---
description: Clean up old and defunct branches that are no longer needed
argument-hint: [--dry-run] [--merged-only] [--remote]
---

## Name
git:branch-cleanup

## Synopsis
```
/git:branch-cleanup [--dry-run] [--merged-only] [--remote]
```

## Description
The `git:branch-cleanup` command identifies and removes old, defunct, or merged branches from your local repository (and optionally from remote). It helps maintain a clean repository by removing branches that are no longer needed, such as:
- Branches that have been merged into the main branch
- Branches that no longer exist on the remote
- Stale feature branches from completed work

The command performs safety checks to prevent deletion of:
- The current branch
- Protected branches (main, master, develop, etc.)
- Branches with unmerged commits (unless explicitly overridden)

The spec sections is inspired by https://man7.org/linux/man-pages/man7/man-pages.7.html#top_of_page

## Implementation
The command should follow these steps:

1. **Identify Main Branch**
   - Detect the primary branch (main, master, etc.)
   - Use `git symbolic-ref refs/remotes/origin/HEAD` or `git branch -r` to determine

2. **Gather Branch Information**
   - List all local branches: `git branch`
   - Get current branch: `git branch --show-current`
   - Identify merged branches: `git branch --merged <main-branch>`
   - Check remote tracking: `git branch -vv`
   - Find remote-deleted branches: `git remote prune origin --dry-run`

3. **Categorize Branches**
   - **Merged branches**: Fully merged into main branch
   - **Gone branches**: Remote tracking branch no longer exists
   - **Stale branches**: Last commit older than threshold (e.g., 3 months)
   - **Protected branches**: main, master, develop, release/*, hotfix/*

4. **Present Analysis to User**
   - Show categorized list of branches with:
     - Branch name
     - Last commit date
     - Merge status
     - Remote tracking status
     - Number of commits ahead/behind
   - Recommend branches safe to delete

5. **Confirm Deletion**
   - Ask user to confirm which branches to delete
   - Present options: all merged, all gone, specific branches, or custom selection
   - If `--dry-run` flag is present, only show what would be deleted

6. **Delete Branches**
   - Local deletion: `git branch -d <branch>` (merged) or `git branch -D <branch>` (force)
   - Remote deletion (if `--remote` flag): `git push origin --delete <branch>`
   - Prune remote references: `git remote prune origin`

7. **Report Results**
   - List deleted branches
   - Show any errors or branches that couldn't be deleted
   - Provide summary statistics

Implementation logic:
```bash
# Determine main branch
main_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$main_branch" ]; then
  main_branch="main"  # fallback
fi

# Get current branch
current_branch=$(git branch --show-current)

# Find merged branches
git branch --merged "$main_branch" | grep -v "^\*" | grep -v "$main_branch"

# Find branches with deleted remotes ("gone")
git branch -vv | grep ': gone]' | awk '{print $1}'

# Find stale branches (older than 3 months)
git for-each-ref --sort=-committerdate --format='%(refname:short)|%(committerdate:iso)|%(upstream:track)' refs/heads/

# Delete local branch (merged)
git branch -d <branch-name>

# Delete local branch (force)
git branch -D <branch-name>

# Delete remote branch
git push origin --delete <branch-name>

# Prune remote references
git remote prune origin
```

## Return Value
- **Claude agent text**: Analysis and results including:
  - List of branches categorized by status (merged, gone, stale)
  - Recommendation for which branches are safe to delete
  - Confirmation prompt for user approval
  - Summary of deleted branches and any errors
  - Statistics (e.g., "Deleted 5 branches, freed X MB")

## Examples

1. **Basic usage (interactive)**:
   ```
   /git:branch-cleanup
   ```
   Output:
   ```
   Analyzing branches in repository...

   Main branch: main
   Current branch: feature/new-api

   === Merged Branches (safe to delete) ===
   feature/bug-fix-123        Merged 2 weeks ago
   feature/update-deps        Merged 1 month ago

   === Gone Branches (remote deleted) ===
   feature/old-feature        Remote: gone
   hotfix/urgent-fix          Remote: gone

   === Stale Branches (no activity > 3 months) ===
   experiment/prototype       Last commit: 4 months ago, not merged

   === Protected Branches (will not delete) ===
   main
   develop

   Recommendations:
   - Safe to delete: feature/bug-fix-123, feature/update-deps (merged)
   - Safe to delete: feature/old-feature, hotfix/urgent-fix (remote gone)
   - Review needed: experiment/prototype (unmerged, stale)

   What would you like to delete?
   ```

2. **Dry run (preview only)**:
   ```
   /git:branch-cleanup --dry-run
   ```
   Output:
   ```
   [DRY RUN MODE - No changes will be made]

   Would delete the following merged branches:
   - feature/bug-fix-123
   - feature/update-deps

   Would delete the following gone branches:
   - feature/old-feature
   - hotfix/urgent-fix

   Total: 4 branches would be deleted
   ```

3. **Merged branches only**:
   ```
   /git:branch-cleanup --merged-only
   ```
   Output:
   ```
   Analyzing merged branches...

   Found 3 merged branches:
   - feature/bug-fix-123
   - feature/update-deps
   - feature/ui-improvements

   Delete these branches? (y/n)
   ```

4. **Including remote cleanup**:
   ```
   /git:branch-cleanup --remote
   ```
   Output:
   ```
   Deleting local and remote branches...

   ✓ Deleted local: feature/bug-fix-123
   ✓ Deleted remote: origin/feature/bug-fix-123
   ✓ Deleted local: feature/update-deps
   ✓ Deleted remote: origin/feature/update-deps

   Summary: Deleted 2 branches locally and remotely
   ```

## Arguments
- `--dry-run`: Preview which branches would be deleted without actually deleting them
- `--merged-only`: Only consider branches that have been fully merged into the main branch
- `--remote`: Also delete branches from the remote repository (requires push permissions)
- `--force`: Force delete branches even if they have unmerged commits (use with caution)
- `--older-than=<days>`: Only consider branches with no commits in the last N days (default: 90)

## Safety Considerations
- **Never delete**: Current branch, main, master, develop, or release/* branches
- **Require confirmation**: Always ask user before deleting branches
- **Preserve unmerged work**: By default, only delete merged branches unless `--force` is used
- **Backup suggestion**: Recommend creating a backup of unmerged branches before deletion
- **Remote deletion**: Only delete remote branches if user explicitly requests with `--remote` flag