Files
claude-config/bin/git_repo.py
T

102 lines
5.3 KiB
Python

"""Run git, in the current directory or a given one, and read the checkout, its default branch and its files."""
import re
import subprocess
from failure import Failure
def git(*args: str, cwd: str | None = None, timeout: float | None = None) -> str | Failure:
"""What git printed, run in cwd, else in the current directory. A Failure where git cannot start, exits non-zero, prints text that is not UTF-8, or still runs after timeout seconds, which stops it."""
try:
ran = subprocess.run(["git", *args], capture_output=True, cwd=cwd, encoding="utf-8", timeout=timeout)
except UnicodeDecodeError as failure:
return Failure(f"git {' '.join(args)} printed text that is not UTF-8: {failure}")
except (OSError, ValueError) as failure:
return Failure(f"git could not start: {failure}")
except subprocess.TimeoutExpired:
return Failure(f"git {' '.join(args)}: stopped after {timeout} s")
return ran.stdout if ran.returncode == 0 else Failure(f"git {' '.join(args)}: {ran.stderr.strip()}")
def top() -> str | Failure:
found = git("rev-parse", "--show-toplevel")
return found if isinstance(found, Failure) else found.strip()
def default_branch(stale_ok: bool, timeout: float | None = None) -> tuple[str, str | None] | Failure:
"""The default branch's ref, as default_ref names it after a fetch where the checkout has an origin remote, and a note for stderr. With stale_ok, a failed fetch reads origin as last fetched, and the note says so. A call to origin still running after timeout seconds fails."""
remotes = git("remote")
if isinstance(remotes, Failure):
return remotes
fetch = git("fetch", "--quiet", "origin", timeout=timeout) if "origin" in remotes.split() else ""
if isinstance(fetch, Failure) and not stale_ok:
return fetch
ref = default_ref(timeout=timeout)
note = f"reading origin as last fetched: {fetch.reason}" if isinstance(fetch, Failure) else None
return ref if isinstance(ref, Failure) else (ref, note)
def default_ref(cwd: str | None = None, timeout: float | None = None) -> str | Failure:
"""The default branch's ref as last fetched, read in cwd, else in the current directory: `origin/<branch>` with that remote, else the local main or master. Asking origin, where the checkout records no default branch for it, fails after timeout seconds."""
remotes = git("remote", cwd=cwd)
if isinstance(remotes, Failure):
return remotes
if "origin" in remotes.split():
recorded = git("symbolic-ref", "--short", "refs/remotes/origin/HEAD", cwd=cwd)
return recorded.strip() if not isinstance(recorded, Failure) else origin_head(cwd, timeout)
for branch in ("main", "master"):
if not isinstance(git("rev-parse", "--quiet", "--verify", f"refs/heads/{branch}", cwd=cwd), Failure):
return branch
return Failure("no origin remote, and no main or master branch to take as the default branch")
def origin_head(cwd: str | None, timeout: float | None) -> str | Failure:
"""The default branch origin names, for a clone made by `git init` and `git remote add`, which records none."""
listed = git("ls-remote", "--symref", "origin", "HEAD", cwd=cwd, timeout=timeout)
if isinstance(listed, Failure):
return listed
if named := re.match(r"ref: refs/heads/(\S+)\tHEAD", listed):
return f"origin/{named.group(1)}"
return Failure("origin names no default branch; set it with `git remote set-head origin --auto`")
def default_branch_todo(root: str, timeout: float) -> str | Failure:
"""todo.md on the default branch as last fetched, read in the checkout at root; empty where that branch holds none. Asking origin, where the checkout records no default branch for it, fails after timeout seconds."""
ref = default_ref(root, timeout)
return ref if isinstance(ref, Failure) else file_at(ref, "todo.md", root)
def newest_release_tag(branch: str) -> str | None | Failure:
"""The newest `v*` tag merged into branch, None when it has none."""
# Sorts v1.0.0-rc.1 below v1.0.0.
tags = git("-c", "versionsort.suffix=-", "tag", "--list", "v*", "--merged", branch, "--sort=-v:refname")
return tags if isinstance(tags, Failure) else next(iter(tags.split()), None)
def commits_since(tag: str | None, branch: str) -> int | Failure:
"""How many commits branch holds after tag, or holds in all where tag is None."""
count = git("rev-list", "--count", f"{tag}..{branch}" if tag else branch)
return count if isinstance(count, Failure) else int(count)
def commit_exists(commit: str, cwd: str | None = None) -> bool:
return not isinstance(git("rev-parse", "--quiet", "--verify", f"{commit}^{{commit}}", cwd=cwd), Failure)
def file_at(revision: str, path: str, cwd: str | None = None) -> str | Failure:
"""A file's text at a revision, read in cwd, else in the current directory; empty where the revision is not a commit, such as a root commit's parent, or holds no such file."""
if not commit_exists(revision, cwd):
return ""
listed = git("ls-tree", "--name-only", revision, "--", path, cwd=cwd)
if isinstance(listed, Failure):
return listed
return git("show", f"{revision}:{path}", cwd=cwd) if listed.strip() else ""
def full_history() -> Failure | None:
"""Why the checkout lacks the history a tool reads, None when it holds it all."""
shallow = git("rev-parse", "--is-shallow-repository")
if isinstance(shallow, Failure):
return shallow
return Failure("a shallow clone lacks the full history; run `git fetch --unshallow origin`") if shallow.strip() == "true" else None