Warning: Experimental repository
This repository is experimental and is not ready for use. We are exploring a variety of ideas here, and behavior, interfaces, and implementation details may change without notice.
rift: better alternative to git worktrees
- copy on write (saves space)
- instant (< 0.1s on 10gb folder)
- fast cli
- use as FFI lib with bun or node
mac and linux+btrfs for now more support soon
npm install -g rift-snapshot
# or
bun add -g rift-snapshotRelease archives are available from GitHub Releases.
| Platform | Backend | Behavior |
|---|---|---|
| Linux x64 | Writable btrfs snapshots | rift init converts an ordinary directory into a btrfs subvolume. |
| macOS arm64 / x64 | APFS clonefile |
rift init registers the source directory. |
| Windows x64 | None | The package is published; workspace creation is not implemented. |
cd ~/code/app
rift initrift init selects an existing Rift root above the current directory, or the nearest Git root when no Rift root exists. Use --here to initialize exactly the selected directory.
On Linux, first initialization of an ordinary btrfs directory performs a reflink import into a new btrfs subvolume and swaps it into the same path. If the selected root is registered already, no conversion occurs. If its .rift marker is missing, rift init restores it and completes any required conversion.
rift create
rift create --name parser-fix
rift create --into /fast/riftsrift create searches upward for .rift, copies that managed workspace, records the immediate parent, and prints the new workspace path to stdout.
On Linux, it creates a writable btrfs snapshot. On macOS, it uses APFS clonefile.
When the workspace is a Git repository, the new workspace has detached HEAD and retains index and working-tree state.
rift list
rift ancestorslist prints direct active child workspaces. ancestors prints parent workspaces, nearest first.
rift remove # trash the current created rift subtree
rift remove -f ~/code/app # unregister a source root
rift remove --children ~/code/app # trash descendants, preserve the selected workspace
rift gc # physically delete trash and prune missing entriesRemoving a created rift moves its active subtree into adjacent .trash storage. rift gc deletes that storage later.
Removing a source root requires -f in the CLI. The source directory remains on disk. Its .rift marker is removed. Existing registered descendants are moved into trash. Missing descendants are removed from the registry.
eval "$(rift shell-init zsh)" # or bashThe shell wrapper changes directory after init conversion, create, or removal of the current created rift.
Each managed workspace has a .rift marker containing its identifier. An SQLite registry stores paths, parent identifiers, and trash entries.
Default created-workspace storage is adjacent to the registered source root:
~/code/app/ source workspace
~/code/.rifts/app/parser-fix/ created workspace
~/code/.rifts/app/.trash/ removed workspace storage
The package selects a Bun or Node FFI binding through conditional exports.
import { create, list, remove, gc } from "rift-snapshot";
const workspace = create({ from: process.cwd(), name: "schema-work" });
console.log(list({ of: process.cwd() }));
remove({ at: workspace });
gc();The Node binding requires the experimental FFI API in Node.js 26.1 or later:
node --experimental-ffi app.mjsWith Node's permission model, also pass --allow-ffi.
init(options?: { at?: string; database?: string }): null
create(options?: { from?: string; name?: string; into?: string; database?: string }): string
remove(options?: { at?: string; all?: false; database?: string }): void
remove(options: { at?: string; all: true; database?: string }): string[]
list(options?: { of?: string; database?: string }): string[]
ancestors(options?: { of?: string; database?: string }): string[]
gc(options?: { database?: string }): string[]The JavaScript init function initializes exactly at; Git-root selection and --here are CLI behavior.
Operation failures throw RiftError with a code and, when relevant, path.
cargo test --workspace --locked
./scripts/install.shscripts/install.sh installs an optimized CLI binary to ${CARGO_HOME:-$HOME/.cargo}/bin/rift.
Benchmark a single real rift create operation against a directory:
cargo bench --bench create -- /path/to/linuxThe benchmark initializes the supplied directory before timing, times only creation of the new rift, and then removes the created workspace outside the measured interval. On first use, initialization of an ordinary Linux btrfs directory converts it into a subvolume before measurement. The benchmark uses the production filesystem strategy, so results on macOS measure APFS cloning and results on Linux require and measure btrfs snapshots.
Establish a baseline by measuring multiple independent rift creations and writing an aggregate machine-readable result file. Keep results outside the source workspace so they do not alter future measurements:
cargo bench --bench create -- /path/to/linux --samples 10 --output /path/to/results/baseline.jsonThe JSON result includes each timing sample and the median, minimum, and maximum elapsed time. A future experiment loop can run the same command in candidate workspaces and compare their median results to this baseline.
Compare multiple candidate rift code workspaces that contain this benchmark target:
cargo bench --bench compare -- /path/to/linux \
--candidate /path/to/rift-baseline \
--candidate /path/to/rift-candidate-a \
--candidate /path/to/rift-candidate-b \
--samples 10 \
--output /path/to/results/create-run-01The comparison runner invokes each candidate's optimized create benchmark against the same workload, writes candidate-01.json, candidate-02.json, and so on, then writes summary.json with candidates ranked by median creation time. Include the unchanged workspace as one candidate when you need a baseline in the ranking.
MIT