worktree-cleanup

name	worktree-cleanup
description	Use when the user asks to clean, prune, or tidy git worktrees, or when worktree count seems excessive, or stale audit-mirror temp worktrees are accumulating.

Worktree Cleanup

Clean up stale, temporary, and merged git worktrees in a bare-repo-with-worktrees layout.

Workflow

1. Survey

List all worktrees and categorize them:

git worktree list

Split into three buckets:

• Temp/ephemeral: paths under OS temp dirs (/private/var/folders/*/T/, /tmp/, $TMPDIR). Typically stale audit mirrors or CI artifacts -- identifiable by ito-audit-mirror-* naming or (detached HEAD) state.
• Locked: worktrees marked locked. Never remove these.
• Feature worktrees: everything else (typically under ito-worktrees/ or sibling directories).

Report counts to the user before proceeding:

Found:
  - N temp worktrees (safe to remove)
  - N locked worktrees (will not touch)
  - N feature worktrees (will check merge status)

2. Remove temp worktrees

Temp worktrees are safe to bulk-remove. The fastest approach:

# Delete directories from disk first (much faster than git worktree remove one-by-one)
rm -rf "$TMPDIR"/ito-audit-mirror-* 2>/dev/null
rm -rf /tmp/ito-audit-mirror-* 2>/dev/null

# Then prune stale worktree entries from git metadata
git worktree prune

Do NOT use git worktree remove in a loop for hundreds of entries -- it is extremely slow (processes one at a time with full git index operations). Disk deletion + git worktree prune is the correct bulk approach.

3. Check feature worktrees for merge status

For each non-locked, non-temp worktree, check if its branch has been merged:

git branch --merged origin/main

Compare the worktree branch names against merged branches.

• Merged branches: safe to remove. Clean up both the worktree and the branch:

  git worktree remove <worktree-path> 2>/dev/null || true
  git branch -d <branch-name> 2>/dev/null || true
  git worktree prune
  

• Unmerged branches: report to the user with branch name and worktree path. Do NOT remove unless explicitly asked.

4. Final verification

git worktree list

Report the final state to the user.

Safety rules

1. Never remove locked worktrees (e.g. main, or any marked locked).
2. Never remove unmerged feature worktrees without explicit user confirmation.
3. Always prune after removing worktrees to clean up git metadata.
4. Temp worktrees are always safe to nuke -- they are ephemeral audit mirrors created by automated processes.

Bare repo notes

In a bare-repo layout, all git commands must be run from inside a worktree (e.g., main/), not from the bare repo root. The worktree list command works from any worktree.

Worktree metadata lives in .bare/worktrees/ -- git worktree prune cleans entries whose directories no longer exist on disk.

Common mistakes

• Using git worktree remove in a loop for hundreds of temp worktrees. This takes minutes; rm -rf + prune takes seconds.
• Removing locked worktrees like main. Always check lock status first.
• Forgetting git worktree prune after deleting directories. Without pruning, git still tracks the stale entries.
• Running git commands from bare repo root instead of from inside a worktree.