Metadata-Version: 2.4
Name: dotfiles-drift
Version: 0.2.0
Summary: Detect drift between your dotfiles repo and your actual machine
Author-email: Yunare Maia <yunare@gmail.com>
License: MIT
Keywords: dotfiles,drift,sync,developer-tools,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# 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?"*

[![License](https://img.shields.io/github/license/yunaremaia/dotfiles-drift)](https://github.com/yunaremaia/dotfiles-drift/blob/main/LICENSE)
[![CI](https://github.com/yunaremaia/dotfiles-drift/actions/workflows/ci.yml/badge.svg)](https://github.com/yunaremaia/dotfiles-drift/actions) [![Stars](https://img.shields.io/github/stars/yunaremaia/dotfiles-drift)](https://github.com/yunaremaia/dotfiles-drift) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![Release](https://img.shields.io/github/v/release/yunaremaia/dotfiles-drift)](https://github.com/yunaremaia/dotfiles-drift/releases/latest)

## 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 git+https://github.com/yunaremaia/dotfiles-drift.git
```

> **Not yet on PyPI.** Install from git with the line above. A PyPI release is
> pending; the distribution name `dotfiles-drift` is currently free.

## Usage

```bash
# 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

## Alternatives

- [GNU Stow](https://www.gnu.org/software/stow/) — symlink manager, not drift detector
- [yadm](https://yadm.io/) — dotfiles manager with git, but no drift reporting
- [chezmoi](https://chezmoi.io/) — has `chezmoi diff` but heavier tool
- [rcm](https://github.com/thoughtbot/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:

```text
Eeztv1nCYUt1fwGWpzKC948gaWfjejYCAuLtUMgzDWbW
```

Funding platforms are configured in [`.github/FUNDING.yml`](.github/FUNDING.yml).

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

## Related tools

- **[driftcheck](https://github.com/yunaremaia/driftcheck)** — detect version drift between docs and toolchain files
- **[license-drift](https://github.com/yunaremaia/license-drift)** — detect license drift across a monorepo
- **[cli-shim](https://github.com/yunaremaia/cli-shim)** — shim CLI flags across tools with different syntax
- **[sandbox-ffi-layers](https://github.com/yunaremaia/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
