Branch Cleanup

Branch Cleanup Command

Clean up merged and stale branches from local and remote repositories.

Usage

/branch-cleanup [<project-name>] [options]
/branch-cleanup [--execute] [--include-remote] [--stale-days <days>]

Example:

/branch-cleanup                                    # Dry-run preview (default), local only
/branch-cleanup --execute                          # Actually delete the previewed branches
/branch-cleanup hospital_erp_system                # Preview specific project
/branch-cleanup --execute --include-remote --stale-days 30  # Delete, include remote, 30-day threshold

Arguments

• <project-name>: Optional project directory name (defaults to current directory)

Options

By default (no --execute) the command performs a read-only dry-run preview and deletes nothing. Confirmation happens at invocation time by adding --execute — there is no interactive mid-run prompt, so the command is scriptable.

Protected Branches

The following branches are never deleted, regardless of their merge status:

Instructions

Execute the following workflow:

1. Navigate to Project

# If project name provided
cd <project-name> 2>/dev/null || { echo "Error: Project directory not found"; exit 1; }

# Fetch latest remote state
git fetch --prune origin

2. Identify Merged Branches

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

# List branches merged into develop, main, or master
MERGED_BRANCHES=$(
  { git branch --merged develop 2>/dev/null; \
    git branch --merged main 2>/dev/null; \
    git branch --merged master 2>/dev/null; } | sort -u
)

# Filter out protected branches and current branch
echo "$MERGED_BRANCHES" | grep -v -E "^\*|main|master|develop|release/|hotfix/"

3. Identify Stale Branches

# Find branches with no commits in the last N days
STALE_THRESHOLD=$(date -d "$STALE_DAYS days ago" +%s 2>/dev/null || date -v-${STALE_DAYS}d +%s)

for branch in $(git branch --format='%(refname:short)'); do
    LAST_COMMIT=$(git log -1 --format='%ct' "$branch" 2>/dev/null)
    if [[ -n "$LAST_COMMIT" && "$LAST_COMMIT" -lt "$STALE_THRESHOLD" ]]; then
        echo "$branch (stale: no commits in $STALE_DAYS days)"
    fi
done

4. Display Branches for Cleanup

Present categorized results:

## Branches Identified for Cleanup

### Merged Branches (safe to delete)
- feat/issue-123-add-login
- fix/issue-456-null-check

### Stale Branches (no commits in 90+ days)
- feat/old-experiment (last commit: 2024-06-15)
- fix/abandoned-fix (last commit: 2024-05-20)

### Protected Branches (will NOT be deleted)
- main
- develop
- release/v2.0

5. Gate Deletion on --execute

The default run is a read-only dry-run preview. Stop here unless --execute was passed — the user confirms by re-invoking with the flag, so there is no interactive prompt.

# Without --execute, this is a preview only: report and exit without deleting.
if [[ "$EXECUTE" != "true" ]]; then
    echo "Dry-run preview only. Re-run with --execute to delete the above branches."
    exit 0
fi

6. Delete Local Branches

for branch in $BRANCHES_TO_DELETE; do
    # Skip protected branches
    if [[ "$branch" =~ ^(main|master|develop|release/|hotfix/) ]]; then
        echo "Skipping protected branch: $branch"
        continue
    fi

    # Delete local branch
    git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
    echo "Deleted local branch: $branch"
done

7. Delete Remote Branches (if --include-remote)

if [[ "$INCLUDE_REMOTE" == "true" ]]; then
    for branch in $REMOTE_BRANCHES_TO_DELETE; do
        # Skip protected branches
        if [[ "$branch" =~ ^(main|master|develop|release/|hotfix/) ]]; then
            echo "Skipping protected remote branch: $branch"
            continue
        fi

        git push origin --delete "$branch"
        echo "Deleted remote branch: $branch"
    done
fi

8. Report Results

Provide summary of actions taken.

Policies

See _policy.md for common rules.

Command-Specific Rules

Output

After completion, provide summary:

## Branch Cleanup Summary

| Item | Value |
|------|-------|
| Project | <project-name> |
| Mode | Dry-run / Executed |
| Stale threshold | 90 days |

### Deleted Branches
| Branch | Type | Last Commit |
|--------|------|-------------|
| feat/issue-123 | merged | 2024-12-01 |
| fix/old-bug | stale | 2024-06-15 |

### Skipped Branches
| Branch | Reason |
|--------|--------|
| main | Protected |
| develop | Protected |
| feat/current-work | Current branch |

### Statistics
- Local branches deleted: N
- Remote branches deleted: N
- Total branches cleaned: N

Error Handling

Prerequisites Check

Runtime Errors

Side Effects and Loop-Safety

This skill is loop_safe: false. It deletes merged and stale local/remote branches. Repeated invocation is a destructive cascade with nothing left to do after the first pass, and could race against concurrent branch creation. Run it once per cleanup; do not wrap it in /loop.