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