FAQ
Platforms and setup
Section titled “Platforms and setup”Does dotsync work on Windows?
Section titled “Does dotsync work on Windows?”No. It supports macOS and Linux, on amd64 and arm64. WSL isn’t tested, but it is Linux, so the Linux build should work there; the background agent needs systemd or cron running in the distribution.
Does it need GitHub?
Section titled “Does it need GitHub?”No. Any git remote you can push to works: GitLab, Gitea, Forgejo, Bitbucket, a bare repository on your own server over SSH, even a path on a mounted drive. GitHub is only used by dotsync update and doctor, to find new releases.
Can I use a repository I already have?
Section titled “Can I use a repository I already have?”Use a new, empty repository. dotsync’s layout, manifest.json plus files/, is its own, and init only sets up an empty repository. See Migrate from another tool.
Can it manage files outside my home directory, like /etc/hosts?
Section titled “Can it manage files outside my home directory, like /etc/hosts?”No. Every target must be inside your home directory, and dotsync runs as you, never as root.
Syncing
Section titled “Syncing”How quickly do changes reach the other machines?
Section titled “How quickly do changes reach the other machines?”The machine that made the change sends it on its next sync, and every other machine installs it on its own next sync. With the default five-minute interval, that’s usually within ten minutes while both machines are awake. Run dotsync sync on both ends to make it immediate.
What happens if two machines sync at the same moment?
Section titled “What happens if two machines sync at the same moment?”One push wins. The other is rejected, and that machine redoes its sync on top of the winning commit. If both changed the same file, that file becomes a conflict. Nothing is lost.
What if I’m editing a file while a sync runs?
Section titled “What if I’m editing a file while a sync runs?”dotsync reads each file again right before replacing it. If your save landed in between, it leaves the file alone and picks it up on the next sync. Files are replaced atomically, so your editor never reads a half-written one.
Are permissions synced?
Section titled “Are permissions synced?”The executable bit is, and an entry’s mode, if it has one, is applied whenever dotsync writes the file. Other permissions, owners and timestamps aren’t. Symlinks inside managed directories are synced as symlinks; empty directories aren’t synced.
Can one file differ between machines?
Section titled “Can one file differ between machines?”Not through templating, deliberately. Use per-OS entries, per-machine exclusions, or local include files. See Per-OS and per-machine differences.
How big can managed directories be?
Section titled “How big can managed directories be?”Files over 10 MiB aren’t synced. Directories with thousands of small files work, but dotfiles are rarely that big; keep caches and plugin checkouts out with ignore.
Security
Section titled “Security”Is my data encrypted?
Section titled “Is my data encrypted?”In transit, by git’s SSH or HTTPS connection to your host. At rest, it’s as private as your repository. dotsync doesn’t encrypt anything itself; it keeps secrets out of the repository instead. Files you encrypt yourself, for example with age or sops, sync as ciphertext. See the security model.
Can several people share one repository?
Section titled “Can several people share one repository?”It’s designed for one person’s machines: every machine syncing with a repository gets the same files, and anyone who can push to it controls what lands in everyone’s home directory.
Managing it
Section titled “Managing it”How do I pause syncing on a machine?
Section titled “How do I pause syncing on a machine?”dotsync agent uninstall stops the background agent; dotsync agent install starts it again. Nothing is lost in between: local changes are sent on the next sync. To stop syncing one entry here, dotsync exclude it.
How do I move to a different remote?
Section titled “How do I move to a different remote?”Push the repository to its new home, then on each machine point the cache clone and the configuration at it:
git -C ~/.local/share/dotsync/repo remote set-url origin <new-url>and change remote in ~/.config/dotsync/config.json to the same URL. dotsync doctor checks that the two agree.
Where does dotsync keep its own files?
Section titled “Where does dotsync keep its own files?”Under ~/.config/dotsync, ~/.local/share/dotsync and ~/.local/state/dotsync, plus the binary in ~/.local/bin and the background agent’s definition. Files and locations lists everything.