git-branch-cleanup

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
# 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:

| Category | Description | Safety |
|----------|-------------|--------|
| **Merged (Safe)** | Already merged to base branch | Safe to delete |
| **Gone Remote** | Remote branch deleted | Review recommended |
| **Stale** | No commits for 30+ days | Needs review |
| **Has Worktree** | Branch checked out in a worktree (`+` prefix in `git branch -v`) | Remove worktree first |
| **Ahead of Upstream** | Has unpushed commits | ⚠️ Do not delete |
| **Unmerged** | Active work in progress | Use caution |

> **Note**: 30 days is a reasonable default for stale detection. Adjust based on team's sprint cycle if needed (e.g., 14 days for 2-week sprints).

### Step 3: Display Format

```
## Branch Analysis Results

### Safe to Delete (Merged)
  - feature/login (3 weeks ago) - Add login feature
  - fix/typo (2 months ago) - Fix typo in readme

### Remote Deleted
  - feature/old-api (1 month ago) - Remote branch no longer exists

### ⚠️ Ahead of Upstream (DO NOT DELETE)
  - feature/wip (1 day ago) - Has 3 unpushed commits

### Stale Branches (30+ days)
  - experiment/cache (2 months ago) - Unmerged

### Active (Unmerged)
  - feature/new-dashboard (2 days ago) - Work in progress

---
Which categories would you like to delete?
1. Merged only (safest)
2. Merged + remote deleted
3. Select individually
```

### Step 4: Safety Guards

**Never delete these branches:**
- `main`
- `master`
- `trunk`
- `develop`
- `development`
- Currently checked out branch

Always confirm before deletion:
```
The following branches will be deleted:
  - feature/login
  - fix/typo

Continue? (y/N)
```

From gotalab/skillport, MIT.

More from gotalab/skillport