Module worktree_snapshot_source 

The snapshot source: whether the creating worktree can be snapshotted for a new worktree, and what that needs. What: Whether the creating worktree can be the source of a snapshot for a new worktree, decided before real Git runs, and everything the snapshot needs to know about it. Why: A snapshot copies the whole subvolume, so the source must be a subvolume root on the same filesystem as the destination, clean, and free of every feature whose result would differ from Git’s checkout: a sparse checkout, a worktree-specific configuration, a submodule, and a nested linked worktree that is an ordinary directory (a snapshot carries its files, and removing them one by one costs more than the checkout saves). Each refusal returns its reason in words; the caller logs it and falls to the next rung without a word to the person.

In TS you’d write (pseudocode):

const source = await chooseSnapshotSource({ context, identity, plan }); // throws the reason it cannot be one

Structs

ChangedPaths

What: What Git’s status lists as changed or untracked in a worktree. Why: The person is told how many paths and one name; the restore refuses a changed .gitattributes file, whose rules could change how the restore writes other files.

Refusal

What: Why a source cannot be copied, and which kind of check said so. Why: The reason is for the log and for the sentence the person reads; the kind lets the sentence be chosen without reading the reason’s words.

SnapshotSource

What: The source a snapshot is taken from and what the later steps need to know about it. Why: The checks ran once before Git; the steps after Git use their results instead of asking again.

Enums

RefusalKind

Which kind of check refused a source, so the person can be told the cause in words that fit it.

Functions

changed_paths

What: The paths git status lists as changed or untracked in the worktree at root, counted, with the first, and whether a .gitattributes file is among them (also one inside an untracked directory); or the words that say which Git run failed and how. Why: Only Git’s own status tells a real change from a stale record of file times. The read takes no optional lock, so it never disturbs the checkout a person works in. A listing with nothing in it is an answer (every file equals its commit by content), never a failure: the stat data of an index that was just written, or of a file that was touched, proves nothing, and Git settles those by content.

choose_snapshot_source

What: Decide whether the creating worktree of a planned add can be the snapshot source: the cheap refusals, the shared checks, then what only a snapshot minds. Why: The ladder asks the three in turn so the clone rung can share the dear checks; this is the whole question for the snapshot alone.

clone_refusal

What: The cheap reasons the clone rung cannot serve a planned add: either side is on a filesystem that never clones, or the two are not in one clone domain (one btrfs filesystem, or one device elsewhere). Why: A clone crosses subvolumes of one btrfs filesystem and nothing else; an overlay or XFS is one device.

common_source

What: Check the creating worktree for everything a copy of its files needs; the reason is the error. Why: Callers that only log or compare the reason ask for the words; the ladder asks source_refusal for the kind too.

plain

What: The text with every control character replaced by ?. Why: A path in a sentence on a terminal or in the journal must not carry an escape sequence or start a line.

registered_roots

What: The roots of the linked worktrees registered in a repository, read from their gitdir files. Why: Git lists the same paths; reading them here costs no Git process.

snapshot_blocker

What: The registered worktree inside the source that would be carried into a snapshot with all its files, if any. Why: Only the snapshot rung cares: a nested worktree that is a subvolume is an empty stub in a snapshot.

snapshot_refusal

What: The cheap reasons the snapshot rung cannot serve a planned add: the source is no subvolume root, or it and the destination are not on one btrfs filesystem. Why: These need two statfs calls and one inode number, so they run before the dear checks.

source_or_dirty

What: source_refusal, except that a main checkout with only ordinary uncommitted changes is a source too, carrying the list of its changes; every other refusal stays. Why: The ladder snapshots such a source and restores the copy to the new worktree’s HEAD; the clone rung and the other callers of the clean answer never see it.

source_refusal

What: Check the creating worktree for everything a copy of its files needs, from the cheapest check to the dearest, and collect what the later steps use; the refusal is the error. Why: The dear checks (the clean check starts one Git run) happen once for both rungs, and only after a cheap check let a rung through. The kind of the refusal lets the ladder tell the person the cause in fitting words.