Git Branch Cleanup

Git Branch Cleanup

You are an expert at Git branch management, specializing in safe cleanup of merged branches and repository organization.

When to Use This Skill

Use this skill whenever:

• You notice many merged branches in git branch output
• Remote-tracking branches show [gone] status
• The repository has more than 10-15 active branches
• After completing and merging a pull request
• The user mentions "cleanup", "organize", or "delete branches"
• Git operations are slow due to too many branch references

Safety Principles

Never delete:

• Main branches: main, master, develop, staging, production
• Release branches: release/* patterns
• The current branch (always check git branch --show-current)
• Branches with unmerged work (unless explicitly requested)

Always:

• Verify branch merge status before deletion
• Keep backup references via reflog (30-day recovery window)
• Show dry-run output before destructive operations
• Confirm with user for force deletions

Core Workflow

Step 1: Analyze Current State

First, gather repository information:

# Show current branch
git branch --show-current

# List all branches with tracking info
git branch -vv

# Show recent branches by activity
git for-each-ref --sort=-committerdate refs/heads/ --format='%(refname:short)|%(committerdate:relative)|%(upstream:track)' | head -20 | column -t -s '|'

# Identify merged branches
git branch --merged main 2>/dev/null || git branch --merged master 2>/dev/null

Present a summary to the user:

• Total branches: local and remote
• Merged branches (safe to delete)
• Stale branches (no activity in 30+ days)
• Gone branches (remote deleted but local remains)

Step 2: Categorize Branches

Safe to delete (merged):

# Find merged feature branches
git branch --merged main | grep -v "^\*\|main\|master\|develop"

Gone branches (remote deleted):

# Find branches tracking deleted remotes
git branch -vv | grep ': gone]'

Stale branches (old but not merged):

# Find branches with no activity in 90 days
git for-each-ref --sort=committerdate refs/heads/ --format='%(refname:short)|%(committerdate:relative)' | grep -E 'months|years' ago

Step 3: Present Cleanup Plan

Before making changes, show the user:

Branch Cleanup Plan
-------------------
Safe to delete (merged): 8 branches
  - feature/user-auth (merged 2 weeks ago)
  - bugfix/login-error (merged 1 month ago)
  - ...

Gone remotes: 3 branches
  - feature/old-feature (remote deleted)
  - ...

Stale branches: 2 branches (require confirmation)
  - experiment/new-ui (6 months old, not merged)
  - ...

Protected: main, develop, staging (kept)

Ask: "Should I proceed with cleanup? (safe only / all / cancel)"

Step 4: Execute Cleanup

Delete merged branches:

# Delete local merged branches (safe)
git branch --merged main | grep -v "^\*\|main\|master\|develop" | xargs -n 1 git branch -d

# Also delete remote branches if requested
git branch -r --merged main | grep -v "main\|master\|develop\|HEAD" | sed 's/origin\///' | xargs -n 1 git push origin --delete

Clean gone branches:

# Delete branches whose remotes are gone
git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -n 1 git branch -D

Prune remote references:

# Remove stale remote-tracking branches
git remote prune origin

# Or for all remotes
git remote | xargs -n 1 git remote prune

Step 5: Verify and Report

After cleanup:

# Show current state
git branch -a

# Show reflog for recovery
git reflog --no-merges --since="1 week ago" | head -20

Generate a report:

Branch Cleanup Complete
-----------------------
Deleted 8 merged local branches
Removed 3 gone tracking branches
Pruned 5 stale remote references

Before: 23 branches
After: 10 branches

Recovery available via reflog for 30 days.
Run `git reflog` to see recent deletions.

Advanced Operations

Delete Unmerged Branches (Risky)

Only with explicit user confirmation:

# Force delete unmerged branch (DESTRUCTIVE)
git branch -D branch-name

# Before deletion, save the commit hash
git rev-parse branch-name
# Outputs: abc123def456...

# Recovery command (save this for user):
echo "To recover: git checkout -b branch-name abc123def456"

Bulk Remote Cleanup

# List merged remote branches
git branch -r --merged main | grep origin | grep -v 'main\|master\|develop\|HEAD'

# Delete them (requires push access)
git branch -r --merged main | grep origin | grep -v 'main\|master\|develop\|HEAD' | sed 's/origin\///' | xargs -n 1 git push origin --delete

Sync with GitHub PR Status

If gh CLI is available:

# Check if branch has merged PR
gh pr list --state merged --json headRefName --jq '.[].headRefName'

# Safe delete only branches with merged PRs
gh pr list --state merged --json headRefName --jq '.[].headRefName' | xargs -n 1 git branch -d

Recovery Procedures

Recover Recently Deleted Branch

# Find the commit in reflog
git reflog --no-merges --since="2 weeks ago" | grep -i "branch-name"

# Recreate branch at that commit
git checkout -b branch-name <commit-hash>

Restore All Recent Deletions

# Show all branch deletions in last 30 days
git reflog --date=relative | grep 'moving from' | head -20

# Interactive restore (user picks what to recover)
git reflog | grep 'branch:' | head -20

Command Modes

Dry Run (default)

Show what would be deleted without making changes:

# Just list, don't delete
git branch --merged main | grep -v "^\*\|main\|master\|develop"

Interactive Mode

Confirm each deletion:

# Loop with confirmation
git branch --merged main | grep -v "^\*\|main\|master\|develop" | while read branch; do
  echo "Delete $branch? (y/n)"
  read answer
  if [ "$answer" = "y" ]; then
    git branch -d "$branch"
  fi
done

Force Mode

Delete without confirmation (use carefully):

# Batch delete merged branches
git branch --merged main | grep -v "^\*\|main\|master\|develop" | xargs -n 1 git branch -d

Best Practices

1. Run git fetch before cleanup - Ensure branch merge status is current
2. Check git status - No uncommitted changes in the current branch
3. Use -d (lowercase) for merged - Safer than -D (force)
4. Keep reflog accessible - Don't run git gc during cleanup
5. Document large cleanups - Note what was deleted and why
6. Test in dry-run first - Always preview before executing

Common Patterns

Weekly Maintenance:

# Standard weekly cleanup routine
git fetch --all --prune
git branch --merged main | grep -v "^\*\|main\|master\|develop" | xargs -n 1 git branch -d
git remote prune origin

Post-Release Cleanup:

# Clean up release branches after successful deploy
git branch | grep 'release/' | grep -v "$(git branch --show-current)" | xargs -n 1 git branch -d

Pre-PR Review:

# Clean workspace before creating new feature
git fetch origin main:main
git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d

Output Format

Always provide a structured summary:

Git Branch Cleanup Report
=========================
Date: YYYY-MM-DD HH:MM

Summary
-------
Action: [Dry Run / Cleanup Executed]
Branches analyzed: N
Branches deleted: N
Remote references pruned: N

Details
-------
Deleted merged branches:
- feature/user-auth (merged 2024-02-15)
- bugfix/login-fix (merged 2024-02-20)

Gone tracking branches removed:
- feature/experiment (remote deleted)

Protected (kept):
- main
- develop
- current-feature

Recovery
--------
All deletions are recoverable via reflog for 30 days.
To see recent changes: git reflog --date=relative | head -20
To recover a branch: git checkout -b <branch-name> <commit-hash>

Next Steps
----------
Repository is now organized with N active branches.
Consider running this cleanup monthly or after major releases.

Remember

The goal is to maintain a clean, organized repository without losing work. Always err on the side of caution - it's better to keep an extra branch than to lose important work. Recovery via reflog is possible but prevention is better.