holocron/plugins/git/.apm/skills/git-worktrees/SKILL.md

name, description, metadata

name	description	metadata
git-worktrees	Use when working on several branches at once without stashing — manages the full lifecycle of a git worktree. Not ordinary branch switching or checkout -> `git-branches`. Not interactive multi-step git guidance -> `git-workflow`.	version category source_keys 1.0.1 git git-scm-worktree-docs

Gotchas

• A branch can be checked out in only one worktree at a time. git worktree add on an already-checked-out branch fails; --force is the only override, so use it only deliberately.
• Never rm -rf a worktree directory. That strands metadata in $GIT_DIR/worktrees/. Use rtk git worktree remove, or rtk git worktree prune afterwards.
• Submodules break worktree support. A worktree containing submodules cannot be moved at all, and needs --force to remove.
• extensions.worktreeConfig = true is a one-way door. Without it, git config --worktree errors; with it, that flag writes to the worktree's own config.worktree file, and core.bare/core.worktree are forced there too. It also breaks older Git. Leave it off unless per-worktree config is needed.

Step 1 — Dispatch

Operation	Run
Create on a branch that already exists locally	rtk git worktree add <path> <branch>
Create on a new branch	rtk git worktree add -b <branch> <path>
Create on the branch named after the path basename	rtk git worktree add <path> — checks that branch out if it exists, else creates it from HEAD
Create and reset an existing branch to HEAD — discards its commits	rtk git worktree add -B <branch> <path>
Create a local branch tracking a remote one	rtk git worktree add --track -b <branch> <path> <remote>/<branch> — always correct. git worktree add <path> <branch> expands to exactly this, but only under the conditions in references/worktrees.md
Throwaway experiment, no branch	rtk git worktree add -d <path> — detached HEAD
Never git worktree add <path> <remote>/<branch>	That ref resolves, so the shortcut never fires and you get a detached HEAD, no branch, no upstream. Commits there go unreachable once HEAD moves, and git push needs an explicit refspec. Use the tracking row above
List	git worktree list -v to read, or git worktree list --porcelain -z to parse — both bare per ADR-0023: rtk re-renders the output and drops the porcelain flags
Lock or unlock	rtk git worktree lock [--reason <str>] <path> / rtk git worktree unlock <path>
Move	rtk git worktree move <from> <to>
Remove	rtk git worktree remove <path>
Prune stale metadata	rtk git worktree prune --dry-run, then without the flag
Repair after a manual move	rtk git worktree repair — in the main worktree if it moved, or inside a linked worktree that moved. rtk git worktree repair <path>... — from any worktree, naming each moved linked worktree's new path

If the operation needs anything the table does not carry — the full add flag table, orphan branches, sparse-checkout, locking for removable media, remote disambiguation across several remotes, how to name a worktree unambiguously, worktree config keys, or the worked emergency-fix and PR-review patterns — read references/worktrees.md.

Gates:

• move, remove — the main worktree cannot be moved or removed. Only linked worktrees, the ones git worktree add created, are candidates.
• add, move, remove — escalate force flags one step at a time. -f overrides a safeguard such as an unclean tree; move and remove need -ff on top of that when the worktree is locked. Confirm with the user before either — both discard state.
• add — lock at creation, not after. rtk git worktree add --lock is atomic, where add-then-lock leaves a window in which the worktree is unprotected.

Step 2 — Report

worktrees:
  - path: <directory-path>
    branch: <branch-name>
    commit: <short-hash>
    locked: <true/false>
    lock_reason: <reason or empty>

Derive those fields from git worktree list --porcelain -z — bare, not rtk: rtk drops both flags and never emits locked/lock_reason (ADR-0023). For a single operation, report its outcome instead — created: true, moved: true, removed: true.