Star 历史趋势
数据来源: GitHub API · 生成自 Stargazers.cn
README.md

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

Version 0.5.0 can reuse matching files from nearby worktrees for other revisions too. Git writes changed, new or converted files. 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

PlatformFilesystemCoW / fallbackVerification
macOSAPFSNative clonefileTests, CI and allocation benchmarks
LinuxBtrfsNative FICLONETests, CI and allocation benchmarks
LinuxXFS with reflink=1Native FICLONETests, CI and allocation benchmarks
LinuxTypical ext4Stock Git fallback; no reflink savingsFull checkout test matrix
LinuxtmpfsStock Git fallback; no reflink savingsCheckout matrix and mixed-mount isolation
LinuxexFAT / VFATStock Git fallback; filesystem limitations applyPortable checkout subset, not full POSIX semantics
LinuxXFS with reflink=0Stock Git fallback expectedNot separately verified
LinuxOverlayFS over ext4Stock Git fallbackCheckout matrix and lower-layer preservation tests
LinuxOverlayFS over reflink-enabled XFS / BtrfsNative FICLONE in tested layoutsCheckout matrix, copy-up and private-write tests
LinuxNTFS (ntfs3, ACL-enabled)Stock Git fallback; no reflink savingsCheckout matrix; UTF-8 name restrictions apply
LinuxNTFS (ntfs-3g, permissions enabled)Stock Git fallback; no reflink savingsCheckout matrix; UTF-8 name restrictions apply
LinuxOpenZFS 2.2.2 (tested guest)Synced-source FICLONE; dirty data may delegate80 checkout tests with Git 2.43; minimum-Git environment incomplete
LinuxNFSv4.2 over tested XFS/ZFS serverClone probes acceptedFull checkout suites budget-stopped; not verified support
LinuxbcachefsExploratory; no support claimNot 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. Version 0.5.0 also chooses a donor across revisions and lets 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 release details.

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 checkout coverage

Share unchanged files across revisions, builtin conversions and submodule checkouts. These synthetic workloads measure a frozen pre-release candidate, not the published binary; faster creation is not guaranteed. They do not measure experimental adopt.

Workload · APFSStock GitTwig v0.4v0.5 candidate
Cross-revision139ms / 128.09 MiB181ms / 128.09 MiB884ms / 16.08 MiB
Builtin conversions145ms / 128.11 MiB372ms / 128.12 MiB923ms / 88.00 KiB
Auto CRLF392ms / 128.09 MiB803ms / 128.09 MiB614ms / 88.00 KiB
Submodules138ms / 128.09 MiB267ms / 128.09 MiB900ms / 72.00 KiB
Unchanged bytes134ms / 128.07 MiB853ms / 68.00 KiB880ms / 68.00 KiB
4,096 small files1.11s / 36.41 MiB2.07s / 3.31 MiB2.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
Repogit worktreegit twigImprovement
Workers starter (10 sequential)456ms / 592 KiB4.27s / 308 KiB9.37× slower / 1.9× less space
git-twig (10 sequential)422ms / 5.2 MiB4.18s / 508 KiB9.91× slower / 10.6× less space
Axo400ms / 30.8 MiB948ms / 1.2 MiB2.37× slower / 26.7× less space
Linux kernel40.56s / 1.8 GiB31.32s / 44.7 MiB1.29× faster / 41.9× less space
OpenClaw8.58s / 919 MiB8.80s / 31.1 MiB1.03× slower / 29.5× less space
Pulumi docs4.32s / 1.2 GiB3.64s / 7.9 MiB1.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
agentsgitworktrees

语言 Languages

Rust69.8%
TypeScript22.7%
Python4.9%
CSS1.1%
Roff0.7%
Shell0.3%
Ruby0.3%
HTML0.2%

提交活跃度 Commit Activity

代码提交热力图
过去 52 周的开发活跃度
65
Total Commits
峰值: 65次/周
Less
More

核心贡献者 Contributors