Quick start

In this tutorial you’ll connect two machines, share a file and a directory between them, and watch a change travel from one to the other. It takes about five minutes.

You’ll need two macOS or Linux machines with dotsync installed, and an account on GitHub, GitLab, Gitea or any other git host. The examples call them laptop (a Mac) and desktop (a Linux machine).

1. Create a private repository

1. On your git host, create a new, empty, private repository, for example dotfiles. Don’t add a README or a license: dotsync sets the repository up itself.

   Caution

   Keep it private. dotsync blocks common secrets, but configuration files still reveal things like hostnames, email addresses and internal URLs.

2. Check that git can reach it without asking for anything. The background agent has nobody to type a password or passphrase:

   git ls-remote git@github.com:you/dotfiles.git

   Any output, or none, is fine. A prompt is not: see git access without prompts.

2. Set up the first machine

1. On the laptop, point dotsync at the repository:

   laptop

   $ dotsync init git@github.com:you/dotfiles.git
   cloning git@github.com:you/dotfiles.git ...
   remote is empty; creating the manifest
   installed ~/.local/bin/dotsync
   dotsync: in sync (0 files)
   automatic sync: launchd agent io.github.dotsync, every 300s

   init cloned the repository, wrote the manifest (the list of managed files) to it, and installed a background agent that syncs every five minutes. Check that everything is healthy:

   laptop

   $ dotsync doctor
   dotsync doctor
     ✓ dotsync 0.5.0 (ed63c37, 2026-09-21T06:18:53Z) go1.27.1 darwin/arm64
     ✓ git version 2.50.1 (Apple Git-155)
     ✓ configuration: ~/.config/dotsync/config.json
         remote git@github.com:you/dotfiles.git, branch main
     ✓ remote reachable without prompts
     ✓ background agent: launchd agent loaded
     ✓ last sync 0s ago (ok)
     ✓ 0 managed entries, 0 files
     · backups: 0 file(s), 0 B in ~/.local/state/dotsync/backups (older than 90 days are pruned)
   
   Everything looks good.

   Every line should start with ✓ or ·. Anything marked ✗ or ! comes with a → line saying how to fix it. The usual culprit is git needing a password it can’t ask for.

2. Choose what to manage. Start with one file and one directory:

   laptop

   $ dotsync add ~/.gitconfig -d "Git identity and aliases"
   managing ~/.gitconfig as 'gitconfig'
     sent      ~/.gitconfig
   dotsync: 1 sent — pushed 3f2a9c1
   
   $ dotsync add ~/.config/nvim -d "Neovim" --ignore lazy-lock.json
   managing ~/.config/nvim as 'nvim'
     sent      ~/.config/nvim/init.lua
     sent      ~/.config/nvim/lua/plugins.lua
   dotsync: 2 sent — pushed 8b1d0e4

   -d sets the description shown by status. --ignore keeps a file inside the directory out of sync, here the plugin lock file that each machine writes for itself.

3. See what’s managed:

   laptop

   $ dotsync status
   dotsync on laptop: git@github.com:you/dotfiles.git (main @ 8b1d0e4)
   last sync: 2026-09-21T10:15:02+05:30 (ok)
   automatic sync: launchd agent loaded
   
   SOURCE     TARGET           STATUS  DESCRIPTION
   gitconfig  ~/.gitconfig     ok      Git identity and aliases
   nvim       ~/.config/nvim/  ok      Neovim

3. Set up the second machine

1. On the desktop, run the same init:

   desktop

   $ dotsync init git@github.com:you/dotfiles.git
   cloning git@github.com:you/dotfiles.git ...
   installed ~/.local/bin/dotsync
     updated   ~/.gitconfig  (previous version saved to ~/.local/state/dotsync/backups/20260921-101730-4242/.gitconfig)
     updated   ~/.config/nvim/init.lua
     updated   ~/.config/nvim/lua/plugins.lua
   dotsync: 3 updated
   existing local files that were replaced are saved under ~/.local/state/dotsync/backups
   automatic sync: systemd user timer dotsync.timer, every 300s

   Your files are here. The desktop already had a .gitconfig of its own, so dotsync backed it up before replacing it.

   Tip

   To review differences before anything is replaced, run dotsync init --keep-existing instead. Every existing file that differs then becomes a conflict for you to settle, one by one.

4. Watch a change travel

1. On the desktop, change a managed file and sync straight away instead of waiting for the agent:

   desktop

   $ git config --global alias.st status      # edits ~/.gitconfig
   $ dotsync sync
     sent      ~/.gitconfig
   dotsync: 1 sent — pushed 51c7e02

2. On the laptop, the agent installs it within five minutes. To get it now:

   laptop

   $ dotsync sync
     updated   ~/.gitconfig  (previous version saved to ~/.local/state/dotsync/backups/20260921-102204-5120/.gitconfig)
   dotsync: 1 updated

That’s the whole workflow. From now on, just edit your files.

What you’ve learned

• dotsync init <url> connects a machine and starts its background agent.
• dotsync add <path> manages a file or directory on every machine, from whichever machine you run it on.
• Changes sync both ways on their own, and every file dotsync replaces is backed up first.
• dotsync doctor checks the setup; dotsync status shows every file.

Where to next

• Manage files and directories: ignore patterns, descriptions, permissions, and how to stop managing something.
• Resolve conflicts: what happens when two machines edit the same file.
• How sync works: the model behind all of this.