Module worktree_snapshot 

The snapshot rung’s mechanics: snapshot to a stage name, make it a worktree, swap it into place. What: The mechanics of rung 1 of the cheap-worktree ladder: a snapshot of the source subvolume taken at a stage name beside the destination, made into a worktree there (its own .git pointer, no stubs of nested worktrees, the source’s index with refreshed stat fields), and swapped with the destination in one atomic step. Why: The snapshot shares every data block with the source and carries its ignored state at no cost (doc/planning/cli-git-btrfs-worktree.md). It is made at a name Git never hands out, so the destination is complete or untouched at every instant: RENAME_EXCHANGE puts the finished subvolume at the destination and the empty directory real Git made at the stage name, which is then removed. A source that changed while the snapshot was taken is caught by comparing the snapshot’s own files with the index entries copied from the source.

In TS you’d write (pseudocode):

await takeSnapshot({ source, plan, stage, admin }); // throws a reason; the caller destroys the stage
await putInPlace({ stage, destination, mode });

Structs

PlaceError

Why a swap of the stage with the destination did not complete, and whether the stage name still holds the snapshot.

PlaceSeams

The moments of a swap at which the controls move the tree.

SnapshotFailure

Why a snapshot could not be taken, and the identity of the stage it left, if it left one.

Snapshotted

What a snapshot that was taken left for the steps after it.

Functions

put_in_place

What: Swap the finished stage with the destination, after giving the stage the mode of the source’s root. Why: RENAME_EXCHANGE leaves no instant at which the destination is missing or incomplete; the old destination, a directory with Git’s .git file, ends up at the stage name for settle_displaced. The names are looked up in the held parent; the destination must be the directory Git made, and a directory that is not is swapped back. When the swap back fails, the error says the stage name no longer holds the snapshot, so the caller does not remove what is there.

put_in_place_with

put_in_place with the moments at which a control may move the tree.

settle_displaced

What: Settle the directory real Git made, now at the stage name: move what was added to it meanwhile into the new worktree, remove Git’s pointer when it is the one that was written, remove the directory when it is empty, and return what stays. Why: The destination may have gained files between the look and the exchange, and a recursive removal would delete them. Only the pointer and an empty directory are removed; every other entry is moved without replacing, or stays with a note.

take_snapshot

What: Take the snapshot at stage and make it the new worktree there; the caller destroys stage on an error. Why: Each step is one the later steps depend on; the first failure ends the rung with its reason.