Settings

Two layers: settings that apply to the whole process, and configuration that applies to one repo. The process layer is read through Object::Configure, so a file, a universal section and environment variables can each contribute; the repo layer is plain JSON written by the tools.

Process settings

The settings file is ~/.conf/app-filesync.json when it exists, or the path in FILESYNC_SETTINGS. The section key is App__FileSync, and a UNIVERSAL section in the same directory applies to every class that uses Object::Configure. Environment variables named App__FileSync__KEY override the file.

# ~/.conf/app-filesync.json
{ "App__FileSync": {
    "log_level"       : "debug",
    "log_format"      : "%level%: %message%",
    "log_file"        : "/home/foo/.filesync/filesync.log",
    "ssh_identity"    : "~/.ssh/filesync_ed25519",
    "ssh_known_hosts" : "~/.ssh/filesync_known_hosts",
    "server_command"  : "/usr/local/bin/filesync-server"
} }

# or, for one run
export App__FileSync__log_level=debug

Command output — sync summaries, plans, --json — is written to standard output by the commands themselves. The logger carries diagnostics on standard error, so a cron job can separate the two. --verbose raises the level to debug and --quiet lowers it to error for that run, overriding the file.

Precedence

Lowest to highest:

1. the built-in default;
2. the UNIVERSAL section;
3. the App__FileSync section of the settings file or FILESYNC_SETTINGS;
4. the environment variables (universal ones first, class ones last);
5. --verbose or --quiet on the command line, which describe this run only.

For a repo, a value recorded by filesync init — --identity, --known-hosts, --server-command — wins over the process setting, so one machine can point at another identity without repeating the common settings. port and host_key_checking exist per repo only: there is no process-wide layer, and ssh's own default applies when the repo leaves them out.

Where a value came from

filesync settings prints every effective value together with the layer that supplied it, which is usually faster than reconstructing the merge by hand:

$ filesync settings
settings file: /home/foo/.conf/app-filesync.json

log_level        debug                 /home/foo/.conf/app-filesync.json [App__FileSync]
log_format       %level%: %message%    built-in default
log_file         /home/foo/f.log       App__FileSync__log_file
ssh_identity     ~/.ssh/id_ed25519     built-in default
ssh_known_hosts                        built-in default
server_command   /usr/local/bin/filesync-server  /home/foo/.conf/app-filesync.json [App__FileSync]

The source is reported as default, file, env, merged or repo in the JSON form. A value that no modelled layer accounts for is reported as merged rather than claimed as a default. filesync settings --config FILE reads another settings file, and --json returns the report as data.

Client configuration

The client keeps one JSON file listing its repos, ~/.filesync/config.json or the path in FILESYNC_CONFIG. filesync init writes it atomically; editing it by hand is fine, but keep the ids plain.

{
  "version"   : 1,
  "client_id" : "laptop",
  "ssh"       : { "command" : "ssh", "extra_args" : [] },
  "repos"     : {
    "documents" : {
      "root"          : "/home/foo/Documents",
      "transport"     : "ssh",
      "server"        : "foo@srv",
      "role"          : "client",
      "identity"      : "~/.ssh/filesync_ed25519",
      "known_hosts"   : "~/.ssh/filesync_known_hosts",
      "server_command": "/home/foo/bin/filesync-server-home",
      "snapshot_mode" : "hardlink"
    }
  }
}

A configuration written by a newer release is read as-is: unknown keys are kept and ignored, and there is no schema version check beyond version. A missing file is an empty configuration rather than an error.

Server repo policy

Each repo has a policy at ROOT/.filesync/repos/REPO/config.json, created by filesync-admin repo create and printed by repo show. It holds the retention and deletion limits, the ignore list, and the admitted clients.

{
  "version"            : 1,
  "name"               : "documents",
  "created"            : "2026-10-23 19:44:45 UTC",
  "trash_days"         : 30,
  "max_deletes"        : 200,
  "max_delete_percent" : 10,
  "conflicts"          : "inline",
  "preserve_mode"      : true,
  "allow_symlinks"     : false,
  "clients"            : { "laptop" : { "role" : "client" } },
  "ignore"             : [ ".filesync-root", ".filesync-tmp-*",
                           ".filesync-snapshots", "*.swp", "*~", ".#*",
                           "#*#", ".DS_Store", "._*", "Thumbs.db",
                           "desktop.ini", "*.crdownload", "*.part" ]
}

The reserved entries are not negotiable: the root marker, temporary files and snapshots must never enter a manifest, so they are excluded whatever the policy says.

Paths