# Worktree runbook
The four steps of [worktrees](../method/08-worktrees.md) as commands: the chapter owns each step's why, this page owns its how. Mode-free by design — it documents the worktree form, which both checkout modes use; only step 1 notes where the `worktree` mode makes this the only path to a commit, and step 3 hands the integration to its own runbook. `<project>` is the main checkout's directory name, and `<repo>` is the project path, filled in by `rk guide worktree` where detection resolves it. The commands are the operator's to run: an agent serves a runbook and states the command, and runs one only where the operator's request named that step.
## 1. Create the worktree
```bash
rk worktree add <type>/<slug> # preview: names the derived path and the source
rk worktree add <type>/<slug> --apply
cd ../<project>@<type>-<slug>
# check: the apply prints the absolute path, and rk worktree list shows the seat
```
On worktree:
In this mode the main checkout commits nothing, so this step is the only path to a commit: every code-changing branch takes its worktree before its first commit.
### 1a. Adopt the forge-minted branch
Work an issue names starts from `rk issue start <issue>`, which mints the branch at the forge and seats it here. [The issue runbook](./issue.md) owns that procedure. Where the branch already exists and only the seat is missing:
```bash
rk worktree add <issue-id>-<slug> --apply
# check: the source line reports remote; the local tracking branch is created from origin/<branch>, never recreated from the trunk
```
### 1b. Cut a release line's worktree
```bash
rk worktree add release/<line> --base "v<version>" --apply
# check: the line takes its explicit base; without one the add refuses, because a line is cut from a tag, never the tip
```
### 1c. Adopt a bare branch
When moving a branch — or the mode — out of the main checkout:
```bash
git switch master # in the main checkout, so the branch is free
rk worktree add <branch> --apply
# check: the source line reports existing, adopted; the work travels with the branch, nothing is lost
```
## 2. Prepare its environment
A worktree is a fresh checkout: copy the untracked environment files the project needs, run its setup, and arm the hooks once per clone.
```bash
pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push
# check: reports the hook types installed; armed hooks fire in every linked worktree through the common git dir, so once per clone is enough
```
On rust:
Each worktree builds into its own `target/` by default. A shared `CARGO_TARGET_DIR` stays correct under cargo's lock and serializes parallel builds; per-worktree targets trade disk for parallelism.
## 3. Integrate
The seat's work reaches the trunk through the authority the record names, and [the integration runbook](./integration.md) owns both paths: `rk guide integration`. Nothing is restated here.
## 4. Prune after the integration
```bash
git fetch --prune origin # forge integration alone; a local integration reached no remote
rk worktree prune # check: the retired worktree is reported
rk worktree prune --verify # check: confirmed, and the row names which proof did it
rk worktree prune --apply # check: pruned; the branch and its configuration went with it
```
The verify names one of three proofs, and each removal rests on one:
- `request`: a merged request whose recorded head equals the branch's tip, the proof forge integration leaves.
- `local-integration`: a recorded local integration whose branch tip equals it and whose commit the trunk reaches, the proof `rk integrate` leaves under either merge form.
- `reachable-tip`: the trunk reaches the branch's current tip, and the branch moved from the commit its reflog's creation entry records. It needs no record and no forge answer, so it holds after a local rebase integration, a GitLab fast-forward merge, and a hand `git merge --ff-only`. A fresh branch still at its creation commit is never pruned by it, and a branch whose creation entry expired gets no such proof.
A squash writes a new commit and a GitHub rebase merge writes new commits with new SHAs, so after either the trunk does not reach the tip, and the merged request or the recorded integration stays the proof. [Integration](./integration.md) owns which one a target leaves, and [worktrees](../method/08-worktrees.md) owns why each proof is admissible. `rk branches prune --verify` names the same three proofs for a branch with no seat.
### 4a. The divergent rerun
An interrupted cleanup recovers with `git worktree list` and `git worktree repair`, then `rk worktree prune` again. A kept row's reason names its unblocking: commit or stash for dirt, `git worktree unlock <path>` for a lock you own. A `branch-delete-failed` row means the worktree is gone and the branch survives with its work; `rk worktree add <branch> --apply` re-seats it.
## 5. Promote to a workspace (optional)
A workspace is a directory scoped to this project alone, holding its main checkout, its worktrees, and whatever else the project keeps beside them; the [chapter](../method/08-worktrees.md) states the layouts this is one of. Promotion is a move per seat, at any time:
```bash
mkdir ../<workspace>
git worktree move ../<project>@<flat> ../<workspace>/<project>@<flat> # each linked worktree; git refuses to move the main one
mv ../<project> ../<workspace>/<project> # the main checkout last, as a plain move
git -C ../<workspace>/<project> worktree repair # check: repair reports each re-linked seat, or nothing
rk worktree list # check: every seat listed, none off-path, none missing
```