worktree-cleanup

The rule

Sequence is ALWAYS:

git worktree remove --force <path>   # step 1
git branch -D <branch>               # step 2

If you skip step 1, step 2 fails. gh pr merge --delete-branch behaves like step 2 — it also fails when a worktree pins the branch.

Behavior

1. Detect the branch to clean up (from user's message or the PR).
2. List worktrees touching the branch:

   git worktree list --porcelain | grep -B2 "branch refs/heads/<branch>"
   

3. If a worktree exists at path <path>:
   • Show it to the user.
   • Run git worktree remove --force <path> (the --force handles dirty state in the worktree; warn user if there are uncommitted changes).
   • THEN run git branch -D <branch>.
4. If no worktree exists for the branch:
   • Just git branch -D <branch>.
5. Report what was removed.

Multiple worktrees on one branch

Impossible under git (each worktree pins its own unique branch). If detection shows multiple, that's a stale entry — clean with git worktree prune first, then retry.

Batch cleanup

If user asks "cleanup all merged branches with worktrees":

1. git branch --merged dev (or main) for merged branches.
2. For each: check worktree via git worktree list --porcelain.
3. Run sequence per branch.
4. Report tally: N branches removed, M worktrees pruned.

Do not

• Never git branch -D before worktree remove — always error, waste of round-trip.
• Never git worktree remove <path> without --force unless the worktree is spotless — the flag is standard in Nimbus flow.
• Never delete a branch with unmerged commits without warning the user + showing them the commits that would be lost.
• Never touch main, dev, master — those are protected default branches.

Cross-repo cleanup

If user asks "cleanup old branches across all my repos", iterate:

for r in ~/Development/cidca/cidca-platform ~/Development/cidca/cidca-services \
         ~/Development/horus/horus-v2 ~/Development/zotea; do
  cd "$r" && echo "=== $(basename $r) ===" && git branch --merged | grep -v -E "(main|dev|master|\*)"
done

Then present the list and let user choose which to remove.