Git Branch Cleanup & Organization

Clean up merged branches and organize repository structure: $ARGUMENTS

Current Repository State

• All branches: !git branch -a
• Recent branches: !git for-each-ref --count=10 --sort=-committerdate refs/heads/ --format='%(refname:short) - %(committerdate:relative)'
• Remote branches: !git branch -r
• Merged branches: !git branch --merged main 2>/dev/null || git branch --merged master 2>/dev/null || echo "No main/master branch found"
• Current branch: !git branch --show-current

Task

Perform comprehensive branch cleanup and organization based on the repository state and provided arguments.

Cleanup Operations

1. Identify Branches for Cleanup

• Merged branches: Find local branches already merged into main/master
• Stale remote branches: Identify remote-tracking branches that no longer exist
• Old branches: Detect branches with no recent activity (>30 days)
• Feature branches: Organize feature/ hotfix/ release/* branches

2. Safety Checks Before Deletion

• Verify branches are actually merged using git merge-base
• Check if branches have unpushed commits
• Confirm branches aren't the current working branch
• Validate against protected branch patterns

3. Branch Categories to Handle

• Safe to delete: Merged feature branches, old hotfix branches
• Needs review: Unmerged branches with old commits
• Keep: Main branches (main, master, develop), active feature branches
• Archive: Long-running branches that might need preservation

4. Remote Branch Synchronization

• Remove remote-tracking branches for deleted remotes
• Prune remote references with git remote prune origin
• Update branch tracking relationships
• Clean up remote branch references

Command Modes

Default Mode (Interactive)

• Show branch analysis with recommendations
• Ask for confirmation before each deletion
• Provide summary of actions taken
• Offer to push deletions to remote

Dry Run Mode (--dry-run)

• Show what would be deleted without making changes
• Display branch analysis and recommendations
• Provide cleanup statistics
• Exit without modifying repository

Force Mode (--force)

• Delete merged branches without confirmation
• Clean up stale remotes automatically
• Provide summary of all actions taken
• Use with caution - no undo capability

Remote Only (--remote-only)

• Only clean up remote-tracking branches
• Synchronize with actual remote state
• Remove stale remote references
• Keep all local branches intact

Local Only (--local-only)

• Only clean up local branches
• Don't affect remote-tracking branches
• Keep remote synchronization intact
• Focus on local workspace organization

Safety Features

Pre-cleanup Validation

• Ensure working directory is clean
• Check for uncommitted changes
• Verify current branch is safe (not target for deletion)
• Create backup references if requested

Protected Branches

Never delete branches matching these patterns:

• main, master, develop, staging, production
• release/* (unless explicitly confirmed)
• Current working branch
• Branches with unpushed commits (unless forced)

Recovery Information

• Display git reflog references for deleted branches
• Provide commands to recover accidentally deleted branches
• Show SHA hashes for branch tips before deletion
• Create recovery script if multiple branches deleted

Branch Organization Features

Naming Convention Enforcement

• Suggest renaming branches to follow team conventions
• Organize branches by type (feature/, bugfix/, hotfix/)
• Identify branches that don't follow naming patterns
• Provide batch renaming suggestions

Branch Tracking Setup

• Set up proper upstream tracking for feature branches
• Configure push/pull behavior for new branches
• Identify branches missing upstream configuration
• Fix broken tracking relationships

Output and Reporting

Cleanup Summary

Branch Cleanup Summary:
✅ Deleted 3 merged feature branches
✅ Removed 5 stale remote references
✅ Cleaned up 2 old hotfix branches
⚠️  Found 1 unmerged branch requiring attention
📊 Repository now has 8 active branches (was 18)

Recovery Instructions

Branch Recovery Commands:
git checkout -b feature/user-auth 1a2b3c4d  # Recover feature/user-auth
git push origin feature/user-auth            # Restore to remote

Best Practices

Regular Maintenance Schedule

• Run cleanup weekly for active repositories
• Use --dry-run first to review changes
• Coordinate with team before major cleanups
• Document any non-standard branches to preserve

Team Coordination

• Communicate branch deletion plans with team
• Check if anyone has work-in-progress on old branches
• Use GitHub/GitLab branch protection rules
• Maintain shared documentation of branch policies

Branch Lifecycle Management

• Delete feature branches immediately after merge
• Keep release branches until next major release
• Archive long-term experimental branches
• Use tags to mark important branch states before deletion

Example Usage

# Safe interactive cleanup
/branch-cleanup

# See what would be cleaned without changes
/branch-cleanup --dry-run

# Clean only remote tracking branches
/branch-cleanup --remote-only

# Force cleanup of merged branches
/branch-cleanup --force

# Clean only local branches
/branch-cleanup --local-only

Integration with GitHub/GitLab

If GitHub CLI or GitLab CLI is available:

• Check PR status before deleting branches
• Verify branches are actually merged in web interface
• Clean up both local and remote branches consistently
• Update branch protection rules if needed