git-clean-branches

name	git-clean-branches
description	Safely find and clean up merged or stale Git branches with dry-run mode and custom base/protected branches support
disable-model-invocation	true
allowed-tools	Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()

Claude Command: Clean Branches

This command safely identifies and cleans up merged or stale Git branches. Runs in read-only preview (--dry-run) mode by default, requiring explicit instructions to perform deletions.

---

Usage

# [Safest] Preview branches to be cleaned without executing any deletions
/git-cleanBranches --dry-run

# Clean local branches merged to main and inactive for over 90 days (requires individual confirmation)
/git-cleanBranches --stale 90

# Clean local and remote branches merged to release/v2.1 (auto-confirm)
/git-cleanBranches --base release/v2.1 --remote --yes

# [Dangerous] Force delete an unmerged local branch
/git-cleanBranches --force outdated-feature

Options

• --base <branch>: Specify the base branch for cleanup (defaults to repository's main/master).
• --stale <days>: Clean branches with no commits for specified days (disabled by default).
• --remote: Also clean remote merged/stale branches.
• --dry-run: Default behavior. Only list branches to be deleted without executing any operations.
• --yes: Skip individual confirmations and delete all identified branches directly (suitable for CI/CD).
• --force: Use -D to force delete local branches (even if unmerged).

---

What This Command Does

1. Configuration and Safety Checks

   • Update Information: Automatically executes git fetch --all --prune to ensure branch status is current.
   • Read Protected Branches: Reads the list of branches that should not be cleaned from Git config (see "Configuration" below).
   • Determine Base: Uses --base parameter or auto-detected main/master as comparison baseline.

2. Analysis and Identification (Find)

   • Merged Branches: Find local (and remote if --remote is added) branches fully merged to --base.
   • Stale Branches: If --stale <days> is specified, find branches with last commit N days ago.
   • Exclude Protected Branches: Remove all configured protected branches from cleanup list.

3. Report and Preview (Report)

   • Clearly list "merged branches to be deleted" and "stale branches to be deleted".
   • Without --yes parameter, command ends here, waiting for user confirmation to re-execute (without --dry-run).

4. Execute Cleanup (Execute)

   • Only executed without --dry-run and after user confirmation (or with --yes).
   • Delete identified branches one by one, unless user chooses to skip in interactive confirmation.
   • Local: git branch -d <branch>; Remote: git push origin --delete <branch>.
   • If --force is specified, local deletion uses git branch -D <branch>.

---

Configuration (Configure Once, Use Forever)

To prevent accidental deletion of important branches (e.g., develop, release/*), add protection rules to the repository's Git config. The command reads them automatically.

# Protect develop branch
git config --add branch.cleanup.protected develop

# Protect all branches starting with release/ (wildcard)
git config --add branch.cleanup.protected 'release/*'

# View all configured protected branches
git config --get-all branch.cleanup.protected

---

Best Practices for Embedded Devs

• Prioritize --dry-run: Develop the habit of previewing before executing.
• Leverage --base: When maintaining long-term release branches, use it to clean feature or hotfix branches merged to that release.
• Careful with --force: Don't force delete unless you're 100% certain an unmerged branch is useless.
• Team Collaboration: Notify the team channel before cleaning shared remote branches.
• Regular Runs: Run monthly or quarterly to keep the repository clean.

---

Why This Version Is Better

• ✅ Safer: Default read-only preview with configurable protected branch list.
• ✅ More Flexible: Supports custom base branches, perfectly fits release / develop workflows.
• ✅ More Compatible: Avoids commands with inconsistent behavior across systems like date -d.
• ✅ More Intuitive: Condenses complex 16-step checklist into a single command with safety options.
• ✅ Consistent Style: Shares similar parameter design and documentation structure with /commit command.