Configuration

One list of sites, shared by the command line and the VS Code extension, plus per-machine state that never leaves the computer.

Where things are kept

Settings roam with your user profile; state stays on the machine. sync-servers config path prints the folders in use.

SYNC_SERVERS_HOME moves both: settings to that folder and state to its state subfolder. --config-dir and --state-dir move one for a single command. Folders are created private to you (0700 on Linux and macOS).

The list of sites

sites.json is plain JSON, described by a JSON Schema that editors use for completion. Every write is atomic, keeps the previous version as sites.json.bak, and takes a lock file so two programs never lose each other's changes. A file that does not validate is never rewritten. Edit it with the commands, the terminal interface, sync-servers site edit --editor for one site, or sync-servers config edit for the whole file. Both reopen your editor with the problems listed until the JSON is valid, and config edit works even when the file does not load.

{
  "$schema": "https://isocialpractice.github.io/cmd-sync-servers/schema/site.schema.json",
  "schemaVersion": 1,
  "cloaking": { "patterns": [".git/", "node_modules/"] },
  "sites": [
    {
      "id": "3f2b7c1e-8a4d-4f6b-9c2e-1d5a7b9e0c31",
      "name": "My Site",
      "localRoot": "/home/<user>/sites/my-site",
      "servers": [
        {
          "id": "9a1c3e5f-7b2d-4e6a-8c0f-2b4d6e8a0c13",
          "name": "Production",
          "protocol": "sftp",
          "host": "sftp.example.com",
          "username": "demo-user",
          "auth": { "method": "password", "savePassword": true },
          "remoteRoot": "/var/www/my-site",
          "webUrl": "https://www.example.com/"
        }
      ],
      "remoteServerId": "9a1c3e5f-7b2d-4e6a-8c0f-2b4d6e8a0c13",
      "cloaking": { "patterns": [".psd"] }
    }
  ]
}

Fields left out take their defaults. Passwords never appear in this file. At the top, cloaking.patterns holds the global cloaking patterns, which every site uses before its own; it is written only while it holds a pattern.

Site fields

Server fields

Cloaking

Cloaked files and folders are never scanned, listed, transferred or deleted, on either side. Patterns use the rules of .gitignore files, with one addition for suffixes:

Names are matched ignoring case on Windows and macOS. Single paths can be cloaked too, and cloak everything beneath them:

sync-servers cloak .psd "archive*" node_modules/    # patterns
sync-servers cloak img/raw                          # an existing path in the site
sync-servers cloak --list
sync-servers uncloak .psd

Global patterns

Files that belong to no site, such as version control folders, installed packages and the files an operating system leaves behind, can be cloaked once for every site. Every site uses the global patterns before its own, so a site's !pattern re-includes what a global pattern cloaks, and a pattern that starts with / is anchored at each site's local root. Turning cloaking off for a site turns the global patterns off there too.

sync-servers cloak --global .git/ .github/ node_modules/ .DS_Store Thumbs.db desktop.ini "*.lnk"
sync-servers cloak --global                              # list them
sync-servers uncloak --global .github/
sync-servers cloak --site "My Site" --ignore-global      # one site stops using them
sync-servers cloak --site "My Site" --use-global         # and uses them again

No global pattern is built in. The list above is a starting point for a typical web site; keep only what your sites never publish. In the terminal interface, c on the Sites screen edits the global patterns, and Site Setup's Cloaking category shows them beside a Use global patterns switch.

The sensitive-file guard

Some files are almost never meant to be published. A file matching one of these patterns is listed in the preview unchecked with the pattern it matched, and moves only when you check it. It is never hidden.

.env  .env.*  *.pem  *.key  *.p12  *.pfx  *.kdbx  id_rsa*  id_ecdsa*  id_ed25519*
.git/  .hg/  .svn/  .ssh/  .aws/  .npmrc  .pypirc  .netrc  *.sqlite-journal

Add patterns of your own in sync.guard.patterns or the Security category of Site Setup. Unattended runs with --yes never transfer a guarded file.

Symbolic links

A site's local folder can hold symbolic links and, on Windows, junctions. sync.symlinks says which of them the site follows. Set it with sync-servers site edit --symlinks, in the Synchronization category of Site Setup, or with sync-servers config edit.

A followed link is synchronized as what it points to, so the server gets ordinary files and folders, never a link:

• A file link is a file at the link's path. A Put sends the file it points to; a Get writes that file and keeps the link.
• A folder link is a folder whose files are listed under the link's path. A file inside it is a file of the folder the link points to, so a Get or a delete changes it there.
• A local delete of a path that is itself a link removes the link, never what it points to, and the recovery folder keeps a copy of the content.
• A folder that is a link is never removed when a delete leaves it empty.
• Two names for one file, such as a link and the file it points to, are two paths of the site. Both are put, and a Get through one changes the other, which the next sync puts too. Rows on one file run one at a time.
• Cloaking and the guard see through links: a link to a cloaked file or folder is cloaked, and a link to a file such as .env is held back like the file.

Never followed: links on the server, links to something that does not exist, links back into a folder above them, and, with follow-inside-root, links that lead out of the site. Each is a problem row that says why; see Link problems.

With follow, a Get or a delete through a link that leads out of the site changes a file outside the site's folder, and the preview says so on each such row. A link to a large folder makes every scan read all of it, so cloak what the site does not need. A local root that is itself a link is followed with every value.

On Windows, junctions and symbolic links both count. Creating a junction needs no privilege; creating a file symbolic link needs Developer Mode or an administrator. Shortcuts (.lnk files) are ordinary files, not links. In cmd.exe, from the site's folder:

mklink /J fonts C:\Users\<user>\Shared\fonts
mklink css\theme.css C:\Users\<user>\Shared\theme\theme.css

On macOS and Linux:

ln -s ~/shared/fonts fonts
ln -s ~/shared/theme/theme.css css/theme.css

Secrets

Passwords and key passphrases are never written to a file. When a connection needs one, it is looked for in this order:

1. The operating system's credential store, when the server has savePassword on: Windows Credential Manager, the macOS Keychain, or the Secret Service keyring on Linux. Entries use the service sync-servers.
2. The environment: SYNC_SERVERS_PASSWORD, or SYNC_SERVERS_KEY_PASSPHRASE for a key.
3. A question in the terminal, typed without being shown. With nobody to ask, the run fails with E_AUTH.

sync-servers password set Production --site "My Site"     # save it
printf %s "$SECRET" | sync-servers password set Production --stdin
sync-servers password forget Production                    # remove it

A secret is asked for only after the server's host key or TLS certificate has been verified, and it is removed from every log and error message. A saved secret is tied to the protocol, address, port and user it was saved for; after any of them changes, it is no longer sent and you are asked again, so save it again with password set. SYNC_SERVERS_KEYRING=off turns the credential store off.

Environment variables

Which site a command means

A command acts on the site named by its argument or --site, then SYNC_SERVERS_SITE, then the site whose local folder holds the current folder (the deepest one when sites are nested). In a terminal, you are otherwise asked to choose; in a script, the command stops with a usage error that lists the sites.