gitbroom

Clean up stale local git branches — merged or upstream-gone — in one command.

Local branches pile up. You merge a PR, the remote branch gets deleted, but the local copy lingers. Multiply that by every feature you ship and git branch becomes a graveyard. gitbroom finds the dead branches and removes them — safely and with your confirmation.

What it does

Running gitbroom looks for local branches that are either:

• merged into the default branch (main / master), or
• gone — their upstream tracking branch was deleted on the remote (the [origin/x: gone] marker in git branch -vv).

It groups them, shows you the list, and asks before deleting anything. The current branch and the default branch are never deleted.

Install

# one-off
npx gitbroom

# or install globally
npm i -g gitbroom
pnpm add -g gitbroom

Requires Node.js >= 18 and git on your PATH.

Usage

gitbroom                 # find candidates, show them, confirm, delete
gitbroom --dry-run       # show what would be deleted, change nothing
gitbroom -y              # delete without the confirmation prompt
gitbroom --merged        # only branches merged into the default branch
gitbroom --gone          # only branches whose upstream is gone
gitbroom --main develop  # override default-branch detection

Tip: gone-branch detection reflects what your local repo knows. Run git fetch --prune first so deleted remote branches are actually marked gone.

Flags

| Flag | Description | | ----------------- | ----------------------------------------------------------------- | | --dry-run | List what would be deleted, then exit. Never deletes. | | -y, --yes | Delete without prompting for confirmation. | | --merged | Only consider branches merged into the default branch. | | --gone | Only consider branches whose upstream is gone. | | --main <branch> | Override default-branch detection (e.g. --main develop). | | -h, --help | Show help and exit. | | -v, --version | Show the version and exit. |

--merged and --gone are mutually exclusive.

Safety guarantees

• The current branch is never deleted.
• The default branch is never deleted.
• Merged branches are removed with git branch -d (the safe delete that refuses to drop unmerged work).
• A branch whose upstream is gone but which is not merged needs the force delete git branch -D. gitbroom flags these clearly (force delete) so you know what you're agreeing to before confirming.
• --dry-run changes nothing and is the recommended first run.

Exit codes

| Code | Meaning | | ---- | -------------------------------------------------------------- | | 0 | Success — nothing to do, a dry run, or branches were deleted. | | 2 | Not a git repository, or a git command failed. |

How it's built

The git-touching layer (runGit) is a thin wrapper over child_process. Everything that decides which branches to remove lives in pure functions (parseBranchVV, parseMerged, selectCandidates) that operate on raw git output strings. Those pure functions are what the test suite exercises — the tests never shell out to real git.

License

MIT © 2026 Abdulmunim Jemal