Prune Git Worktrees

Removes worktrees whose branches are merged on the remote default branch, while preserving any worktree with uncommitted changes, unpushed commits, detached HEAD, or unresolved state.

When to use

• Before starting fresh work in a repo with many open worktrees
• When git worktree list shows entries you don't recognize
• After a batch of PRs has merged and you want to reclaim disk + namespace
• As part of a periodic git-hygiene pass across multiple repos

What this skill does

1. git fetch origin --prune --quiet to refresh remote state.
2. Walks git worktree list --porcelain and classifies each entry.
3. Skips: main clone, bare clone, detached HEAD, missing path (admin-prunes those), uncommitted, unpushed.
4. Decides PRUNE if any of the following hold:
   • origin/<branch> is gone (typical squash-merge with delete-on-merge),
   • gh pr list --head <branch> --state merged returns a result, or
   • branch tip is an ancestor of origin/<default> (catches merge-commits).
5. Otherwise KEEPs and reports the reason.

How to invoke

# Always start with --dry-run for a new repo
python3 ~/.claude/plugins/otc-awesome-llm/skills/prune-worktrees/scripts/prune_worktrees.py \
  /path/to/repo --dry-run

# Repo whose default branch is develop (gitflow)
python3 .../prune_worktrees.py /path/to/repo --default develop --dry-run

# Apply
python3 .../prune_worktrees.py /path/to/repo --default main

The script must be invoked once per repo. For multi-repo passes, loop in shell:

for repo in repo-a repo-b repo-c; do
  python3 .../prune_worktrees.py "$HOME/scm/$repo" --default main
done

Safety guarantees

• Read-only when --dry-run — every action is logged but nothing mutates.
• Never touches uncommitted work — git status --porcelain non-empty -> KEEP.
• Never touches unpushed commits — origin/<branch>..HEAD non-zero -> KEEP.
• Defers on gh API failure — falls through to ancestry check, never assumes merged.
• Only removes via git worktree remove — refuses on dirty paths automatically; on failure the script keeps the entry and continues.
• Branch deletion is -D only after a successful worktree remove — never deletes a branch whose worktree is still active.

What this skill does NOT do

• Does not push, force-push, or rewrite history.
• Does not touch main, the bare clone, or any clone outside the targeted repo path.
• Does not run across repos in one call — one repo per invocation, by design.
• Does not delete unmerged branches, even if their worktree is empty.

Required tooling

• Python 3.11+ (stdlib only)
• git 2.20+ (worktree porcelain output)
• gh CLI authenticated (gh auth status) — without this, only remote-branch + ancestry detection runs

Cross-tool parity

This skill is canonical for Codex (via target_tool: codex) and the script ships here. A separate VS Code instruction at vscode/instructions/prune-worktrees.instruction.md references the same prune_worktrees.py for the VS Code surface.

Related issues

• optum-tech-compute/otc-awesome-llm#478 — original feature request