/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.