Overview

Branch-cleaner identifies stale branches and provides explicit, safe delete or prune commands. It emphasizes reversible steps and requires user confirmation, with protections for base branches and user-defined patterns.

How This Skill Works

It begins with git fetch --prune and status checks, then builds candidate lists: local merged into base, local not merged, remote merged, and date-based stales. After excluding protected branches and the current base, it presents grouped candidates for user confirmation before executing deletions (local or remote) as approved.

When to Use It

• To prune local branches that have been merged into the base branch.
• To audit branch hygiene across local and remote repositories.
• To identify not-merged branches for potential cleanup while keeping safe patterns.
• When you need to respect protected patterns (e.g., release/*, hotfix/*) during pruning.
• When you want a user-confirmed, reversible workflow before deleting branches, including optional remote deletions.

Quick Start

1. Step 1: Run git fetch --prune and check git status to note uncommitted changes.
2. Step 2: Build and inspect candidate lists using git branch --merged <base>, git branch --no-merged <base>, git branch -r --merged <base>, and git for-each-ref --sort=committerdate refs/heads.
3. Step 3: Exclude protected patterns and obtain explicit user approval before executing delete commands (local and remote).

Best Practices

• Run git fetch --prune before analyzing candidates.
• Define and honor protected patterns and the base/default branch.
• Review merged vs. not-merged lists and flag warnings for recently updated branches.
• Use a dry-run/listing step and require explicit user confirmation prior to deletion.
• Don’t delete remote branches unless you have explicit approval and a confirmed plan to revert if needed.

Example Use Cases

• Prune local branches merged into main to clean up a feature branch workflow.
• Audit origin/remotes to identify stale branches not merged into the base.
• Exclude release/* and hotfix/* while pruning to preserve critical branches.
• Verify merged status with gh pr list --state merged --base <base> and gh pr view <branch> if needed.
• Use git for-each-ref to list stale branches by committer date for long-unused branches.

Frequently Asked Questions