Metadata-Version: 2.4
Name: branchreap
Version: 0.1.0
Summary: Safely reap merged & gone-upstream git branches — clean up your local branch clutter in one pass. Zero dependencies, no install.
Author: yyfjj
License: MIT
Project-URL: Homepage, https://github.com/jjdoor/branchreap-py
Project-URL: Repository, https://github.com/jjdoor/branchreap-py
Project-URL: Issues, https://github.com/jjdoor/branchreap-py/issues
Keywords: git,branch,cleanup,merged,stale-branches,prune,delete-branches,cli,devtools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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**.

```bash
# 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

```bash
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

```bash
--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

```text
$ 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
