MrGitClean

A small shell utility I keep reaching for: cleans up merged Git branches across local and remote, with dry-run safety baked in.

I work across enough repos that the merged-but-not-deleted branch list gets long fast. Some days I’d open a project and find 30 branches I’d already shipped weeks ago, still hanging around. MrGitClean is the script I wrote to handle it once, then dropped into my path so I can run it everywhere. 🧼

What is MrGitClean?

MrGitClean is a shell utility for managing merged Git branches. On a team with weekly merges, the branch list at any repo grows fast, and Git operations get slower as it does. The tool does what you’d expect: finds branches that are already merged into your default branch and offers to delete them. The pieces I cared about getting right:

• 🧹 Identifies merged branches into the main branch.
• ⚙️ Offers interactive and batch cleanup modes to suit your workflow.
• 🌐 Removes both local and remote branches for complete repository hygiene.
• 🕒 Displays details about each branch, such as the last commit date and merge hash.
• 🔍 Includes advanced filters, dry-run simulations, and logging for precision and control.

The four things that mattered most to me when building it:

Features and Benefits

1. Safe and User-Friendly

The default mode prompts before each delete and prints the relevant context (last commit date, merge hash) so you can decide on a per-branch basis. Hitting Enter on each prompt is fine, but you can also skip a single branch without abandoning the whole run.

➜ mrgitclean
Default branch is: main
Found 4 merged branches eligible for cleanup.

-----------------------------------------
Branch: feature/add-new-auth-system
Last commit: 2024-12-09 16:32:23 -0500 (6 day(s) ago)
Merge commit: 18930fa73094e1222cc89960f1ea3c89547173e5
Delete this branch? [y/N] n
Skipped 'feature/add-new-auth-system'

2. Batch Mode for Efficiency

Confirming each branch is fine for a handful, but on a repo with 40+ stale branches it gets old fast. Batch mode skips the prompts and uses globs/exclusions to keep specific branches safe (release branches in particular):

$ ./mrgitclean --batch --remote --exclude="release/*"
Deleted branches:
  - feature/add-auth
  - bugfix/fix-typo

Batch mode is what I run most often on my own projects.

3. Dry-Run Mode for Peace of Mind

Anything destructive should let you preview first. --dry-run prints exactly what would be deleted without actually touching anything:

➜ mrgitclean --dry-run
Default branch is: main
Found 2 merged branches eligible for cleanup.

-----------------------------------------
Branch: feature/add-new-auth-system
Last commit: 2024-12-09 16:32:23 -0500 (6 day(s) ago)
Merge commit: 18930fa73094e1222cc89960f1ea3c89547173e5
[DRY-RUN] Would delete: feature/add-new-auth-system

I run dry-run by default whenever a new repo asks for cleanup, just to scan for anything that looks wrong before I commit.

4. Remote Branch Cleanup

Local cleanup alone leaves the remote a mess. --remote deletes the matching upstream branches, with a warning about the impact on collaborators since this affects everyone with the repo cloned:

➜ mrgitclean --dry-run --batch --remote
Default branch is: main
Found 2 merged branches eligible for cleanup.

-----------------------------------------
Warning: Deleting remote branches affects all users.
Branch: feature/add-new-auth-system
Last commit: 2024-12-09 16:32:23 -0500 (6 day(s) ago)
Merge commit: 18930fa73094e1222cc89960f1ea3c89547173e5
[DRY-RUN] Would delete: feature/add-new-auth-system
[DRY-RUN] Would delete remote branch 'feature/add-new-auth-system'

Why a Shell Script?

Why a shell script and not a Node CLI or a Go binary? Two reasons. First, Bash and Zsh are already on every Unix machine I touch, so a shell script with no dependencies is the lightest possible install. Second, it’s something I can read end-to-end in one sitting, which matters when the script is deleting things from your Git repo. Easy to audit, easy to fork.

The medium-term goal is a Homebrew formula so the install becomes brew install mrgitclean.

What’s Next for MrGitClean?

A few things on the list that I’d like to add when I get back to it:

• 🔧 Advanced Filtering: Adding regex-based branch selection for more precise control.
• 📊 Enhanced Logs: Providing detailed reports in JSON and CSV formats.
• 🤖 CI/CD Integration: Automating branch cleanup in pipeline environments.
• 💻 Windows Compatibility: Expanding support to Windows users.
• 🧑‍🏫 Interactive Tutorials: Creating guides to help users get the most out of the tool.
• 🍺 Homebrew Support: Packaging MrGitClean for easy installation via Homebrew.

Suggestions or pull requests welcome on GitHub.

Try it

Source and install instructions are on GitHub. If you give it a run on your own repos and find anything weird, drop an issue.