Introduction
dotsync keeps your dotfiles identical on every Mac and Linux machine you use, without you having to think about it.
You tell it once which files matter, such as ~/.gitconfig, ~/.config/fish/config.fish or all of ~/.config/nvim. From then on you edit those files as usual, on any machine, and a small background job on each machine keeps them in sync through a private git repository.
How it works, in one paragraph
Section titled “How it works, in one paragraph”Your private repository holds a manifest (the list of managed files) and their content. Every few minutes each machine fetches the repository and compares three versions of every managed file: the one on disk, the one in the repository, and the one both last agreed on. If only the repository changed, the machine backs up its copy and installs the new version. If only the local file changed, it pushes it. If both changed, it’s a conflict: dotsync touches nothing and tells you. How sync works has the details.
The problem it solves
Section titled “The problem it solves”Keeping configuration consistent across machines usually means one of these:
- Copying files by hand, and forgetting which machine has the good version.
- A dotfiles repository plus a deploy tool, where every edit is a ritual: edit, commit, push, then pull and apply on every other machine. Skip a step and the machines quietly drift apart.
- Symlinks into a synced folder, which break when an application replaces its config file, and which let one machine’s half-finished edit overwrite everyone else’s.
What dotsync does differently
Section titled “What dotsync does differently”- You edit the real files. There’s no source directory to remember and no apply step.
- It syncs in both directions, automatically. A change flows from whichever machine made it to all the others.
- It’s careful. Every file it replaces or deletes is backed up first. When two machines changed the same file, it doesn’t pick a winner.
- It keeps secrets home. Private keys, cloud credentials and tokens are held back before they reach the repository.
- It has almost no moving parts: one binary,
git, and a repository you already know how to host.
What you need
Section titled “What you need”- Two or more machines running macOS or Linux, on amd64 or arm64
- git 2.20 or newer on each of them
- A private git repository on any host (GitHub, GitLab, Gitea, your own server) that each machine can reach without a password prompt, because the background job can’t answer one
Is it right for you?
Section titled “Is it right for you?”dotsync is a good fit if you:
- use two or more Macs or Linux machines
- want your configuration to simply be the same everywhere
- would rather not run commands to keep it that way
It’s probably not the right tool if you need:
- templating, where one file renders differently per machine. chezmoi is excellent at that. dotsync covers the common cases with per-OS entries, per-machine exclusions and local include files.
- Windows support.
- instant sync. dotsync syncs every five minutes by default, by design.
The comparison with other tools goes into more detail.