dotsync

dotsync watches paths under your home directory, copies their content into a git repo (default ~/.dotfiles), and pushes to a remote. Config files stay as regular files in $HOME — the repo is a mirror, not a symlink farm. Use categories to sync subsets of your dotfiles per machine; use @tree lines to watch whole directories that grow over time.

Installation

Quick install (installs uv if needed; first run ~30s, then instant):

curl -fsSL https://raw.githubusercontent.com/HarveyGG/dotsync/main/install.sh | bash

Homebrew:

brew tap HarveyGG/tap
brew install dotsync

pip:

pip install dotsync-cli

Requires git. Runtime uses uv to resolve the CLI (handled by the install methods above).

Quick start

Machine that already has your configs:

dotsync track ~/.zshrc shell
dotsync track ~/.config/nvim editor
dotsync save    # mirror → commit → push (prompts for remote on first push)

New machine:

dotsync restore
# or non-interactive:
dotsync restore --remote git@github.com:you/dotfiles.git --categories shell,editor --yes

track bootstraps ~/.dotfiles and git init on first use. restore clones (or uses an existing repo), pulls latest, then copies mirrors back to $HOME.

Filelist

Watch rules live in ~/.dotfiles/filelist:

# path:category[,category...]  optional |encrypt
.zshrc:shell,common
.ssh/config:tools|encrypt

# whole directory — re-scanned on every save
@tree:.config/nvim:editor
@tree:.local/share/my-app/custom-*:tools

# host → category groups (optional)
macbook=shell,editor,common

• Atomic paths — single files tracked with dotsync track <file>.
• @tree — whole directories; dotsync track <dir> adds a @tree line. New files under the pattern are picked up on the next save. Globs supported (*, ?, […]).
• Symlinks inside trees — targets are materialized into the repo (internal links keep layout; external targets go under .dotsync/materialized/).

Commands

Common flags: --non-interactive, --dry-run, --encrypt, --keep-going.

Full reference: ReadTheDocs.

Test coverage

295 tests total (37 black-box E2E scenarios against the real CLI in an isolated sandbox). All scenarios below pass on v2.0.5.

uv run pytest tests/blackbox/ -v
uv run pytest tests/ -v

Scenario details: tests/blackbox/test_plan.md.

Contributing

git clone https://github.com/HarveyGG/dotsync.git && cd dotsync
uv sync
uv run pytest tests/

Pull requests welcome.

License

Non-Commercial License — free for personal, educational, and non-profit use. See LICENSE. Commercial use requires permission: harvey.wanghy@gmail.com

Links

• Documentation
• Issues
• PyPI