Skip to content

freespace: share linked worktree files with the main checkout via APFS clones - #2

Draft
tony-scio wants to merge 1 commit into
mainfrom
tony/freespace-clone-worktree-files
Draft

tony-scio wants to merge 1 commit into
mainfrom
tony/freespace-clone-worktree-files

Conversation

@tony-scio

@tony-scio tony-scio commented Nov 15, 2026 •

Copy link
Copy Markdown

Summary

freespace.sh now makes every linked git worktree share disk blocks with its main checkout on macOS. On a large monorepo checkout with 27 worktrees, this shared 47.7G (about 1.8G per worktree) without deleting anything. During one pass, free space rose 29.5G.

Why

Each worktree holds its own full copy of every tracked file. With many agent worktrees, that duplication is often the biggest thing on the disk, and it isn't a cache that can be deleted.

APFS can store a file as a clone: a copy that shares the original's disk blocks and only uses new space for blocks that later change. A clone behaves exactly like an ordinary independent file. Editing it in one worktree never changes another.

What changes

  • New scripts/clone-worktree-files.py (Python standard library only). For each linked worktree it replaces every tracked file that matches the main checkout with a clone of it. A file matches when both indexes record the same blob and mode and git diff-files sees it unmodified on both sides. --verify-bytes also compares the bytes.
    • Each replacement is an atomic swap (renamex_np with RENAME_SWAP), undone if the file was written after it was checked.
    • Clones are staged in the worktree's git directory, so git status never shows them.
    • Worktrees where a running process has its working directory are skipped.
    • It refreshes a copy of the index and installs it only if untouched, so it never holds index.lock while re-hashing.
  • freespace.sh runs it after git gc for each main checkout with linked worktrees and reports the amount shared (-n reports what it would share).

Notes

  • du and Finder still count every clone in full; only free space (df) shows the saving. Savings shrink as files diverge, and rerunning re-shares them.
  • The first run replaces every matching file once (about a minute per large worktree), so file watchers see one burst of changes. Later runs only touch files that changed.
  • No-op off macOS and across volumes.
  • A separate PR adds the same script (identical file) for new worktrees in sparse-branch.sh. The two merge in either order.

Testing

  • Scratch repos: dirty files, modes, symlinks, and files missing from the main checkout were kept. A rerun is a no-op. A simulated write during a swap was kept. A concurrent git add during the index refresh was kept. SIGTERM mid-run left no temp files.
  • Ran the script over 28 worktrees of a large repo: 27 shared, 1 skipped as busy, git status clean.
  • bash -n. freespace.sh -n on my laptop exited 0. After the run above it reported 1.8G still shareable in the large repo (a worktree that was busy earlier), plus 7M and 5M in two small repos with worktrees.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant