Rift Documentation

Pages

1. OverviewWhat Rift exposes (CLI, npm package, FFI), supported platforms and backends, and the shortest path from init to create.
2. InstallationInstall via npm/bun global package or Cargo build script; platform support matrix and prebuilt binary layout.
3. QuickstartInitialize a source workspace, create a filtered copy-on-write child, list it, and remove it with expected stdout signals.
4. Workspaces and registryManaged workspace model: ULID identity, `.rift` markers, SQLite registry schema, parent-child provenance tree, and upward resolution.
5. Copy strategies and platformsPlatform-specific copy-on-write backends (btrfs subvolumes, Linux reflinks, APFS clonefile), filtered vs exact copy modes, and unsupported platforms.
6. Storage layoutDefault `.rifts` sibling storage, custom `--into` paths, trash relocation naming, and central SQLite database location.
7. Git integrationGit repository detection, detached HEAD behavior, marker exclusion, unsafe source states, and preserved index/working-tree semantics.
8. Initialize a workspaceRun `rift init` with Git-root vs `--here` selection, btrfs subvolume conversion progress, marker restoration, and success signals.
9. Create workspacesCreate child workspaces with `--name`, `--into`, filtered vs `--copy-all` copy, `--no-hooks`, random name generation, and Git preparation.
10. Manage and remove workspacesList children, trace ancestors, remove created rifts to trash, unregister source roots with `-f`, `--children` mode, and `rift gc` physical deletion.
11. Shell integrationInstall Bash, Zsh, or Nushell wrappers via `rift shell-init` for automatic `cd` after init, create, and remove operations.
12. Postcreate hooksConfigure `.rift.toml` v1 postcreate hooks, hook environment variables, sequential execution, and failure behavior after workspace registration.
13. CLI referenceAll `rift` subcommands, flags, defaults, stdout/stderr behavior, hidden `--database` and `--shell-cwd` flags, and exit codes.
14. JavaScript API reference`rift-snapshot` exports, Bun vs Node conditional bindings, FFI request protocol, function signatures, and Node.js 26.1+ FFI requirements.
15. Configuration reference`.rift.toml` schema: `version`, `hooks.postcreate` array, validation rules, and CLI/API hook skip flags.
16. Error codesComplete `RiftError` code catalog from FFI and TypeScript bindings, CLI user-facing messages, and path-bearing error variants.
17. TroubleshootingCommon failure modes: uninitialized workspaces, missing markers, CoW unavailable, unsafe Git state, hook failures, and platform limitations.
18. DevelopmentBuild and test the Rust workspace, install the CLI locally, CI test matrix, and filesystem integration test environment variables.
19. BenchmarkingMeasure `rift create` performance with `create` and `compare` Cargo benches, sample counts, JSON output schema, and candidate comparison workflow.