git-branch-cleanup-cli
Delete stale local git branches — gone on the remote, or fully merged — with a dry run first, always.
What it does
Over a project's life, local branches pile up: feature branches merged weeks ago, branches whose remote branch was deleted, experiment branches never finished. git-branch-cleanup lists them and, only when you say --apply, deletes the safe ones:
- Upstream gone — the remote branch no longer exists (shows as
: gone]ingit branch -vv). - Fully merged into HEAD —
git branch --merged HEADsays the work is already in your current branch.
What it does NOT do
- It never deletes the current branch.
- It never deletes an unmerged branch unless you pass both
--include-unmergedand--yes— a single flag is refused on purpose. - It never fetches, pushes, or talks to a remote. If you want the "gone" list to reflect the remote's current state, run
git fetch --prunefirst yourself. - It never deletes remote branches, tags, or stashes.
- It sends nothing anywhere. Everything runs locally, Python standard library only.
Install
No install step and no dependencies — Python 3.8+ and git are enough:
git clone https://github.com/haiderstudio/git-branch-cleanup-cli.git
cd git-branch-cleanup-cli
python3 src/git_branch_cleanup.py --help
Usage
Dry run first — this is the default, and it deletes nothing:
python3 src/git_branch_cleanup.py
Real output on a sample repo (see examples/):
Current branch: main
Local branches: 3
Would delete:
- done (merged)
Kept:
- main (current branch)
- wip (not merged and upstream still exists)
Dry run: nothing deleted. Re-run with --apply to delete.
Delete the safe branches:
python3 src/git_branch_cleanup.py --apply
Work on a different repo without changing directory:
python3 src/git_branch_cleanup.py --repo /path/to/your/repo --apply
Delete unmerged branches too — only with both flags, deliberately:
python3 src/git_branch_cleanup.py --apply --include-unmerged --yes
--include-unmerged alone is refused (exit code 2) and deletes nothing.
Example
See examples/ for a runnable walkthrough: it creates a throwaway repo with a merged branch and an unmerged branch, runs the dry run, then --apply, and shows that only the merged branch disappears. The same scenario is covered by the integration test, so the example and the tests cannot drift apart.
How it is tested
python3 tests/test_git_branch_cleanup.py
Expected output: All 5 tests passed. The suite covers the classification rules (current branch never deleted, gone branches deletable, unmerged kept), the : gone] parsing, a real-repo dry-run-then-apply run, and refusal outside a git repo. Tests run on the exact files in this repo, with no network and no third-party packages.
Contributing
Small, focused improvements are welcome. Open an issue first for anything larger than a typo, keep the safety rules above intact, and run the test suite before opening a pull request. See CONTRIBUTING.md.
Licence
MIT — see LICENSE. Original work, written for this repo; it builds on git's own --merged and -vv output, not on any other cleanup tool's code.
Metadata
Release files for git-branch-cleanup-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| git_branch_cleanup_cli-0.1.0.tar.gz | 7.0 kB | Without provenance | Details for git_branch_cleanup_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| git_branch_cleanup_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for git_branch_cleanup_cli-0.1.0-py3-none-any.whl |
Total release size: 13.4 kB
Release files / git_branch_cleanup_cli-0.1.0.tar.gz
| Download URL | git_branch_cleanup_cli-0.1.0.tar.gz |
|---|---|
| Size | 7.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
95c8cd533275e6a697aabff97273a279726cc721f491933246018cc126711ed9
|
|
BLAKE2b-256 checksum How to use checksums |
810ce419a9d8ad6bf6b0621469ed6eec82aaf9188af2850659b516a241324e9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / git_branch_cleanup_cli-0.1.0-py3-none-any.whl
| Download URL | git_branch_cleanup_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c046715561d6d596c84c37b9ec67d935988a899f684c2b6108660df08647e1ba
|
|
BLAKE2b-256 checksum How to use checksums |
a0d5e6a521f347e66b652b7dd3566cde7567dadec08d2971aaf910d54e5913dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for git-branch-cleanup-cli 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.