git-reclaim 0.1.0__py3-none-any.whl

git_reclaim/__init__.py

@@ -0,0 +1,3 @@
+"""Reclaim disk space across a tree of git repositories."""
+
+__version__ = "0.1.0"

git_reclaim/cli.py

@@ -0,0 +1,353 @@
+"""Command-line entry point for git-reclaim.
+
+The tool is installed as ``git-reclaim``, so git runs it as ``git reclaim``.
+It has three independent jobs:
+
+* report and optionally purge regenerable cache directories
+* compact every repository's ``.git`` with ``git gc``
+* list clones that are safe to delete because the remote has everything
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from git_reclaim import __version__
+
+# Directory names that are regenerable and never source. dist/ and build/ are
+# deliberately excluded because they are occasionally committed.
+CACHE_NAMES = frozenset(
+    {
+        "node_modules",
+        ".venv",
+        "venv",
+        "__pycache__",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".mypy_cache",
+        ".next",
+        "target",
+    }
+)
+
+# Directories not worth descending into while looking for repos. A directory
+# that is itself a repo is detected before this list is applied.
+PRUNE_NAMES = CACHE_NAMES | {".tox", "vendor"}
+
+GIT_TIMEOUT = 60
+GC_TIMEOUT = 600
+
+
+@dataclass(frozen=True)
+class Style:
+    """ANSI colours, disabled when output is not a terminal."""
+
+    red: str = ""
+    green: str = ""
+    yellow: str = ""
+    grey: str = ""
+    bold: str = ""
+    reset: str = ""
+
+    @classmethod
+    def auto(cls) -> Style:
+        if not sys.stdout.isatty() or os.environ.get("NO_COLOR"):
+            return cls()
+        return cls(
+            red="\033[31m",
+            green="\033[32m",
+            yellow="\033[33m",
+            grey="\033[90m",
+            bold="\033[1m",
+            reset="\033[0m",
+        )
+
+
+def human(kb: int) -> str:
+    """Format a size in KiB the way the old shell version did."""
+    if kb >= 1024 * 1024:
+        return f"{kb / 1024 / 1024:.1f}G"
+    if kb >= 1024:
+        return f"{kb // 1024}M"
+    return f"{kb}K"
+
+
+def du_kb(path: Path) -> int:
+    """Return disk usage for a path in KiB, without following symlinks."""
+    total = 0
+    for root, dirs, files in os.walk(path, followlinks=False):
+        for name in [*dirs, *files]:
+            entry = Path(root) / name
+            if entry.is_symlink():
+                continue
+            try:
+                stat = entry.lstat()
+            except OSError:
+                continue
+            blocks = getattr(stat, "st_blocks", 0)
+            total += blocks * 512 if blocks else stat.st_size
+    return total // 1024
+
+
+def find_cache_dirs(root: Path) -> list[Path]:
+    """Find cache directories under root, without descending into them."""
+    found: list[Path] = []
+    for dirpath, dirnames, _ in os.walk(root, topdown=True, followlinks=False):
+        current = Path(dirpath)
+        keep: list[str] = []
+        for name in dirnames:
+            entry = current / name
+            if name == ".git" or entry.is_symlink():
+                continue
+            if name in CACHE_NAMES:
+                found.append(entry)
+                continue
+            keep.append(name)
+        dirnames[:] = keep
+    return found
+
+
+def find_repos(root: Path) -> list[Path]:
+    """Find git repositories under root, stopping at each repo boundary."""
+    repos: list[Path] = []
+    for dirpath, dirnames, _ in os.walk(root, topdown=True, followlinks=False):
+        current = Path(dirpath)
+        if (current / ".git").exists():
+            repos.append(current)
+            dirnames[:] = []
+            continue
+
+        keep: list[str] = []
+        for name in dirnames:
+            entry = current / name
+            if name in PRUNE_NAMES or entry.is_symlink():
+                continue
+            keep.append(name)
+        dirnames[:] = keep
+    return repos
+
+
+def git(
+    repo: Path, *args: str, timeout: int = GIT_TIMEOUT
+) -> subprocess.CompletedProcess[str]:
+    """Run git in a repository, capturing output."""
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+
+
+def git_tracks_files(path: Path) -> bool:
+    """True when git tracks at least one file inside path."""
+    result = git(path, "ls-files")
+    return result.returncode == 0 and bool(result.stdout.strip())
+
+
+def report_caches(root: Path, style: Style, purge: bool) -> None:
+    """Report caches and optionally delete them."""
+    caches = find_cache_dirs(root)
+    sizes = sorted(((du_kb(path), path) for path in caches), reverse=True)
+
+    print(f"{style.bold}Regenerable caches under {root}{style.reset}")
+    if not sizes:
+        print(f"  {style.grey}none found{style.reset}")
+        return
+
+    for kb, path in sizes[:12]:
+        print(f"  {human(kb):<8} {style.grey}{path.relative_to(root)}{style.reset}")
+    if len(sizes) > 12:
+        print(f"  {style.grey}... and {len(sizes) - 12} more{style.reset}")
+
+    total = sum(kb for kb, _ in sizes)
+    print(
+        f"  {style.bold}{len(sizes)} cache dirs, {human(total)} reclaimable{style.reset}"
+    )
+
+    if not purge:
+        print(f"  {style.yellow}(dry run, pass -p to delete these){style.reset}")
+        return
+
+    before = shutil.disk_usage(root).free // 1024
+    purged = skipped = failed = 0
+    for _, path in sizes:
+        if git_tracks_files(path):
+            print(
+                f"  {style.yellow}skipped {path.relative_to(root)} "
+                f"(git tracks files inside it){style.reset}"
+            )
+            skipped += 1
+            continue
+        try:
+            shutil.rmtree(path)
+        except OSError:
+            failed += 1
+        else:
+            purged += 1
+
+    after = shutil.disk_usage(root).free // 1024
+    freed = max(0, after - before)
+    print(
+        f"  {style.green}-> purged {purged} of {len(sizes)} dirs, "
+        f"freed {human(freed)} (free: {human(before)} -> {human(after)}){style.reset}"
+    )
+    if failed:
+        print(f"  {style.red}-> {failed} dir(s) could not be removed{style.reset}")
+
+
+def report_gc(root: Path, style: Style) -> None:
+    """Run git gc, and git lfs prune when available, in every repo."""
+    print()
+    print(f"{style.bold}Compacting repo history (git gc){style.reset}")
+
+    have_lfs = shutil.which("git-lfs") is not None
+    count = before = after = 0
+
+    for repo in find_repos(root):
+        rev = git(repo, "rev-parse", "--absolute-git-dir")
+        if rev.returncode != 0:
+            continue
+        gitdir = Path(rev.stdout.strip())
+        size_before = du_kb(gitdir)
+        git(repo, "gc", "--quiet", timeout=GC_TIMEOUT)
+        if have_lfs:
+            git(repo, "lfs", "prune", timeout=GC_TIMEOUT)
+        size_after = du_kb(gitdir)
+
+        count += 1
+        before += size_before
+        after += size_after
+        if size_before > size_after:
+            print(
+                f"  -{human(size_before - size_after):<7} "
+                f"{style.grey}{repo.relative_to(root)}{style.reset}"
+            )
+
+    saved = max(0, before - after)
+    print(
+        f"  {style.bold}gc'd {count} repo(s): .git {human(before)} -> "
+        f"{human(after)} (saved {human(saved)}){style.reset}"
+    )
+
+
+def report_safe_repos(root: Path, style: Style) -> None:
+    """List clones where the remote already has everything."""
+    print()
+    print(
+        f"{style.bold}Repos safe to delete (remote has everything), "
+        f"biggest first{style.reset}"
+    )
+
+    rows: list[tuple[int, str, Path, str]] = []
+    keep = 0
+
+    for repo in find_repos(root):
+        remotes = git(repo, "remote").stdout.strip()
+        dirty = git(repo, "status", "--porcelain").stdout.strip()
+        unpushed = git(
+            repo, "log", "--branches", "--not", "--remotes", "--oneline"
+        ).stdout.strip()
+        stash = git(repo, "stash", "list").stdout.strip()
+        tags = git(repo, "tag").stdout.strip()
+
+        if not remotes or dirty or unpushed or stash or tags:
+            keep += 1
+            continue
+
+        size = du_kb(repo)
+        last = git(repo, "log", "-1", "--format=%cs").stdout.strip()
+        url_result = git(repo, "remote", "get-url", "origin")
+        url = url_result.stdout.strip() if url_result.returncode == 0 else "?"
+        rows.append((size, last, repo, url))
+
+    rows.sort(key=lambda row: row[0], reverse=True)
+    for size, last, repo, url in rows:
+        print(
+            f"  {human(size):<8} last:{last:<10} "
+            f"{str(repo.relative_to(root)):<44} {style.grey}{url}{style.reset}"
+        )
+
+    total = sum(size for size, _, _, _ in rows)
+    print(
+        f"{style.bold}{len(rows)} safe ({human(total)}) / {keep} keep{style.reset}  "
+        f"{style.grey}(keep = dirty, unpushed, stashed, tagged, or no remote)"
+        f"{style.reset}"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="git reclaim",
+        description="Reclaim disk space across a tree of git repositories.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "(default)  dry run: report reclaimable cache space; deletes nothing\n"
+            "-p         purge the cache directories (git-tracked dirs are skipped)\n"
+            "-g         run git gc (and git lfs prune) in every repo\n"
+            "-r         list repos that are safe to delete (size, last commit, URL)\n"
+            "-d DIR     directory to scan (default: current directory)"
+        ),
+    )
+    parser.add_argument(
+        "-p",
+        "--purge",
+        action="store_true",
+        help="delete the cache directories",
+    )
+    parser.add_argument(
+        "-g",
+        "--gc",
+        action="store_true",
+        help="compact every repository with git gc",
+    )
+    parser.add_argument(
+        "-r",
+        "--repos",
+        action="store_true",
+        help="list repositories that are safe to delete",
+    )
+    parser.add_argument(
+        "-d",
+        "--dir",
+        default=".",
+        metavar="DIR",
+        help="directory to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    root = Path(args.dir).expanduser()
+
+    if not root.is_dir():
+        print(f"Cannot cd into {root}", file=sys.stderr)
+        return 1
+
+    root = root.resolve()
+    style = Style.auto()
+
+    report_caches(root, style, args.purge)
+    if args.gc:
+        report_gc(root, style)
+    if args.repos:
+        report_safe_repos(root, style)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

git_reclaim-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: git-reclaim
+Version: 0.1.0
+Summary: Reclaim disk space across a tree of git repositories
+Project-URL: Homepage, https://github.com/michael-borck/git-reclaim
+Project-URL: Repository, https://github.com/michael-borck/git-reclaim
+Project-URL: Issues, https://github.com/michael-borck/git-reclaim/issues
+Author-email: Michael Borck <michael@borck.dev>
+License: MIT
+License-File: LICENSE
+Keywords: cleanup,cli,disk-space,git,repository-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# git-reclaim
+
+A small, dependency-free **disk-reclaim** helper for people who keep many git
+clones side by side. It finds space you can safely get back across a whole tree
+of repos, and flags clones that are safe to delete because the remote already
+has everything.
+
+`git-reclaim` is a [git custom subcommand](https://git-scm.com/book/en/v2/Git-Internals-Git-Internals):
+an executable named `git-reclaim` on your `PATH` is runnable as `git reclaim`.
+
+> **Scope:** `git-reclaim` does one thing: reclaim disk space across local
+> clones. For multi-repo **status and sync** (branch, ahead/behind, batch
+> `git` commands), use [gita](https://github.com/nosarthur/gita). For anything
+> needing the **GitHub API** (bulk listing, health checks, topics, portfolio
+> sites), use [gh-toolkit](https://github.com/michael-borck/gh-toolkit) or
+> [`gh`](https://cli.github.com/). If you want one verb set across all of them,
+> use [gx](https://github.com/michael-borck/gx).
+
+## Install
+
+```bash
+uv tool install git-reclaim
+# or
+pipx install git-reclaim
+# or
+pip install git-reclaim
+```
+
+No dependencies beyond Python 3.10+ and `git`.
+
+## `git reclaim`
+
+```
+git reclaim [-p] [-g] [-r] [-d DIR]
+
+  (default)  dry run: report reclaimable cache space; deletes nothing
+  -p         purge the cache directories (any dir git tracks files inside is
+             skipped, never deleted)
+  -g         compact history: run `git gc` (and `git lfs prune` if installed)
+             in every repo and report the .git space reclaimed
+  -r         also list repos that are safe to delete (size + last commit + URL)
+  -d DIR     directory to scan (default: current directory)
+```
+
+Three ways to free space across a tree of clones:
+
+- **Purge regenerable caches.** It finds `node_modules`, `.venv`/`venv`,
+  `__pycache__`, `.pytest_cache`, `.ruff_cache`, `.mypy_cache`, `.next`, and
+  `target`. These rebuild on demand. So `git reclaim -p` recovers space without
+  touching your source, history, or uncommitted work. If a directory with one
+  of these names turns out to be git-tracked (a committed `target/`, say), the
+  purge detects that and skips it. `dist/` and `build/` are deliberately
+  excluded because they are occasionally committed. Re-run `npm install` or
+  `uv sync` next time you open a project.
+
+- **Compact `.git` itself.** `git reclaim -g` runs `git gc` (plus
+  `git lfs prune` when git-lfs is installed) in every repo and reports the
+  space recovered per repo. This is standard git maintenance: nothing reachable
+  is deleted, and lfs prune always retains unpushed objects.
+
+- **Find repos that are safe to delete.** `git reclaim -r` lists repos where
+  the remote already has everything: clean working tree, has a remote, no
+  unpushed commits on any local branch, no stashes, and no tags. Rows are sorted
+  by size, with each repo's last-commit date and re-clone URL. Anything not
+  fully synced is counted as "keep" and never listed as safe. Tags are treated
+  conservatively because a local tag ref can be lost even when its commit is on
+  the remote.
+
+### How discovery works
+
+It walks the tree but **prunes at repo boundaries**. The moment a directory
+contains a `.git` entry it is recorded as a repo and not descended into. So
+workspace folders are descended into to find their child repos, while a repo's
+own working tree (and its `node_modules`, `vendor`, submodules, etc.) is not
+re-scanned. `.git` is detected as a **file or directory**, so submodule and
+worktree clones are recognised too.
+
+### Examples
+
+```bash
+git reclaim              # what could I free from caches? (dry run)
+git reclaim -p           # actually purge the caches
+git reclaim -g           # repack every repo's .git (git gc)
+git reclaim -r           # caches report + list of repos safe to delete
+git reclaim -r -d ~/work # scan a different tree
+```
+
+> `git reclaim` only ever deletes **caches**, and only with `-p`; `-g` just
+> repacks history in place. It never deletes a repo. It just reports which are
+> safe, so you stay in control of removing whole clones. Pair it with the
+> re-clone URLs it prints.
+
+## Using it from `gita`
+
+If you manage your clones with `gita`, you can make `git-reclaim` feel native.
+gita loads a user command file from `~/.config/gita/cmds.json` and lets custom
+commands shadow the defaults. Add:
+
+```json
+{
+  "reclaim": {
+    "cmd": "git-reclaim -d .",
+    "disable_async": true,
+    "help": "reclaim caches / flag safe-to-delete clones"
+  }
+}
+```
+
+Now `gita reclaim` (or `gita reclaim <group>`) runs `git-reclaim` in each
+registered repo. No-config alternative:
+
+```bash
+gita shell 'git-reclaim -d .'
+```
+
+Note this runs it **per repo**, which suits the cache purge (`-p`) and
+`git gc` (`-g`) modes. For the cross-tree "what's safe to delete, biggest
+first" view (`-r`), run `git-reclaim` standalone against the parent folder
+(`git reclaim -r -d ~/projects`) so you get the single aggregate, size-sorted
+report.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check src tests
+uv run ruff format --check src tests
+```
+
+CI runs the same checks on every push and pull request.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

git_reclaim-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+git_reclaim/__init__.py,sha256=1qFGzD8CMX6-z99zZbqjVZmzC5RdsybxS-HE7iElAN8,83
+git_reclaim/cli.py,sha256=0iT6BBE2mzEchPAudt6Hex1ONmMWEtDiMS00QQsJpaU,10680
+git_reclaim-0.1.0.dist-info/METADATA,sha256=qVCymBLngjlLuz_PnBXDdNVuYfmDjFEZyUDJ74psv6U,6328
+git_reclaim-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+git_reclaim-0.1.0.dist-info/entry_points.txt,sha256=wKeZHp8QvfLR8zbSRUCeUfqcOrCfWN-qb37TfwFCiXc,53
+git_reclaim-0.1.0.dist-info/licenses/LICENSE,sha256=tP28nznO05HKBQN8uZ9NSvmcpzCWMj4P8e6F7IDj24Q,1070
+git_reclaim-0.1.0.dist-info/RECORD,,

git_reclaim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

git_reclaim-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-reclaim = git_reclaim.cli:main

git_reclaim-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Borck
+
+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.