Riftri

Lightweight Git workspaces for parallel development.

Riftri creates real Git worktrees without eagerly storing another full physical copy of every unchanged project file. It is designed for developers and coding agents working on several tasks at once.

Warning

Riftri is experimental, pre-release software. Keep important work committed or backed up. Optimized worktree operations require a writable APFS volume on macOS, Btrfs/reflink-enabled XFS or OverlayFS on Linux, or ReFS on Windows. OverlayFS requires either an already mount-capable namespace or the explicit system helper described below. Broader Windows filesystem support is still in development.

Why Riftri?

Git linked worktrees share repository history, but each worktree normally gets its own complete checkout. That can consume significant disk space when several developers or agents work on a large repository in parallel.

Riftri keeps normal Git behavior while making those checkouts lightweight:

• Every workspace is a real Git linked worktree.
• Unchanged files share native copy-on-write storage blocks.
• Changes remain private to each worktree.
• Editors, build tools, and agents use ordinary files and Git commands.
• Interrupted creation and cleanup operations can be recovered safely.

Riftri does not replace Git, manage branches, or sit between applications and the filesystem.

Installation

On macOS or Linux, install the standalone native CLI with Bash:

curl -fsSL https://riftri.vercel.app/install.sh | bash

The installer verifies SHA-256, checks the binary version, and installs to ~/.local/bin. Follow its printed PATH command to use it in your current shell. It does not edit shell profiles, use sudo, or activate Git interception. Read the script before running it, or download it for review first as described in the installation guide.

For Windows or manual installation, download the standalone native CLI from GitHub Releases. Choose your OS and architecture, verify the archive against SHA256SUMS, and install it in a per-user directory. Node.js and npm are not required. See the direct-download installation guide for all eight targets and copyable checksum-verification commands.

The npm launcher is a separate distribution channel. Confirm that the requested version is present on npm because GitHub and npm publication complete independently. To install a published npm version:

$ npm install --global riftri
$ riftri doctor

Or build it from source:

$ cargo build --release -p riftri-cli
$ ./target/release/riftri doctor

The npm package is a small launcher for the same prebuilt Rust binary. Builds are provided for macOS, Linux, and Windows, but optimized worktree creation is currently available on APFS, supported Linux reflink volumes, caller-visible OverlayFS mounts, and ReFS, subject to the selected release's capabilities. Installing the Windows CLI on NTFS does not add an NTFS worktree backend.

Quick start

Check whether the current repository and destination are compatible:

$ riftri doctor --destination ../app-auth

The readiness summary names the backend Riftri would select, confirms whether copy-on-write is available, reports OverlayFS helper state when relevant, and gives the next command or a concrete remedy. The check does not create Riftri state or Git worktree metadata.

Create an optimized worktree explicitly:

$ riftri worktree add ../app-auth -b feature/auth main
$ cd ../app-auth
$ git status

The new directory behaves like any other Git worktree. Riftri shares unchanged data through an immutable native base; files allocate private storage as they are changed.

Use normal git worktree commands

Activate Riftri's Git shim in the current shell, then enable each repository that should use optimized worktrees:

$ eval "$(riftri shell hook zsh)"
$ cd app
$ riftri enable
$ git worktree add -b feature/auth ../app-auth main

The shell hook may be added to your shell profile if you want it available in every new shell. This does not enable Riftri for every repository: riftri enable is still required in each repository. Commands in repositories that are not enabled go directly to the real Git executable. Riftri never edits shell startup files automatically.

For a single agent or command tree, use process-scoped activation instead:

$ riftri enable
$ riftri exec -- claude

Use riftri disable to opt a repository out. Use riftri shell status to inspect activation, or deactivate the shim in the current shell with:

$ eval "$(riftri shell deactivate zsh)"

See Global shell activation for shell setup, compatibility details, and edge cases involving IDEs, containers, aliases, and Git wrappers.

Supported today

On macOS with APFS, Linux with Btrfs or reflink-enabled XFS, and Windows with ReFS, Riftri supports:

• Optimized creation of real linked worktrees.
• Repository-scoped and process-scoped Git interception.
• Clean worktree removal, move, and prune operations.
• Reusable immutable bases with disk-usage reporting.
• Journaled recovery, repair, and garbage collection.
• Safe compatibility checks before any worktree is created.

Linux OverlayFS is also available experimentally when the add-time probe proves that the current mount namespace can host a persistent view. On a normal Linux shell without mount capability, install Riftri's narrow helper once:

$ sudo riftri overlayfs install-helper

The helper is available system-wide, but it does not intercept Git or enable any repository. riftri enable remains a separate per-repository choice. The root-owned helper accepts only validated OverlayFS mount, exact identity-checked unmount, and disposable work-directory reset requests for directories owned by the calling user; capability-probe files remain owned and verified by that user; Git, agents, editors, builds, and normal file access continue to run without elevation. Use --replace when upgrading an existing helper.

OverlayFS supports the same real-worktree creation, clean removal, isolation, crash recovery, and explicit repair after a reboot. Mounted-view moves are rejected before mutation. If neither reflinks, a mount-capable namespace, nor a valid helper is available, Riftri stops before mutation and never silently creates a full-copy worktree.

Riftri deliberately stops with a clear explanation when a checkout cannot yet be reproduced safely—for example, repositories using Git LFS, custom filters, sparse checkout, submodules, or external attributes. It never silently replaces an optimized operation with a full worktree copy.

Useful commands:

$ riftri doctor
$ riftri status
$ riftri repair
$ riftri gc
$ riftri gc --apply
$ riftri state forget-missing /absolute/path/to/removed-state

Automation can add --json-errors anywhere in a command. A failure is then written to stderr as one versioned JSON receipt with a stable code, category, operation, optional durable phase, cleanup disposition, and recovery guidance. Normal successful output and default human-readable errors are unchanged.

If a custom state directory was removed outside Riftri, lifecycle interception continues to fail closed. Remove that exact stale repository-local registration explicitly with riftri state forget-missing; existing state directories are never accepted by this command.

How disk sharing works

Riftri prepares one immutable base for an exact Git tree. It creates native APFS clones, Linux reflinks, or ReFS block clones from it, or exposes it as an OverlayFS lower layer with a private writable upper. Unchanged contents are not materialized again; worktrees are lightweight—not free—and private disk use grows as they diverge.

riftri status reports managed views and filesystem-accounted allocation. For details on measuring physical sharing, see APFS allocation evidence and Linux reflink verification, or see Windows ReFS support for that backend's requirements. The tested metadata guarantees and platform boundaries are documented in Backend guarantees and metadata profiles, with the detailed integration cases in Filesystem metadata compatibility.

Project status

The macOS/APFS, Linux reflink, Linux OverlayFS, and Windows/ReFS implementations include worktree creation, process-scoped Git interception, lifecycle recovery, cleanup, and disk accounting. Broader checkout compatibility, ordinary Windows filesystem alternatives, and managed environments remain roadmap work.

Development plans and design details live in:

• Project definition
• Roadmap
• Architecture
• Design decisions
• Backend guarantees
• Native COW benchmark
• Release process

Contributing

Run the complete local quality gate before opening a pull request:

$ cargo fmt --all --check
$ cargo clippy --workspace --all-targets --all-features -- -D warnings
$ cargo test --workspace
$ npm test
$ npm run smoke:installed

The installed-package smoke test packs both npm artifacts, installs them into an isolated global prefix without registry access, and exercises the resulting riftri command. Native-backend CI also runs the complete add, edit, remove, status, and collection workflow from that installed command.

Riftri is licensed under the Apache License 2.0.