Skip to content
leosteraPublic

About

lightweight git-worktrees for agents

Topics

Resources

Stars

245 stars

Watchers

0 watching

Forks

Repository files navigation

git twig 🌱

With twig, your agents can create cheap lightweight worktrees and use up to 97% less space on disk. Imagine all the worktrees you could now make!

Install

brew tap leostera/git-twig https://github.com/leostera/git-twig
brew install leostera/git-twig/git-twig

Or install from crates.io with Rust 1.95+ and Git 2.40+:

cargo install git-twig --locked

For local development: cargo install --path crates/git-twig --locked.

Use

With your source checkout in main/:

git -C main twig new -b feat/x ../feat-x HEAD
git -C main twig list

Released v0.4.0 requires the source checkout's current HEAD. Development builds can reuse matching files from nearby worktrees for other revisions too. Short help works outside a checkout: git twig -h or git twig new --help.

For coding agents: git twig skill prints the bundled skill. Give those instructions to your agent so it chooses the right checkout, branch and location, uses Twig for creation, and asks before cleanup. Twig does not manage agent sessions or intercept an app's built-in worktree creation; no client-specific hook is needed for agent-directed CLI use.

Native CoW is verified on macOS/APFS and Linux Btrfs/reflink-enabled XFS, including the tested OverlayFS layouts below. Creates ordinary linked worktrees from committed files; local changes and ignored files aren't copied. Unsupported filesystems (including typical ext4), options and checkout semantics use git worktree. Set TWIG_TRACE=1 to see backend selection.

The selected donor, destination and Git metadata must share a clone-capable filesystem for native CoW. Twig verifies cloned files against the requested commit; writes are private, never hardlinked to source. Staging lives under the common Git directory in twigs/staging and is removed after success. Failed/interrupted attempts retain staging and may leave a partial registered worktree; inspect before retrying.

Filesystem support

Platform Filesystem CoW / fallback Verification
macOS APFS Native clonefile Tests, CI and allocation benchmarks
Linux Btrfs Native FICLONE Tests, CI and allocation benchmarks
Linux XFS with reflink=1 Native FICLONE Tests, CI and allocation benchmarks
Linux Typical ext4 Stock Git fallback; no reflink savings Full checkout test matrix
Linux tmpfs Stock Git fallback; no reflink savings Checkout matrix and mixed-mount isolation
Linux exFAT / VFAT Stock Git fallback; filesystem limitations apply Portable checkout subset, not full POSIX semantics
Linux XFS with reflink=0 Stock Git fallback expected Not separately verified
Linux OverlayFS over ext4 Stock Git fallback Checkout matrix and lower-layer preservation tests
Linux OverlayFS over reflink-enabled XFS / Btrfs Native FICLONE in tested layouts Checkout matrix, copy-up and private-write tests
Linux NTFS (ntfs3, ACL-enabled) Stock Git fallback; no reflink savings Checkout matrix; UTF-8 name restrictions apply
Linux NTFS (ntfs-3g, permissions enabled) Stock Git fallback; no reflink savings Checkout matrix; UTF-8 name restrictions apply
Linux OpenZFS 2.2.2 (tested guest) Synced-source FICLONE; dirty data may delegate 80 checkout tests with Git 2.43; minimum-Git environment incomplete
Linux NFSv4.2 over tested XFS/ZFS server Clone probes accepted Full checkout suites budget-stopped; not verified support
Linux bcachefs Exploratory; no support claim Not verified

Linux uses the actual clone operation, not a filesystem-name allowlist. Clone refusals before registration fall back to stock Git; failures after registration retain partial state for inspection. An accepted clone does not guarantee useful disk savings, especially for tiny files. Verification covers the tested setups, not every kernel, mount option or checkout policy. OverlayFS coverage includes fresh upper-layer repositories and repositories seeded in lowerdir before mount; it is not an allocation benchmark. See Linux test setup. Checkout policy coverage below is separate from filesystem capability.

Checkout policies

Version 0.4.0 supports common LF policies such as text=auto eol=lf. They compare private clones to raw target blobs and let Git write exceptional files, retaining sharing for the rest. Development builds also choose a donor across revisions and let Git write builtin ident/encoding exceptions. External filters and sparse checkout still delegate. Submodules are Git-written empty directories, never copied or recursively initialized from a donor. See the changelog for released fixes and unreleased coverage.

With TWIG_TRACE=1, native creation reports verified-clone and Git-written path counts. Delegation reports its specific cause; an attribute refusal names the path, attribute, and value (for example filter="unspecified" on "file.txt"). Do not override repository attributes with -text just to force the fast path: that changes Git checkout semantics rather than proving the bytes are correct.

Benchmarks

v0.5 preview · unreleased

Share unchanged files across revisions, builtin conversions and submodule checkouts. These synthetic workloads exercise the new sharing coverage; faster creation is not guaranteed. The preview benchmarks do not measure experimental adopt.

Workload · APFS Stock Git Twig v0.4 v0.5 preview
Cross-revision 139ms / 128.09 MiB 181ms / 128.09 MiB 884ms / 16.08 MiB
Builtin conversions 145ms / 128.11 MiB 372ms / 128.12 MiB 923ms / 88.00 KiB
Auto CRLF 392ms / 128.09 MiB 803ms / 128.09 MiB 614ms / 88.00 KiB
Submodules 138ms / 128.09 MiB 267ms / 128.09 MiB 900ms / 72.00 KiB
Unchanged bytes 134ms / 128.07 MiB 853ms / 68.00 KiB 880ms / 68.00 KiB
4,096 small files 1.11s / 36.41 MiB 2.07s / 3.31 MiB 2.08s / 3.38 MiB

Each cell is creation time / additional disk allocation. Medians of 3 two-worktree batches, one create at a time, on warm-cache filesystem images. Synthetic workloads, not real-repository or universal speed claims. Allocation includes Git metadata after first status; it is not exclusive file space reclaimed.

Across all levels: 992 certified creates; 2 failed points and 1 unstable observation retained.

Other filesystems: APFS (case-sensitive) · XFS · Btrfs. Speed varies by workload. Full results and limitations.

v0.4 real-repository benchmarks
Repo git worktree git twig Improvement
Workers starter (10 sequential) 456ms / 592 KiB 4.27s / 308 KiB 9.37× slower / 1.9× less space
git-twig (10 sequential) 422ms / 5.2 MiB 4.18s / 508 KiB 9.91× slower / 10.6× less space
Axo 400ms / 30.8 MiB 948ms / 1.2 MiB 2.37× slower / 26.7× less space
Linux kernel 40.56s / 1.8 GiB 31.32s / 44.7 MiB 1.29× faster / 41.9× less space
OpenClaw 8.58s / 919 MiB 8.80s / 31.1 MiB 1.03× slower / 29.5× less space
Pulumi docs 4.32s / 1.2 GiB 3.64s / 7.9 MiB 1.19× faster / 155.8× less space

Each cell is creation time / additional disk space. Batch sizes differ; creation excludes first status. † Includes failed Git attempts. Setup and raw results.

For Linux CLI time/allocation measurements, see Linux benchmarks.

Develop

cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked

Linux CI tests the host filesystem plus reflink-enabled XFS and Btrfs images, requiring native CoW on both. Locally on a supported Linux filesystem, run TWIG_TEST_REQUIRE_NATIVE=1 cargo test -p git-twig. Tests and benchmarks retain fixtures under target/; disk use grows. See the design contract, Linux correctness boundaries, changelog, and release operations.

MIT

About

lightweight git-worktrees for agents

Topics

Resources

Stars

245 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages