Reflink Forest

Reflink Forest is a local, content-addressed Git object store designed to publish complete raw Git workspaces that share Btrfs extents with a derived cache. It is intentionally not a Git worktree implementation or a process sandbox.

The project is in active construction. The durable cold-store foundation is complete, and the current work covers the M2–M8 operational path: offline Git snapshots, verified Btrfs materialization, cache hydration, raw workspaces, daemon recovery, capacity controls, and cold-tier checkpoints. Privileged loop/mount fault injection remains gated to a dedicated Btrfs VM.

Project contracts

• Architecture roadmap
• Format v1
• Implementation plan
• Naming decision
• Workspace ownership decision

Build and test

cargo fmt --check
cargo test --workspace
cargo test -p reflink-forest-index --features rocksdb-backend
# Deterministic malformed-input corpus; runs in ordinary CI without cargo-fuzz.
cargo test -p reflink-forest-format untrusted_decoder_fuzz_corpus
cargo test -p reflink-forest-import untrusted_manifest_decoder_fuzz_corpus
cargo test -p reflink-forest-backup untrusted_backup_decoders_fuzz_corpus

The decoder corpus tests exercise fixed boundary lengths, reproducible pseudo-random byte inputs, and authenticated hostile length/count fields. They are intentionally ordinary unit tests so every CI runner can execute them; each decoder also applies a format-specific input and allocation bound before constructing decoded collections.

For coverage-guided fuzzing, the opt-in fuzz project has cargo-fuzz targets for the record, snapshot-manifest, backup-manifest, and cold-tier-descriptor decoders. It is excluded from normal workspace builds and keeps its deliberately malformed seed corpus under version control.

The runtime clone-domain probe must be run against the planned Btrfs cache and workspace directories, not merely any two paths:

cargo run -p reflink-forest-probe -- /path/to/cache /path/to/workspaces

ficlone: supported means the probe successfully cloned a file and verified that mutating the destination did not alter the source. Any error means that pair of directories is not usable as a Reflink Forest clone domain.

The real loopback Btrfs lifecycle test is deliberately ignored. It creates and formats a disposable image, so run it only on a dedicated VM as root with CAP_SYS_ADMIN and loop-device support:

REFLINK_FOREST_RUN_PRIVILEGED_BTRFS_TESTS=1 \
  cargo test -p reflink-forest-btrfs --test privileged_loopback -- --ignored