git-branch-cleanup-cli 0.1.0__py3-none-any.whl

git_branch_cleanup.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""git-branch-cleanup: delete stale local git branches, safely by default.
+
+Default run is a dry run: it lists what WOULD be deleted and deletes
+nothing. Pass --apply to actually delete, and only then.
+
+Safety rules (non-negotiable):
+- The current branch is never deleted.
+- A branch is only auto-deleted if its upstream is gone, or it is fully
+  merged into HEAD. Both are checked with git itself, not guessed.
+- Unmerged branches are listed as "kept" and are never deleted unless the
+  user passes BOTH --include-unmerged and --yes (which uses `git branch -D`).
+- Nothing is fetched, pushed, or sent anywhere. This tool only reads the
+  local repo and deletes local branches the user approved.
+
+Usage:
+    python3 src/git_branch_cleanup.py            # dry run, list only
+    python3 src/git_branch_cleanup.py --apply    # delete gone + merged
+    python3 src/git_branch_cleanup.py --apply --include-unmerged --yes
+
+Exit codes: 0 = ok (dry run or deletions done), 1 = usage/git error,
+2 = refused (e.g. not a git repo, or --include-unmerged without --yes).
+Python standard library only. No third-party dependencies.
+"""
+
+import argparse
+import subprocess
+import sys
+
+
+def run_git(repo, args):
+    """Run git in repo; return (returncode, stdout). Raise on git missing."""
+    result = subprocess.run(
+        ["git", "-C", repo] + args,
+        capture_output=True, text=True, check=False,
+    )
+    return result.returncode, result.stdout.strip()
+
+
+def is_git_repo(repo):
+    code, _ = run_git(repo, ["rev-parse", "--git-dir"])
+    return code == 0
+
+
+def current_branch(repo):
+    code, out = run_git(repo, ["branch", "--show-current"])
+    if code != 0:
+        raise RuntimeError("could not determine the current branch")
+    return out
+
+
+def local_branches(repo):
+    """All local branch names, in git's order."""
+    code, out = run_git(repo, ["branch", "--format=%(refname:short)"])
+    if code != 0:
+        raise RuntimeError("could not list local branches")
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def merged_branches(repo):
+    """Branches fully merged into HEAD."""
+    code, out = run_git(repo, ["branch", "--merged", "HEAD",
+                               "--format=%(refname:short)"])
+    if code != 0:
+        raise RuntimeError("could not list merged branches")
+    return set(line.strip() for line in out.splitlines() if line.strip())
+
+
+def gone_branches(repo):
+    """Branches whose upstream is gone.
+
+    Parses `git branch -vv`, where a gone upstream shows as ': gone]'.
+    Note: run `git fetch --prune` first if you want this list to reflect
+    the remote's current state; this tool deliberately does not fetch.
+    """
+    code, out = run_git(repo, ["branch", "-vv"])
+    if code != 0:
+        raise RuntimeError("could not list branches with upstream info")
+    gone = set()
+    for line in out.splitlines():
+        if ": gone]" in line:
+            # Line form: "* name  abc1234 [origin/name: gone] message"
+            # or: "  name  abc1234 [origin/name: gone] message"
+            parts = line.replace("*", " ").split()
+            if parts:
+                gone.add(parts[0])
+    return gone
+
+
+def classify(branches, current, merged, gone):
+    """Sort branches into (delete, keep) with a reason for each kept one.
+
+    A branch is deletable only if it is not current AND (gone or merged).
+    Everything else is kept, with the reason stated plainly.
+    """
+    delete = []
+    keep = {}
+    for branch in branches:
+        if branch == current:
+            keep[branch] = "current branch"
+        elif branch in gone:
+            delete.append(branch)
+        elif branch in merged:
+            delete.append(branch)
+        else:
+            keep[branch] = "not merged and upstream still exists"
+    return delete, keep
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="List (default) or delete stale local git branches.")
+    parser.add_argument("--repo", default=".",
+                        help="path to the git repo (default: current dir)")
+    parser.add_argument("--apply", action="store_true",
+                        help="actually delete; without this, dry run only")
+    parser.add_argument("--include-unmerged", action="store_true",
+                        help="also delete unmerged branches (needs --yes)")
+    parser.add_argument("--yes", action="store_true",
+                        help="confirm unmerged deletion (needs --include-unmerged)")
+    args = parser.parse_args(argv)
+
+    if args.include_unmerged and not args.yes:
+        print("Refused: --include-unmerged requires --yes. "
+              "Unmerged branches are never deleted on a single flag.",
+              file=sys.stderr)
+        return 2
+    if not is_git_repo(args.repo):
+        print(f"Refused: {args.repo} is not a git repository.",
+              file=sys.stderr)
+        return 2
+
+    try:
+        current = current_branch(args.repo)
+        branches = local_branches(args.repo)
+        merged = merged_branches(args.repo)
+        gone = gone_branches(args.repo)
+    except RuntimeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    delete, keep = classify(branches, current, merged, gone)
+    unmerged = [b for b in keep if keep[b].startswith("not merged")]
+    if args.include_unmerged and args.yes:
+        delete = delete + unmerged
+        keep = {b: r for b, r in keep.items() if b not in unmerged}
+
+    print(f"Current branch: {current}")
+    print(f"Local branches: {len(branches)}")
+    if delete:
+        print("Would delete:" if not args.apply else "Deleting:")
+        for branch in delete:
+            reason = "upstream gone" if branch in gone else "merged"
+            print(f"  - {branch} ({reason})")
+    else:
+        print("Nothing to delete.")
+    if keep:
+        print("Kept:")
+        for branch, reason in keep.items():
+            print(f"  - {branch} ({reason})")
+
+    if not args.apply:
+        print("Dry run: nothing deleted. Re-run with --apply to delete.")
+        return 0
+
+    force = args.include_unmerged and args.yes
+    # Forced (-D) only for the explicitly confirmed unmerged set.
+    failures = []
+    for branch in delete:
+        is_unmerged = branch in unmerged
+        code, out = run_git(args.repo,
+                            ["branch", "-D" if is_unmerged else "-d", branch])
+        if code != 0:
+            failures.append((branch, out))
+    if failures:
+        for branch, out in failures:
+            print(f"Failed to delete {branch}: {out}", file=sys.stderr)
+        return 1
+    print(f"Deleted {len(delete)} branch(es).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

git_branch_cleanup_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: git-branch-cleanup-cli
+Version: 0.1.0
+Summary: Delete stale local git branches — gone on the remote, or fully merged — with a dry run first, always.
+Author: Haider Ali
+License: MIT
+Project-URL: Homepage, https://github.com/haiderstudio/git-branch-cleanup-cli
+Project-URL: Repository, https://github.com/haiderstudio/git-branch-cleanup-cli
+Project-URL: Issues, https://github.com/haiderstudio/git-branch-cleanup-cli/issues
+Keywords: git,branches,cleanup,cli,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# git-branch-cleanup-cli
+
+Delete stale local git branches — gone on the remote, or fully merged — with a dry run first, always.
+
+[![CI](https://github.com/haiderstudio/git-branch-cleanup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/haiderstudio/git-branch-cleanup-cli/actions/workflows/ci.yml) [![Licence: MIT](https://img.shields.io/badge/Licence-MIT-yellow.svg)](LICENSE)
+
+## 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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+python3 src/git_branch_cleanup.py --apply
+```
+
+Work on a different repo without changing directory:
+
+```sh
+python3 src/git_branch_cleanup.py --repo /path/to/your/repo --apply
+```
+
+Delete unmerged branches too — only with both flags, deliberately:
+
+```sh
+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
+
+```sh
+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.

git_branch_cleanup_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+git_branch_cleanup.py,sha256=O7Q5x4jMT3cQKUoan8Hw8H62ZKp1_UK0Px1vYiwKv_E,6686
+git_branch_cleanup_cli-0.1.0.dist-info/licenses/LICENSE,sha256=mTjYlQM7htiV7thgBkBwT0woURqRpTJG1eWK1Logfl8,1067
+git_branch_cleanup_cli-0.1.0.dist-info/METADATA,sha256=UnBG1Dr9rMPhGzv-mfky1Owh7OJhEnmA65xerK0ZXMQ,4432
+git_branch_cleanup_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+git_branch_cleanup_cli-0.1.0.dist-info/entry_points.txt,sha256=Q1GdBnFub4YDpC3hWdPScc1XRB3bkDr2ZAKbp9hnq14,63
+git_branch_cleanup_cli-0.1.0.dist-info/top_level.txt,sha256=FnNmgY-NHrRSw6A0M1VwV0EtpymyISzjHrKXAp_Irfc,19
+git_branch_cleanup_cli-0.1.0.dist-info/RECORD,,

git_branch_cleanup_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_branch_cleanup_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-branch-cleanup = git_branch_cleanup:main

git_branch_cleanup_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haider Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_branch_cleanup_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+git_branch_cleanup