Varn

Local state checkpointing and rollback system.

Varn captures a known state of your local filesystem, lets you observe what changed, and safely restores a previous state.

It is designed primarily for AI agents and automated tools operating on a local machine, but is equally useful for humans who want to safely experiment with local changes.

"An automated process changed my local environment. What exactly changed, and can I safely return to the previous state?"

What Varn Is Not

Varn is not Git. It does not implement branches, remotes, commits, rebases, merges, pull/push, or Git-compatible history. Varn complements Git — Git tracks project/source history; Varn protects local state.

Quick start

varn init
varn checkpoint "before changes"
# ... make changes ...
varn diff <checkpoint-id>
varn restore <checkpoint-id>

See installation instructions to get started.

Commands

varn init [path]           Initialize Varn in a directory
varn init --gitignore      Also add .varn/ to the root .gitignore
varn checkpoint <desc>     Capture the current filesystem state
varn list                  Display available checkpoints
varn diff <checkpoint>     Compare current state with a checkpoint
varn restore <checkpoint>  Restore a checkpoint
varn gc                    Remove unreferenced objects from the store
varn migrate               Migrate storage format to current version
varn --json <command>      Emit machine-readable JSON output

See the CLI usage reference for details.

Features

• Content-addressed storage with SHA-256 hashing and deduplication
• Symlink scanning and full restoration
• Hard link detection and restoration (Unix and Windows/NTFS)
• Full permission mode restoration (Unix), file attributes (Windows)
• BSD file flags restoration (macOS: uchg, hidden, ...)
• Owner/ACL restoration: uid/gid (Unix), security descriptors (Windows)
• mtime restoration (all platforms)
• Conflict detection with explicit confirmation
• Safety checkpoint before restore (undo a bad restore)
• Idempotent checkpointing (same state = same ID, no duplicates)
• Incremental scanning with persistent mtime/size cache
• Content streaming for large files (no full file in memory)
• Ignore patterns via .varnignore (gitignore-style syntax)
• Storage format migration framework (varn migrate)
• Garbage collection with --dry-run
• Git coexistence: the store is automatically gitignored (.varn/.gitignore), so git add -A never stages Varn's objects
• --json output for AI agent integration
• Linux, macOS, and Windows support

Platform support

Platform	Status
Linux	Officially tested — full CI matrix (build, clippy, 440+ tests) on every commit
Windows	Officially tested — full CI matrix on every commit, plus field-tested on Windows 11 / NTFS
macOS	Best-effort — full CI matrix on every commit; macOS shares the Unix code paths with Linux (mode bits, ownership, symlinks), so coverage is substantially equivalent, but we do not currently run dedicated macOS hardware tests

Every commit runs the complete test suite (442 tests) on ubuntu-latest, windows-latest, and macos-latest, so all three platforms compile and pass the same regression suite continuously. The distinction above is about dedicated human field testing, not CI coverage.

Limitations

No extended attributes (xattr), no ACL restoration, no concurrent scanning, no streaming restore, no incremental restore. See FUTURE.md for the full list.

Documentation

• Install — get Varn running
• CLI usage — command reference
• Safety model — guarantees and restore pipeline
• Architecture — internals and design decisions
• Future work — planned features and known limitations
• Contributing — how to contribute
• Changelog — version history

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release

Regression tests

tests/regression/ is the canonical home for field-report regressions, organized by platform so every bug from every OS has a permanent, named test:

tests/regression/
├── main.rs        # suite root
├── common/        # cross-platform helpers
├── common_*.rs    # cross-platform bugs (cache, IDs, restore, storage, ...)
├── windows/       # Windows-only (attributes, ACLs, hard links, junctions)
├── macos/         # macOS-only (BSD flags, symlinked temp dirs)
└── linux/         # Linux-only (mode bits, uid/gid, POSIX locks/symlinks)

When fixing a bug, add a named regression test here first — it documents the failure and prevents it from ever coming back.

License

MIT OR Apache-2.0