cleaning-up-branches

What this skill does

# Branch Cleanup

Delete merged branches (local and optionally remote) with explicit user confirmation, and flag stale unmerged branches for manual review.

## Auto-Invoke Triggers

This skill activates when:

1. **Keywords**: "cleanup branches", "delete merged branches", "prune old branches", "remove stale branches", "branch cleanup", "remove dead branches"
2. **Command**: `/cleanup-branches`

## Arguments

- `--base <branch>` — Base branch for merge check (default: main)
- `--threshold <months>` — Inactivity threshold for stale detection (default: 3)
- `--remote` — Include remote branch deletion
- `--dry-run` — Show what would be deleted without acting

## Safety Model

- **Merged branches**: Deletable after explicit user confirmation
- **Unmerged branches**: Never auto-deleted — reported with manual commands only
- **Dry-run**: Available via `--dry-run` flag to preview actions
- **Confirmation**: Before each destructive step, list branches and ask the user

## Workflow

Execute each step below using the Bash tool.

### Step 1: Validate Git Repository

```bash
git rev-parse --is-inside-work-tree 2>/dev/null || echo "NOT_A_GIT_REPO"
```

If not a git repo, stop and inform the user.

### Step 2: Parse Arguments

Parse `$ARGUMENTS` for:
- `--base BRANCH` → set BASE_BRANCH=BRANCH (default: main)
- `--threshold N` → set THRESHOLD_MONTHS=N (default: 3)
- `--remote` → set INCLUDE_REMOTE=true (default: false)
- `--dry-run` → set DRY_RUN=true (default: false)

Verify the base branch exists:

```bash
git rev-parse --verify "$BASE_BRANCH" 2>/dev/null || echo "BASE_BRANCH_NOT_FOUND"
```

If the base branch doesn't exist, try `master` as fallback. If neither exists, stop and inform the user.

### Step 3: Fetch Latest Remote State

```bash
if ! git fetch --prune 2>/dev/null; then
  echo "Warning: Could not reach remote. Remote branch data may be stale."
fi
```

### Step 4: Display Branch Status Summary

```bash
current_branch=$(git branch --show-current)
total_local=$(git branch | wc -l | tr -d ' ')
total_remote=$(git branch -r | grep -v HEAD | wc -l | tr -d ' ')
remote=$(git config --get "branch.$BASE_BRANCH.remote" 2>/dev/null || echo "origin")
merged_local=$(git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | wc -l | tr -d ' ')
merged_remote=$(git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | wc -l | tr -d ' ')

echo "=== BRANCH STATUS ==="
echo "Current branch: $current_branch"
echo "Base branch: $BASE_BRANCH"
echo "Local branches: $total_local ($merged_local merged into $BASE_BRANCH)"
echo "Remote branches: $total_remote ($merged_remote merged into $BASE_BRANCH)"
```

Present this summary to the user.

### Step 5: Local Merged Branch Cleanup

List local branches merged into base (excluding base and current branch):

```bash
git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | while IFS= read -r branch; do
  branch="${branch## }"
  last_commit=$(git log -1 --format='%ci' "$branch" 2>/dev/null | cut -d' ' -f1)
  echo "  $branch  (last commit: ${last_commit:-unknown})"
done
```

Count:

```bash
merged_count=$(git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | wc -l | tr -d ' ')
if [ "$merged_count" -eq 0 ]; then
  echo "  (none)"
fi
echo "Found $merged_count local merged branch(es)"
```

**If merged branches exist and not `--dry-run`:**

Ask the user for confirmation using natural conversation: _"These N branches are merged into BASE_BRANCH. Delete them?"_

If confirmed, delete each branch:

```bash
git branch --merged "$BASE_BRANCH" | grep -v "^\*" | grep -vw "$BASE_BRANCH" | while IFS= read -r branch; do
  branch="${branch## }"
  git branch -d "$branch"
done
```

**If `--dry-run`:** Display what would be deleted but skip the deletion.

### Step 6: Squash-Merged Branch Cleanup

Detect branches whose changes are already in base via squash-and-merge or rebase-merge. Uses `git cherry` to compare patch-ids.

```bash
echo "=== SQUASH-MERGED BRANCHES ==="
squash_branches=""
for branch in $(git for-each-ref --format='%(refname:short)' refs/heads/); do
  [ "$branch" = "$BASE_BRANCH" ] && continue
  current=$(git branch --show-current)
  [ "$branch" = "$current" ] && continue

  # Skip branches already detected as merged
  merged=$(git branch --merged "$BASE_BRANCH" | grep -w "$branch" | wc -l | tr -d ' ')
  [ "$merged" -gt 0 ] && continue

  # Count commits on branch since merge-base
  merge_base=$(git merge-base "$BASE_BRANCH" "$branch" 2>/dev/null)
  [ -z "$merge_base" ] && continue
  unique_commits=$(git log --oneline "$merge_base".."$branch" --no-merges 2>/dev/null | wc -l | tr -d ' ')
  [ "$unique_commits" -eq 0 ] && continue

  # git cherry: + means NOT in base, - means equivalent exists in base
  unpicked=$(git cherry "$BASE_BRANCH" "$branch" 2>/dev/null | grep '^+' | wc -l | tr -d ' ')
  if [ "$unpicked" -eq 0 ]; then
    relative=$(git log -1 --format='%cr' "$branch")
    echo "  $branch ($relative)"
    squash_branches="$squash_branches $branch"
  fi
done
squash_count=$(echo "$squash_branches" | wc -w | tr -d ' ')
if [ "$squash_count" -eq 0 ]; then
  echo "  (none)"
fi
echo "Found $squash_count squash-merged branch(es)"
```

**If squash-merged branches exist and not `--dry-run`:**

Ask the user for confirmation: _"These N branches were squash-merged into BASE_BRANCH (verified via git cherry). Delete them?"_

If confirmed, delete each branch. Note: must use `-D` (force) since git doesn't recognize squash merges as merged:

```bash
for branch in $squash_branches; do
  git branch -D "$branch"
done
```

**If `--dry-run`:** Display what would be deleted but skip the deletion.

### Step 7: Remote Merged Branch Cleanup (if --remote)

Only execute if `--remote` flag was provided.

List remote branches merged into base:

```bash
git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | while IFS= read -r branch; do
  branch="${branch## }"
  short_name="${branch#$remote/}"
  last_commit=$(git log -1 --format='%ci' "$branch" 2>/dev/null | cut -d' ' -f1)
  echo "  $short_name  (last commit: ${last_commit:-unknown})"
done
```

Count:

```bash
remote_merged=$(git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | wc -l | tr -d ' ')
if [ "$remote_merged" -eq 0 ]; then
  echo "  (none)"
fi
echo "Found $remote_merged remote merged branch(es)"
```

**If remote merged branches exist and not `--dry-run`:**

Ask the user for confirmation: _"These N remote branches are merged. Delete them from $remote?"_

If confirmed, delete each remote branch:

```bash
git branch -r --merged "$remote/$BASE_BRANCH" | grep -v "$remote/$BASE_BRANCH" | grep -v "$remote/HEAD" | while IFS= read -r branch; do
  branch="${branch## }"
  short_name="${branch#$remote/}"
  git push "$remote" --delete "$short_name"
done
```

**If `--dry-run`:** Display what would be deleted but skip the deletion.

### Step 8: Stale Unmerged Branch Report

List inactive unmerged branches (past threshold) with ahead/behind counts. **Never delete these** — only display them.

Calculate threshold:

```bash
if [[ "$OSTYPE" == "darwin"* ]]; then
  threshold=$(date -v-${THRESHOLD_MONTHS}m +%s)
else
  threshold=$(date -d "${THRESHOLD_MONTHS} months ago" +%s)
fi
```

Scan for stale unmerged branches:

```bash
echo "=== STALE UNMERGED BRANCHES (manual review required) ==="
git for-each-ref --sort=committerdate --format='%(refname:short) %(committerdate:unix) %(committerdate:relative)' refs/heads/ | while IFS= read -r line; do
  branch=$(echo "$line" | awk '{print $1}')
  timestamp=$(echo "$line" | awk '{print $2}')
  relative=$(echo "$line" | cut -d' ' -f3-)

  # Skip base branch and squash-merged branches (already handled in Step 6)
  [ "$branch" = "$BASE_BRANCH" ] && continue
  echo "$squash_branches" | grep -qw "$branch" && continue

  if [[ "$timestamp" =~ ^[0-9]+$ ]] && [ "$timestamp" -lt "$th