dotfiles-drift

Detect drift between your dotfiles repo and $HOME.

Answer the question: "What changed on my machine that's not in my dotfiles repo, and vice versa?"

Quick Start (5 min)

pip install dotfiles-drift

# Check drift in your dotfiles repo
dotfiles-drift status ~/dotfiles

Typical output shows synced, missing, modified, and orphaned files across your repo and $HOME. Use dotfiles-drift status ~/dotfiles --format json for script-friendly output.

## Why

You keep your dotfiles in a git repo. You clone it onto a new machine. But which files did you forget to add? Which files exist in `$HOME` but not in the repo? Which files have been modified locally without being committed?

`dotfiles-drift` tells you:

| Status | Meaning |
|--------|---------|
| **synced** | Repo and home have identical content |
| **missing** | File exists in repo but not in home (need to symlink/copy) |
| **modified** | File exists in both but content differs |
| **orphaned** | File exists in home but not in repo |

## Install

```bash
pip install dotfiles-drift

Usage

# Check drift status
dotfiles-drift status ~/dotfiles

# Export as JSON
dotfiles-drift status ~/dotfiles --format json

# Sync missing/modified files from repo to home (dry run)
dotfiles-drift sync ~/dotfiles --dry-run

# Actually sync
dotfiles-drift sync ~/dotfiles --force

# Only check git-tracked files
dotfiles-drift status ~/dotfiles --only-tracked

Example Output

Dotfiles Drift — /root/dotfiles
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File          ┃ Status       ┃ Details                            ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ .bashrc      │ synced       │                                   │
│ .gitconfig   │ modified     │ repo=2026-09-12 home=2026-08-30   │
│ .vimrc       │ missing      │ exists in repo, not in $HOME       │
│ .zshrc       │ orphaned     │ exists in $HOME, not in repo       │
└──────────────┴──────────────┴────────────────────────────────────┘

Summary: 1 synced | 1 missing | 1 modified | 1 orphaned

Features

• SHA256 content comparison (not just size/mtime)
• Detects orphaned files (exist in $HOME but not in repo)
• Git-tracked-only mode
• JSON output for scripting
• Dry-run sync mode
• Ignores .git, README.md, LICENSE, Makefile, *.bak, *.swp by default

Security model

dotfiles-drift reads and hashes every file it scans, so it treats the repository you point it at as untrusted input:

• Each file is resolved with Path.resolve() before it is read. A file in the repo must resolve inside the repo; a file in $HOME must resolve inside $HOME or the repo (so symlinks created by tools such as GNU Stow keep working).
• Files that resolve anywhere else, for example a .bashrc -> /etc/shadow symlink in a malicious repo, are skipped and a warning is written to stderr.
• --allow-unsafe-symlinks (on status and sync) turns the check off. Only use it on repositories you trust.
• sync only previews changes unless you pass --force. Review the preview before applying changes from a repo you did not write.
• --dry-run is authoritative: a preview never writes, even when combined with --force. Without either flag, sync previews too.

Alternatives

• GNU Stow — symlink manager, not drift detector
• yadm — dotfiles manager with git, but no drift reporting
• chezmoi — has chezmoi diff but heavier tool
• rcm — rc file management, no content diff

dotfiles-drift is a read-only detector — it reports what's out of sync. You decide whether to symlink, copy, or use a full dotfiles manager.

Sponsoring

dotfiles-drift is MIT licensed and free to use. If it earns a permanent place in your setup, you can support continued maintenance via GitHub Sponsors or by sending SOL to the project treasury wallet:

Eeztv1nCYUt1fwGWpzKC948gaWfjejYCAuLtUMgzDWbW

Funding platforms are configured in .github/FUNDING.yml.

If this tool is useful to you, a star helps other people find it.

Related tools

• driftcheck — detect version drift between docs and toolchain files
• license-drift — detect license drift across a monorepo
• cli-shim — shim CLI flags across tools with different syntax
• sandbox-ffi-layers — layer FFI calls behind a sandbox boundary

Part of a family of focused, single-purpose developer tools — each one does one thing and does it well.

License

MIT