Re: [PATCH v2 1/2] worktree: add --reflink for copy-on-write worktree creation
- From
- Jason Newton <nevion@gmail.com>
- Date
- Oct 21, 2026, 07:15 UTC
- Message-ID
- <CAGou9MhkmSZs3ViSj6qqkZY6LLLQQ+5RzjLG5EhM-AXx+d7h=A@mail.gmail.com>
- In-Reply-To
- <atfbDXhTUmPtv5pE@fruit.crustytoothpaste.net>
Brian,
macOS cp has no --reflink=always. The clone option is -c, which is clonefile(2). t/t2400-worktree-add.sh already probes that way. The REFLINK prerequisite runs "cp -c" when the MACOS prerequisite is set, and "cp --reflink=always" otherwise. The test that depends on REFLINK is "--reflink carries untracked files and reconciles changes".
That is in 042485f0e9cd8cf1765b811ea7334247aec44971. The pull request CI for that commit is the APFS run:
https://github.com/git/git/pull/2317 https://github.com/git/git/actions/runs/39502233266
All four macos-14 jobs succeeded. The runners were macOS 14.8.9 (23J631), image macos-14-arm64 20260831.0302.1. "print test failures" was skipped on each job, which is the step that runs only when a test script fails.
osx-clang: https://github.com/git/git/actions/runs/39502233266/job/118902393415 t2400-worktree-add.sh ok, 55208 ms
osx-gcc: https://github.com/git/git/actions/runs/39502233266/job/118902393588 t2400-worktree-add.sh ok, 45173 ms
osx-meson: https://github.com/git/git/actions/runs/39502233266/job/118902393644
osx-reftable: https://github.com/git/git/actions/runs/39502233266/job/118902393664
The macOS evidence is those jobs.
Reflink is disabled on Windows in "worktree: disable reflink on Windows" (91806975a6909265b1325206ef2f33a169393920). The pull request head is 876fb541a8e1d43731bb72ddbbf1c49da8760775, which keeps that disable and leaves the filesystem probe compiled so the mingw build does not fail with -Werror=unused-function. The CI run linked above is the previous tip, 042485f. The warning names the build from the git-lfs report, Windows 11 build 26200. A later note on that report reproduced the zero-fill on build 26200.9448 with git-lfs 3.6.1. No fixed build is identified, so every Windows version refuses the ioctl and falls back to a regular checkout. "git worktree add --reflink" and worktree.reflink=true warn with "Windows build 26200". worktree.reflink=auto stays silent. t2400 checks that warning under MINGW.
On the git-lfs report, the failure mode is real and documented here:
https://github.com/git-lfs/git-lfs/issues/6312 https://github.com/git-lfs/git-lfs/pull/6323
FSCTL_DUPLICATE_EXTENTS_TO_FILE can publish zeros when the source data is still cached. FlushFileBuffers on the read-only handle a checkout uses fails with ERROR_ACCESS_DENIED (win32 5). The change in 6323 reopens the source writable, flushes, and skips that flush when the volume does not advertise FILE_SUPPORTS_BLOCK_REFCOUNTING.
The numbers below are from the ioctl path before that disable, on this machine, Windows build 26300.9457. The read-only flush failed with win32 5, the same error the git-lfs report describes. The clones kept the original bytes.
NTFS rejects the ioctl: win32 1 on a USB NTFS partition, win32 50 on C:. The fallback there is a normal write. The USB disk would not format as ReFS. The ReFS volume was a 32 GiB Dev Drive, stored as a VHD on that disk, with block refcounting set. The clone path did not flush.
Content check, every clone, unbuffered SHA-256:
4000 files, 8,388,608 bytes each (33,554,432,000 bytes, 31.25 GiB of clone names). Created with FSCTL_DUPLICATE_EXTENTS_TO_FILE only.
Source before rewrite: 106640827aa82610080b1e4c676e2028230b841fa4642faaa292046833950714 Pass 1: old=4000 new=0 other=0 errors=0
Source rewritten to a different pattern, still no flush: e58408ac406d407257cd3a2474b8bba7b615e76bd4ce03e8ec3df9b42a02bc89 Pass 2: old=4000 new=0 other=0 errors=0
FlushFileBuffers on the read-only handle: FAIL win32=5 Reopen writable and flush: OK Source hash stayed on the rewritten pattern. Pass 3, after that flush: old=4000 new=0 other=0 errors=0
All 4000 clones still hashed to the original source. After they settled, free space was 30,462,386,176 bytes and the backing VHD was still 4,164,943,872 bytes. The volume stayed Healthy. Deleting the clones freed nothing further.
This is one Windows build, alongside the version described in git-lfs #6312.
On Tue, Oct 20, 2026 at 2:20 PM brian m. carlson <sandals@crustytoothpaste.net> wrote:
Show 60 quoted lines
> > On 2026-10-20 at 16:04:08, Jason Newton via GitGitGadget wrote: > > Creating many worktrees from the same base -- for example to run a > > fleet of automated agents in parallel -- is expensive today: every > > "git worktree add" materializes the entire working tree by writing > > each tracked file out from the object store. The objects are shared > > via the common directory, but the working tree is not: N worktrees > > mean N full checkouts on disk and N times the file I/O. > > > > Add a "--reflink" option that, on a copy-on-write filesystem, populates > > the new worktree by reflinking the current worktree's files and index > > instead. The subsequent "git reset --hard" then only rewrites the > > paths that actually differ between the current worktree and > > <commit-ish>; everything else (including untracked files such as build > > outputs) keeps sharing storage with the source until modified. > > > > A new reflink_file() helper in copy.c clones every regular file. There > > is no size cutoff. > > > > On Linux it uses the FICLONE ioctl. That is the primitive btrfs, XFS > > and bcachefs implement, and the one overlayfs forwards when the lower > > filesystem can clone. This path has been tested on btrfs. > > > > On macOS it uses clonefile(), the APFS primitive. That path is > > implemented and has not been run here. > > > > On Windows it uses ReFS block cloning, > > FSCTL_DUPLICATE_EXTENTS_TO_FILE, as Git LFS does. The destination is > > sized to the source, extents are cloned in chunks of at most 1GiB, and > > the tail is rounded up to a cluster (64K, then 4K) and cloned; Windows > > ignores the range past EOF. The tail is not byte-copied, and small > > files are not skipped. That path is implemented and has not been run > > on ReFS. A volume that rejects the control code, including NTFS, fails > > the probe. > > That functionality is defective; see > https://github.com/git-lfs/git-lfs/issues/6312. We should not implement > this on Windows because there's no reasonable way to avoid corruption. > It's quite shocking that that bug exists, but it does. Unless we can > guarantee a fixed version of Windows (which does not exist yet), we > should skip reflinking there. > > I'd also like to see us limit this to platforms where it _has_ been > manually tested or is guaranteed to be automatically tested in CI. That > means we should make sure this runs in CI on APFS for macOS (see below). > > > +# Reflinks are only available on copy-on-write filesystems (btrfs, XFS, > > +# bcachefs, APFS, ...). Where they are unavailable, --reflink transparently > > +# falls back to a regular checkout, which the test above already covers. > > +test_lazy_prereq REFLINK ' > > + echo probe >reflink-src && > > + cp --reflink=always reflink-src reflink-dst 2>/dev/null > > +' > > Does this work properly on macOS? That is, does the macOS `cp` binary > contain support for `--reflink=always`? If not, we won't be testing > this case properly on macOS. > -- > brian m. carlson (they/them) > Toronto, Ontario, CA