git-branch-cleanup

Git Branch Cleanup

Safely organize and clean up local Git branches. Categorizes branches by merge status, staleness, and remote tracking, then guides users through safe deletion.

Contents

• Quick Start
• Workflow (Steps 1-5)
• Commands Reference
• Dry Run Mode
• Safety Checklist

Quick Start

1. Analyze branches (Step 1)
2. Categorize by safety level (Step 2)
3. Display results and ask user which to delete (Step 3)
4. Verify against safety guards (Step 4)
5. Execute deletion after confirmation (Step 5)

Workflow

Step 1: Branch Analysis

Collect information with these commands:

# Decide base branch (prefer auto-detect; fallback to main)
BASE_BRANCH="$(
  git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@'
)"
[ -n "$BASE_BRANCH" ] || BASE_BRANCH=main

# List all branches with last commit date
git for-each-ref --sort=-committerdate refs/heads/ \
  --format='%(refname:short)|%(committerdate:relative)|%(upstream:trackshort)|%(contents:subject)'

# Merged branches (against base)
git branch --merged "$BASE_BRANCH"

# Unmerged branches
git branch --no-merged "$BASE_BRANCH"

# Branches whose upstream is gone (remote deleted)
git branch -vv | grep -F ': gone]' || true

# List worktrees (branches with '+' prefix in git branch -v have worktrees)
git worktree list

# Branches with worktrees ('+' prefix indicates worktree association)
git branch -v | grep '^+' || true

# Branches ahead of upstream (have unpushed commits)
git for-each-ref refs/heads \
  --format='%(refname:short) %(upstream:trackshort)' \
  | grep '>' || true

Step 2: Categorization

Categorize branches by safety level: