Branch Cleanup

Automated workflow to sync main with origin and clean up local branches that have merged PRs.

Quick Start

When user asks to "clean up branches" or "delete merged branches":

Pre-flight checks:

• git fetch origin (update remote refs)

• git branch --show-current (verify current branch)

• If not on main: Ask user: "Should I switch to main? (Current: {branch})"

Sync main:

• git checkout main

• git pull origin main --ff-only

• If conflicts: ⚠️ Stop and report "Main has conflicts. Resolve manually."

List local branches:

• git branch --format='%(refname:short)'

• Filter out: main , master , develop , staging , production , archive*

• If no branches: Report "No local branches to clean up" and STOP.

Check PR status for each branch:

• Get PR for branch: gh pr list --head {branch} --state merged --json number,title,url

• If merged PR found: Add to cleanup list

• If no PR or not merged: Skip

Present cleanup list:

• Show table with: branch name, PR number, PR title, PR URL

• Ask user: "Delete these {count} branches? (y/n)"

• If user declines: STOP.

Delete branches:

• For each approved branch:

• git branch -d {branch} (safe delete)

• If fails with unmerged warning: Show warning and skip

• If succeeds: Report "✅ Deleted {branch}"

• Final summary: "Deleted {count} branches, skipped {count} unmerged branches"

Workflow Details

Step 1: Pre-flight Checks

Fetch latest remote refs

git fetch origin

Check current branch

CURRENT_BRANCH=$(git branch --show-current)

If not on main:

• Show: "Currently on {CURRENT_BRANCH} . Switch to main?"

• Wait for user confirmation

Safety:

• Never switch branches with uncommitted changes

• Check: git status --porcelain (must be empty)

Step 2: Sync Main

Switch to main

git checkout main

Fast-forward merge only (no conflicts)

git pull origin main --ff-only

If fast-forward fails:

• ⚠️ Stop with error: "Main branch has diverged from origin. Manual resolution required."

• Do NOT attempt merge or rebase

Step 3: Identify Merged Branches

For each local branch:

Get merged PR for branch

gh pr list --head {branch} --state merged --json number,title,url --limit 1

Branch categories:

Status Action

Merged PR found Add to cleanup list

Open PR found Skip (not merged)

No PR found Skip (might be local work)

Protected branch Skip (main, master, etc.)

Protected branches:

• main , master , develop , staging , production

• Any branch starting with archive (e.g., archive-2024 , archive/old )

• Any branch matching origin/*

Step 4: Present Cleanup List

Format as markdown table:

Branches with merged PRs

Total: 2 branches

User prompt: "Delete these branches? They have merged PRs and are safe to remove. (y/n)"

Step 5: Safe Deletion

Safe delete (only if fully merged)

git branch -d {branch}

If git branch -d fails:

• Shows: "The branch '{branch}' is not fully merged."

• Action: Skip and report to user

• Reason: Prevents data loss

Force delete (-D ) is NEVER used automatically.

Edge Cases

No Merged Branches

If no branches qualify for cleanup:

✅ All local branches are up to date. No merged branches found for cleanup.

Partially Merged Branches

If branch has commits not in main but PR is merged:

• git branch -d will fail (expected)

• Report: "⚠️ Skipped {branch}: has unmerged commits (possible rebase)"

• User can manually verify with: git log main..{branch}

Archive Branches

Branches starting with archive are preserved:

• ❌ Skip: archive-2024 , archive/backup , archive-old-features

• Reason: Archive branches contain historical work that should be manually managed

Remote Tracking Branches

Only delete local branches, never remote refs:

• ✅ Delete: fxstein/AIT-12-feature

• ❌ Skip: origin/fxstein/AIT-12-feature

Use git push origin --delete {branch} only if user explicitly requests remote deletion.

Error Handling

If ANY error occurs:

• STOP IMMEDIATELY

• Report the specific error

• Show current state: branch name, operation attempted

• WAIT for user input

Common errors:

Error Cause Action

"Not on main" Current branch not main Ask to switch

"Fast-forward failed" Main diverged from origin Stop, manual resolution

"gh command not found" GitHub CLI not installed Stop, ask user to install

"Branch not fully merged" Branch has unmerged commits Skip branch

Safety Guarantees

• ✅ Never force-delete (-D ) branches

• ✅ Never delete without user confirmation

• ✅ Never modify remote branches

• ✅ Never switch branches with uncommitted changes

• ✅ Always use --ff-only for main sync

Output Format

Success

🔄 Syncing main with origin... ✅ Main is up to date

📋 Found 3 branches with merged PRs:

• fxstein/AIT-12-feature (PR #45)
• oliver/ait-8-bugfix (PR #38)
• fxstein/AIT-10-docs (PR #42)

🗑️ Deleting branches... ✅ Deleted fxstein/AIT-12-feature ✅ Deleted oliver/ait-8-bugfix ✅ Deleted fxstein/AIT-10-docs

✨ Cleanup complete: 3 branches deleted

With Skipped Branches

🗑️ Deleting branches... ✅ Deleted fxstein/AIT-12-feature ⚠️ Skipped fxstein/AIT-15-wip: not fully merged ✅ Deleted oliver/ait-8-bugfix

✨ Cleanup complete: 2 deleted, 1 skipped

Additional Features

Dry Run Mode

If user asks for "preview" or "dry run":

• Execute steps 1-4 only

• Show cleanup list

• STOP before deletion

Delete Remote Branches

If user explicitly asks to "delete remote branches too":

• After local deletion succeeds

• For each deleted branch: git push origin --delete {branch}

• Report: "✅ Deleted {branch} (local + remote)"

Requirements

• Git: Version 2.0+

• GitHub CLI (gh): Required for PR status checks

• Repository: Must be a git repository with GitHub remote

Forbidden Actions

• ❌ Never use git branch -D (force delete)

• ❌ Never delete branches without user confirmation

• ❌ Never modify main , master , or protected branches

• ❌ Never attempt merge/rebase to resolve conflicts