Agent-Skills.md

Agent Skills: Git Worktree & Branch Prune

Safely prune stale git worktrees and local branches left over from past sessions, deleting only those with no unique work so no commit is ever lost. Use when a repo has accumulated worktrees and branches over many sessions and needs cleanup. Triggers include "prune worktrees", "delete stale branches", "clean up git worktrees/branches", "remove old worktrees", "which branches are safe to delete".

UncategorizedID: ZacheryGlass/.claude/git-worktree-prune

Repository

ZacheryGlass/.claude
ZacheryGlass
59855

Install this agent skill to your local

pnpm dlx add-skill https://github.com/ZacheryGlass/.claude/tree/HEAD/skills/git-worktree-prune

Skill Files

Browse the full folder contents for git-worktree-prune.

Download Skill

Loading file tree…

skills/git-worktree-prune/SKILL.md

Skill Metadata

Name
git-worktree-prune
Description
Safely prune stale git worktrees and local branches left over from past sessions, deleting only those with no unique work so no commit is ever lost. Use when a repo has accumulated worktrees and branches over many sessions and needs cleanup. Triggers include "prune worktrees", "delete stale branches", "clean up git worktrees/branches", "remove old worktrees", "which branches are safe to delete".

Git Worktree & Branch Prune

Remove stale worktrees and local branches from old sessions without ever losing a commit.

Safety invariant

  • A branch is deleted only when every commit on it is reachable from some other surviving ref (another local branch, a remote-tracking branch origin/*, or a tag). Branches with unique commits are kept.
  • A worktree is removed only when it is clean (no uncommitted or untracked changes). The branch it held is preserved.
  • The primary worktree, the current branch, and main/master are always kept.

Usage

Always dry-run first (the default — it changes nothing), review the plan, then apply:

python scripts/prune_git.py --repo <path>            # dry-run: prints KEEP/REMOVE/DELETE plan
python scripts/prune_git.py --repo <path> --apply    # execute after reviewing the dry-run

Flags:

  • --fetch — run git fetch --all --prune first so branches already merged/pushed to a remote are recognized as deletable. Without it the tool is more conservative (stale remotes only ever cause it to keep more, never lose work).
  • --protect BRANCH — always keep this branch (repeatable). Use for branches with no unique commits that you still want to keep (see below).
  • --repo PATH — a path inside the target repo (default: cwd).

Review the DELETE list before --apply

The "no unique commits" rule is about commits, not intent. A branch can be flagged DELETE while still being meaningful — most commonly a feature branch that a descendant now subsumes (e.g., you branched research/x off feat/y, so feat/y's commits now also live on research/x). No commit is lost if it's deleted, but the branch name and its PR track are. Keep such a branch with --protect <name>.

Every removal is printed with its reason; a branch shown as KEEP -- N unique commit(s) holds work found nowhere else and is never touched.

Notes

  • Never deletes remote-tracking refs, tags, or the reflog — only local branches and worktree checkouts.
  • Removing a worktree that holds a branch (even a protected one like main) frees the branch without deleting it; you can then check it out in the primary worktree.
  • Worktrees whose directory is already gone are cleaned via git worktree prune.
  • On Windows, run under Git Bash / a UTF-8 console (PYTHONIOENCODING=utf-8) if paths contain non-ASCII characters.