Skip to main content

dotsync

dotsync Python Platform License

Mirror-only dotfiles manager — edit configs in $HOME, mirror them to git, restore on new machines.

Install • Quick start • Commands • Filelist • Test coverage • Docs


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

Command Description
init [dir] Create repo skeleton at ~/.dotfiles (or given path)
track <path> [category] [--encrypt] [--no-auto-update] Add to filelist; mirrors immediately unless --no-auto-update
untrack <path> [--purge-repo] Stop watching; home file kept
encrypt <path> Convert an already-tracked plain path to encrypted
list [categories] [--top-level] List watched paths; each row shows (file|tree, plain|encrypt) plus categories; @tree entries are summarized by directory, not expanded
categories Show category groups from filelist
save [categories] [-m msg] [--dry-run] [--no-push] Expand @tree, mirror home → repo, commit, push
restore [categories] [--remote URL] [--yes] [--skip-pull] [--conflict …] Pull (unless skipped), then repo → home; diff on conflict
update [categories] Mirror home → repo without commit
diff [categories] Show git diff plus pending mirror changes
commit [-m msg] Commit staged repo changes
clean [categories] Remove repo mirrors no longer in filelist
passwd Set or change encryption password
showpw Print stored encryption password (local machine only)

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
ID Area What it verifies
L1 Lifecycle track → save (push) → restore on a fresh machine
L2 Lifecycle untrack removes from filelist; home file kept
L3 Lifecycle untrack --purge-repo deletes mirror
L4 Lifecycle track bootstraps repo when missing
L5a Lifecycle Default track mirrors immediately
L5b Lifecycle track --no-auto-update defers mirror until save
M1 Mirror Home paths stay regular files after save + restore
M2 Mirror Atomic file round-trip is byte-identical
M3 Mirror Nested paths restore as files, not symlinks
RP1 Pull restore pulls remote before copying to home
RP2 Pull Diverged repo aborts restore with no home writes
RP3 Pull --skip-pull uses local HEAD only
RP4 Pull No remote: restore from local HEAD
C1 Conflicts Cancel on diff aborts entire restore
C2 Conflicts Overwrite continues for remaining paths
C3 Conflicts Identical home file skipped without prompt
C4 Conflicts --conflict overwrite --non-interactive
C5 Conflicts --conflict abort --non-interactive
T1 @tree New tree member picked up on second save
T2 @tree Glob excludes non-matching paths
T3 @tree Removed member pruned from repo mirror
T4 @tree Tree save → restore on clean home
S1 Symlinks Internal symlink materialized with manifest
S2 Symlinks External symlink under .dotsync/materialized/
S3 Symlinks Broken symlink skipped cleanly
S4 Symlinks Dedup when link target also watched
S5 Symlinks Restore recreates internal symlink
S6 Symlinks External symlink save → restore round-trip
E1 Encrypt Encrypt track → save → restore
E2 Encrypt showpw prints stored password
E3 Encrypt showpw fails when no password set
B1 Boundaries Empty filelist save is a no-op
B2 Boundaries Declined remote URL aborts save
B3 Boundaries Push failure exits non-zero
B4 Boundaries Binary conflict; cancel leaves home unchanged
B5 Boundaries --no-push durability warning
B6 Boundaries Save without remote exits quickly (no hang)

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

Metadata

Release files for dotsync-cli 2.0.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dotsync-cli 2.0.7
File Size Uploaded Provenance Actions
dotsync_cli-2.0.7.tar.gz 42.1 kB Without provenance Details for dotsync_cli-2.0.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dotsync-cli 2.0.7
File Interpreter ABI Platform Actions
dotsync_cli-2.0.7-py3-none-any.whl Python 3 none any Details for dotsync_cli-2.0.7-py3-none-any.whl

Total release size: 89.9 kB

Release files / dotsync_cli-2.0.7.tar.gz

Download URL dotsync_cli-2.0.7.tar.gz
Size 42.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6d4ee6562b044e72d0e067c8531c192a7179efab3e118e04a3ddc38873133a8b
BLAKE2b-256 checksum
How to use checksums
fe230e3099319e8488f6d670f61a40a0217a2db9649b6633775e26c63df33af0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / dotsync_cli-2.0.7-py3-none-any.whl

Download URL dotsync_cli-2.0.7-py3-none-any.whl
Size 47.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
898e6abdc4cb8561673410a9c8a98ba78478624013df5edbe7f7663e3cb12ad9
BLAKE2b-256 checksum
How to use checksums
cb1139ddcddd2808616b8c0355d33157167b154303821035cbee81b66216bbc2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Security for dotsync-cli 2.0.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page