Skip to main content

git-branch-cleanup-cli

Delete stale local git branches — gone on the remote, or fully merged — with a dry run first, always.

CI Licence: MIT

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] in git branch -vv).
  • Fully merged into HEAD — git branch --merged HEAD says 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-unmerged and --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 --prune first 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)

Source distribution for git-branch-cleanup-cli 0.1.0
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)

Table of built distributions (wheels) for git-branch-cleanup-cli 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page