Worktrees

Note

Draft placeholder — outline notes only; prose not yet written.

Points this section needs to cover:

  • What a worktree is: multiple working trees sharing a single repository (one object database, one set of refs, many checkouts)

  • git worktree add, list, move, remove, lock/unlock, prune; git worktree add --orphan for empty starting points

  • Use cases:

    • fixing a bug on another branch without stashing or disturbing a work in progress

    • running builds/tests on one branch while working on another

    • one checkout per coding agent for parallel agent work (forward pointer to Ch 7, Git and Agents)

  • Rules and housekeeping: a branch can only be checked out in one worktree at a time; where the linked worktree metadata lives; cleaning up with prune

  • New diagrams needed in diagram-source/ (shared repository, multiple working trees)