CONCEPTS

Config merge

All machines share one config.toml. The sync repo holds an encrypted copy. Each sync merges that copy into the local file, then exports the result.

Three-way merge

Tether compares settings, not bytes. It merges against a base: the synced copy of the last merge, or of the last export once the remote branch holds it. Tether keeps the base in ~/.tether/config.base.toml. That file never syncs.

• Edits to different settings on two machines both stay
• Lists without an order, such as dotfiles.files, dotfiles.dirs and packages.allow_scripts, keep the additions of both machines. Tether writes them sorted
• Ordered lists, such as merge.args, merge as one value
• When both machines change one setting, this machine's value stays and the sync warns. The machines then settle on one value within two syncs
• A machine always keeps its own profile assignment. A profile that a machine is assigned to is never deleted
• A new machine takes the synced config, so its defaults do not replace the settings of your other machines
• The merge edits the local file in place. Comments, layout and keys from a newer Tether stay

Settings for one machine only belong in ~/.tether/local.toml, which never syncs.

Machines on 1.x

Every 2.0 export writes config_writer = 2. A synced config without it counts as a copy from 1.x.

• A 1.x machine drops keys it does not know when it saves, such as dashboard and packages.allow_scripts. In a 1.x copy, a missing key that 1.x does not know keeps its value
• A missing key that 1.x knows is a deletion. So a 1.x machine can still delete a profile or a team
• A 1.x machine before 1.13.2 pushes its old copy of config.toml again after it applies a synced one. That copy reverts the config changes made since, and 2.0 cannot tell it from a real change. Patch or upgrade the 1.x machines, then make the change again

When the synced copy does not read

• A synced config with a newer config_version than this Tether reads does not fail the sync. The local config stays, and the sync warns
• A synced config that does not decrypt or read does not fail the sync either. The sync warns once per copy, skips the merge and the export, and runs the rest
• tether sync --dry-run does not write config.toml