Module worktree_clone 

The clone rung: tracked files cloned into the new worktree, the source’s index installed with fresh stat fields. What: Rung 2 of the cheap-worktree ladder: each tracked file of the clean source is cloned (FICLONE) into the new worktree with the source’s mode and times, and the source’s index is installed with fresh stat fields. Why: A clone shares every data block with the source on btrfs, on XFS with reflink and inside an overlay, which the snapshot rung cannot reach (overlayfs and XFS have reflink but no subvolumes). It takes no less time than Git’s checkout on btrfs (doc/planning/cli-git-btrfs-worktree.md, option B), so it saves disk, not time, and it is the accelerated rung where a snapshot is impossible. The wrapper’s own index writer is rewrite_index_stat_with: with each file’s size and modification time kept, only the inode, change time and device of every entry change. The first failure ends the rung with its reason, the entries this run created stay (a name cannot be checked and unlinked in one step), and Git’s own checkout completes the worktree and overwrites the tracked ones. Every source file is opened below a held handle of the source root without following a link, and its descriptor’s metadata, not a path, is compared with the frozen index entry before and after the clone; every destination entry is created below a held handle of the destination. A directory swapped for a link while the run goes on is an error, never a detour.

In TS you’d write (pseudocode):

await cloneTrackedFiles(source, destination, admin); // throws a reason

Structs

Cloned

What: What a successful clone run holds: the entries it created. Why: A later step that fails (the tree difference) reports them; Git’s own checkout then overwrites the tracked ones, and the rest stay as untracked files for the person to remove.

Created

What: An entry this run created, named by its components below the destination. Why: Nothing is removed on a failure: a name cannot be checked and unlinked in one step, and the entry may by then be another process’s, so the run keeps what it made and reports it. The list is what the report names.

Functions

clone_tracked_files

What: Clone every tracked file of the frozen index into the held destination, and install that index in the held admin with the stat fields of the regular files made. On an error nothing is removed: the entries this run created stay and are counted in the reason. Why: The index bytes are the ones proven clean, so what is installed is what was proven; the destination may hold files of other writers, and they are not this run’s to remove.

leftover_report

What: The report of entries a clone run created and leaves in place. Why: The tracked ones are overwritten by the checkout that completes the worktree; any other stays as an untracked file, and the person is told where to look.