branchreap 0.1.0

Safely reap merged & gone-upstream git branches — clean up your local branch clutter in one pass. Zero dependencies, no install.

branchreap

Safely reap merged & gone-upstream git branches. After a few months, git branch becomes a graveyard: dozens of feature/* that shipped long ago, and tracking branches whose remote was deleted the moment the PR merged. branchreap finds the ones that are actually safe to delete — and only those. Zero dependencies, pure standard library.

# Run without installing:
pipx run branchreap              # scan (read-only)

# Or install it:
pip install branchreap
branchreap clean                 # reap, with a confirmation prompt

What it reaps

• Merged branches — local branches fully merged into your default branch.
• Gone branches — tracking branches whose upstream was deleted ([gone]), as long as they carry no unmerged work.

What it will never touch

• the current branch
• the default branch (main / master / whatever origin/HEAD points at)
• unmerged or unpushed work, or any branch with commits of its own — unless you explicitly pass --include-unmerged (and even then, never the current or default branch)

That safety floor is the whole point: run it without reading the docs and the worst case is it deletes a branch git itself considers fully merged.

Why not git branch --merged | xargs git branch -d?

Because that one-liner misses gone-upstream branches, happily lists main, and does nothing about the "is this actually safe?" question. branchreap does merged and gone in one pass, protects the branches you'd regret losing, and runs instantly with pipx (or npx — there's a byte-for-byte twin on npm), no toolchain to install.

Usage

branchreap                      # scan (read-only, default)
branchreap scan --json          # machine-readable
branchreap clean --dry-run      # preview exactly what would be deleted
branchreap clean                # delete, with a confirmation prompt
branchreap clean --yes          # delete, no prompt (scripts / aliases)

Options

--main <branch>       Override the detected default branch
--fetch               Run 'git fetch --prune' first, so 'gone' status is fresh
--include-unmerged    Also reap gone branches with unmerged commits (uses -D)
--json                Machine-readable scan output
-y, --yes             Skip the confirmation prompt
--dry-run             Show what would be deleted, delete nothing

Example

$ branchreap

default branch: main

  ✗ feature/old-login          merged         merged into main
  ✗ fix/typo                    gone           upstream gone · merged into main
  ────────────────────────────────────────────────────────
  2 reapable  (1 merged · 1 gone)  ·  4 kept

  1 gone branch(es) held back (unmerged commits). Use --include-unmerged to reap.

Exit codes

Code	Meaning
0	ok
2	error (not a git repo, bad args, or a deletion failed)

License

MIT