Worktrees
Development reference · View source
Space g w (:git-worktrees) lists every checkout registered with the
repository: linked, detached, locked, prunable, and bare.
| Key | Action in the worktree list |
|---|---|
Enter | Attach to this root’s persistent session, starting it if necessary |
Tab n | Name a new branch at this checkout’s tip and create its worktree; attach in mux mode |
Tab d | Compare committed tips with this worktree |
Tab D | Remove this worktree and its session after confirmation; keep its branch |
Space g r | Re-read the registered worktrees |
*marks the current root. Unavailable states are written on their rows.- Paths are the identity, including paths that are not valid UTF-8 (displayed with replacement characters).
Opening another root never retargets this workspace’s buffers or language servers.
| Mode | Enter | Tab n |
|---|---|---|
| Mux | Detaches the TUI and attaches to the destination’s host (starting it if needed). The old host keeps its buffers and terminals. | Creates the worktree and attaches at once |
| Ide | Explains that attaching needs mux mode | Creates the worktree and stays in the current workspace |
Removing a worktree
Tab D removes one ordinary worktree at a time and never deletes its branch.
Refused before confirmation:
- staged, unstaged, or untracked files;
- a running session on it with unsaved file buffers or unavailable health;
- the current Runyte root, and locked, bare, missing, or otherwise unavailable worktrees.
What the confirmation asks for:
| Situation | Confirm with |
|---|---|
| A clean session runs on it | Typed text — the branch name, or the displayed path for a detached checkout (the session goes too) |
| Its branch has commits ahead of the cached upstream, or the upstream is gone | The exact branch name |
| An unretained detached checkout | Its displayed path |
| Otherwise | Enter |
Remove worktree /home/me/code/runyte-enh-render-space.
This also stops and forgets session 5 (runyte-enh-render-space).
Branch enh/render-space will remain.
Type enh/render-space exactly to continue.
Escape keeps it.
Order of events:
- Git status, worktree identity, upstream state, and session health are checked again.
- The session is stopped — the host owns the directory and its runtime state. A failed stop leaves the worktree standing.
- Git removes the directory. If Git refuses, the branch and history record are left alone.
- The workspace’s history record is forgotten, so nothing keeps a claim on the digit it used. This happens whether or not a host was running.
Stopping the session is part of removal, not a session command, so it
happens in ide mode too: an ide-mode editor cannot attach to a
session, but it can still find and stop one running on the worktree.