compforge-repokit 0.15.0__py3-none-any.whl

repokit/git.py

@@ -0,0 +1,296 @@
+"""Git operations with explicit arguments, bounded execution and observable failures."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .git_index import IndexView
+
+
+@dataclass(frozen=True)
+class GitResult:
+    rc: int
+    out: str
+    err: str
+    uncertain: bool = False
+
+    @property
+    def ok(self) -> bool:
+        return self.rc == 0
+
+
+def git(
+    repo_dir: str | Path,
+    *args: str,
+    timeout: float = 5,
+    raw: bool = False,
+    index_file: Path | None = None,
+) -> GitResult:
+    env = {**os.environ, "GIT_INDEX_FILE": str(index_file.absolute())} if index_file else None
+    return _run(["git", "-C", str(repo_dir), *args], timeout, raw=raw, env=env)
+
+
+def git_global(*args: str, timeout: float = 5) -> GitResult:
+    return _run(["git", *args], timeout)
+
+
+def _run(
+    argv: list[str], timeout: float, *, raw: bool = False, env: dict[str, str] | None = None
+) -> GitResult:
+    from ._process import run_command
+    from .budget import current_budget
+
+    budget = current_budget(timeout)
+    # Expiry before launch is a known non-action; transport interruption after
+    # launch cannot prove that a write was rolled back.
+    try:
+        budget.remaining()
+    except (TimeoutError, InterruptedError) as exc:
+        return GitResult(-1, "", str(exc))
+    try:
+        result = run_command(argv, budget, env=env)
+        out = os.fsdecode(result.stdout)
+        return GitResult(
+            0, out if raw or "\0" in out else out.strip(), os.fsdecode(result.stderr).strip()
+        )
+    except subprocess.CalledProcessError as exc:
+        out = os.fsdecode(exc.output or b"")
+        return GitResult(
+            exc.returncode,
+            out if raw or "\0" in out else out.strip(),
+            os.fsdecode(exc.stderr or b"").strip(),
+        )
+    except (TimeoutError, InterruptedError, ValueError) as exc:
+        return GitResult(-1, "", str(exc), uncertain=True)
+    except OSError as exc:
+        return GitResult(-1, "", str(exc))
+
+
+def stage(
+    repo: str | Path,
+    paths: list[str],
+    *,
+    validate: Callable[[IndexView], None] | None = None,
+) -> GitResult:
+    """Stage literal paths, retaining unrelated entries.
+
+    With validate, prepare an isolated index and pass its IndexView (entries and
+    changes against HEAD) to the callback. A raised exception propagates and leaves
+    the original index untouched, as does a failed add. Empty paths validate the
+    current index.
+    The callback must only inspect facts: the real index is locked until installation.
+    Git objects/clean-filter side effects are not rolled back.
+    """
+    if validate is not None:
+        from ._staging import stage_validated
+
+        return stage_validated(repo, paths, validate)
+    if not paths:
+        raise ValueError("stage requires explicit paths")
+    return git(repo, "--literal-pathspecs", "add", "--", *paths, timeout=30)
+
+
+def create_branch(repo: str | Path, name: str, base: str) -> GitResult:
+    """Create and check out a branch at a resolved commit; never stash implicitly."""
+    resolved = git(repo, "rev-parse", "--verify", "--end-of-options", f"{base}^{{commit}}")
+    return git(repo, "checkout", "-b", name, resolved.out, timeout=30) if resolved.ok else resolved
+
+
+def commit(repo: str | Path, message: str) -> GitResult:
+    """Commit the current index. Selection and validation belong to the caller."""
+    return git(repo, "commit", "-m", message, timeout=120)
+
+
+def push(
+    repo: str | Path,
+    branch: str,
+    *,
+    remote: str = "origin",
+    upstream: bool = False,
+    lease: str | None = None,
+) -> GitResult:
+    args = ["push"]
+    if upstream:
+        args.append("--set-upstream")
+    if lease is not None:
+        args.append(f"--force-with-lease=refs/heads/{branch}:{lease}")
+    return git(repo, *args, "--", remote, f"HEAD:refs/heads/{branch}", timeout=120)
+
+
+def rebase(repo: str | Path, base: str) -> GitResult:
+    """Leave conflicts in place for the caller; never auto-abort or discard work."""
+    resolved = git(repo, "rev-parse", "--verify", "--end-of-options", f"{base}^{{commit}}")
+    return git(repo, "rebase", resolved.out, timeout=120) if resolved.ok else resolved
+
+
+def continue_rebase(repo: str | Path, *, editor: str | None = None) -> GitResult:
+    """Continue staged conflict resolutions; optionally set core.editor for this call.
+
+    Git's editor environment variables still take precedence over core.editor.
+    Failure leaves the operation in place for the caller to inspect.
+    """
+    config = ["-c", f"core.editor={editor}"] if editor is not None else []
+    return git(repo, *config, "rebase", "--continue", timeout=120)
+
+
+def abort_rebase(repo: str | Path) -> GitResult:
+    """Ask Git to abort the current rebase and restore its original checkout state."""
+    return git(repo, "rebase", "--abort", timeout=30)
+
+
+def add_worktree(
+    repo: str | Path, path: str | Path, ref: str, *, branch: str | None = None, detach: bool = False
+) -> GitResult:
+    if branch is not None and detach:
+        raise ValueError("branch and detach are mutually exclusive")
+    args = ["worktree", "add"]
+    if detach:
+        args.append("--detach")
+    if branch is not None:
+        args += ["-b", branch]
+    return git(repo, *args, "--", str(path), ref, timeout=30)
+
+
+def remove_worktree(repo: str | Path, path: str | Path, *, force: bool = False) -> GitResult:
+    """Default removal preserves dirty and locked worktrees."""
+    return git(
+        repo,
+        "worktree",
+        "remove",
+        *(["--force", "--force"] if force else []),
+        "--",
+        str(path),
+        timeout=30,
+    )
+
+
+def prune_worktrees(repo: str | Path) -> GitResult:
+    """Prune stale worktree registrations using Git's default expiration policy.
+
+    This removes metadata, not checkout directories or branches. Git preserves locked
+    worktree registrations. The caller decides when cleanup is appropriate.
+    """
+    return git(repo, "worktree", "prune", timeout=15)
+
+
+def add_exclude(repo: str | Path, pattern: str) -> bool:
+    """Append one exact pattern to info/exclude; return whether a line was added.
+
+    Resolve metadata through Git so linked worktrees share the correct exclude file.
+    Preserve existing bytes and pattern whitespace. Git/filesystem failures propagate;
+    choosing patterns and accepting a best-effort failure are caller policies.
+    """
+    from .git_state import git_path
+
+    if not pattern or any(char in pattern for char in "\r\n\0"):
+        raise ValueError("exclude pattern must be one nonempty line without NUL")
+    path = git_path(repo, "info/exclude")
+    try:
+        existing = path.read_bytes()
+    except FileNotFoundError:
+        existing = b""
+    encoded = pattern.encode("utf-8")
+    if any(line.removesuffix(b"\r") == encoded for line in existing.split(b"\n")):
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    separator = b"\n" if existing and not existing.endswith(b"\n") else b""
+    with path.open("ab") as output:
+        output.write(separator + encoded + b"\n")
+    return True
+
+
+def changed_paths(repo: str | Path, *, base: str = "HEAD", head: str | None = None) -> list[str]:
+    """Changed paths, including both rename sides; Git failure remains an error."""
+    from ._process import Budget, run
+
+    budget = Budget(10, None)
+    root = Path(repo)
+    before = (
+        run(root, ["rev-parse", "--verify", "--end-of-options", f"{base}^{{commit}}"], budget)
+        .decode()
+        .strip()
+    )
+    args = ["diff", "--no-renames", "--name-only", "-z", before]
+    if head is not None:
+        after = (
+            run(root, ["rev-parse", "--verify", "--end-of-options", f"{head}^{{commit}}"], budget)
+            .decode()
+            .strip()
+        )
+        args.append(after)
+    output = run(root, [*args, "--"], budget)
+    if head is None:
+        output += run(root, ["ls-files", "--others", "--exclude-standard", "-z"], budget)
+    return list(
+        dict.fromkeys(os.fsdecode(p) for p in output.split(b"\0") if p and not p.endswith(b"/"))
+    )
+
+
+def committed_paths(repo: str | Path, rev: str = "HEAD") -> list[str]:
+    """Paths changed by one commit, against its first parent (empty tree for roots)."""
+    from ._process import Budget, run
+
+    budget = Budget(10, None)
+    root = Path(repo)
+    sha = (
+        run(root, ["rev-parse", "--verify", "--end-of-options", f"{rev}^{{commit}}"], budget)
+        .decode()
+        .strip()
+    )
+    output = run(
+        root,
+        [
+            "diff-tree",
+            "--root",
+            "--diff-merges=first-parent",
+            "--no-commit-id",
+            "-r",
+            "--no-renames",
+            "--name-only",
+            "-z",
+            sha,
+            "--",
+        ],
+        budget,
+    )
+    return list(dict.fromkeys(os.fsdecode(p) for p in output.split(b"\0") if p))
+
+
+def range_paths(repo: str | Path, base: str, head: str = "HEAD") -> list[str]:
+    """Branch changes from the merge base to head, preserving both rename sides."""
+    from ._process import Budget, run
+
+    budget = Budget(10, None)
+    root = Path(repo)
+    refs = [
+        run(root, ["rev-parse", "--verify", "--end-of-options", f"{ref}^{{commit}}"], budget)
+        .decode()
+        .strip()
+        for ref in (base, head)
+    ]
+    output = run(
+        root, ["diff", "--no-renames", "--name-only", "-z", f"{refs[0]}...{refs[1]}", "--"], budget
+    )
+    return list(dict.fromkeys(os.fsdecode(p) for p in output.split(b"\0") if p))
+
+
+def fetch_branches(
+    repo: str | Path, branches: list[str], *, remote: str = "origin", timeout: float = 60
+) -> GitResult:
+    """Refresh explicit tracking refs, including remote rewrites and narrow fetch configs."""
+    from .git_state import validate_branch_name
+
+    if not branches:
+        raise ValueError("fetch requires explicit branches")
+    for branch in branches:
+        validate_branch_name(repo, branch)
+    # Validate the destination namespace before constructing refspecs.
+    validate_branch_name(repo, remote)
+    refs = [f"+refs/heads/{b}:refs/remotes/{remote}/{b}" for b in dict.fromkeys(branches)]
+    return git(repo, "fetch", remote, *refs, timeout=timeout)

repokit/git_index.py

@@ -0,0 +1,275 @@
+"""Working-tree and index facts, preserving literal repository-relative paths."""
+
+import hashlib
+import os
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import git as gitcmd
+
+
+@dataclass(frozen=True)
+class StatusEntry:
+    path: str
+    index_status: str
+    worktree_status: str
+    original_path: str | None = None
+
+
+@dataclass(frozen=True)
+class IndexChange:
+    path: str
+    old_mode: str
+    new_mode: str
+    status: str
+
+
+@dataclass(frozen=True)
+class IndexEntry:
+    """One Git index entry; mode and oid retain Git's meaning, including gitlinks."""
+
+    path: str
+    mode: str
+    oid: str
+    stage: int
+
+
+@dataclass(frozen=True)
+class IndexView:
+    """Captured index entries and changes, with config queries bound to their blob IDs.
+
+    Gitlinks are entries like any other path. Registration and commit acceptance
+    belong to consumers. Queries never fall back to working-tree files.
+    """
+
+    changes: tuple[IndexChange, ...]
+    entries: tuple[IndexEntry, ...]
+    _repo: Path = field(repr=False)
+
+    def config_values(self, path: str, pattern: str) -> list[str]:
+        """Read matching Git-config values from a regular file in this index.
+
+        Missing paths or keys return an empty list. Unmerged/non-file entries,
+        malformed config and failed queries raise. Includes are not followed.
+        """
+        entries = [entry for entry in self.entries if entry.path == path]
+        if not entries:
+            return []
+        if len(entries) != 1 or entries[0].stage != 0:
+            raise OSError(f"unmerged config entry: {path}")
+        entry = entries[0]
+        if entry.mode not in ("100644", "100755"):
+            raise OSError(f"config entry is not a regular file: {path}")
+        result = gitcmd.git(
+            self._repo,
+            "config",
+            "--no-includes",
+            "--null",
+            "--blob",
+            entry.oid,
+            "--get-regexp",
+            pattern,
+            raw=True,
+        )
+        # Git's blob reader also returns 1 for malformed config, with stderr.
+        # Only a clean no-match result means an empty selection.
+        if result.rc == 1 and not result.err:
+            return []
+        if not result.ok:
+            raise OSError(result.err or f"cannot read index config: {path}")
+        return [record.partition("\n")[2] for record in result.out.split("\0") if record]
+
+
+def index_view(repo: str | Path, *, index_file: Path | None = None) -> IndexView:
+    """Capture index facts; callers must serialize writes while this is collected."""
+    entries = []
+    for record in _query(
+        repo, "ls-files", "--stage", "--full-name", "-z", index_file=index_file
+    ).split("\0"):
+        if not record:
+            continue
+        metadata, separator, path = record.partition("\t")
+        fields = metadata.split()
+        if not separator or not path or len(fields) != 3 or fields[2] not in ("0", "1", "2", "3"):
+            raise OSError("invalid Git index entry")
+        entries.append(IndexEntry(path, fields[0], fields[1], int(fields[2])))
+    return IndexView(
+        tuple(staged_changes(repo, index_file=index_file)), tuple(entries), Path(repo).resolve()
+    )
+
+
+def _query(repo: str | Path, *args: str, index_file: Path | None = None) -> str:
+    result = gitcmd.git(repo, *args, raw=True, index_file=index_file)
+    if not result.ok:
+        raise OSError(f"cannot read Git {args[0]}: {result.err}")
+    return result.out
+
+
+def status_entries(repo: str | Path) -> list[StatusEntry]:
+    """Status of each changed/untracked file, excluding ignored files.
+
+    Rename/copy entries retain both paths. Failures raise; an empty list means clean.
+    Untracked directories are expanded so callers can select individual files.
+    """
+    records = iter(
+        _query(
+            repo, "--no-optional-locks", "status", "--porcelain=v1", "-z", "--untracked-files=all"
+        ).split("\0")
+    )
+    entries = []
+    for record in records:
+        if not record:
+            continue
+        if len(record) < 4 or record[2] != " ":
+            raise OSError("invalid Git status entry")
+        original = None
+        if "R" in record[:2] or "C" in record[:2]:
+            original = next(records, "")
+            if not original:
+                raise OSError("missing Git rename/copy source")
+        entries.append(StatusEntry(record[3:], record[0], record[1], original))
+    return entries
+
+
+def deleted_tracked_paths(repo: str | Path) -> list[str]:
+    """Tracked paths absent from the working tree; failed reads raise."""
+    return list(
+        dict.fromkeys(
+            p for p in _query(repo, "ls-files", "--deleted", "--full-name", "-z").split("\0") if p
+        )
+    )
+
+
+def staged_changes(repo: str | Path, *, index_file: Path | None = None) -> list[IndexChange]:
+    """Index changes against HEAD (the empty tree for an unborn branch).
+
+    Renames are represented as deletion/addition, so each path retains its own
+    old/new mode. This also preserves gitlink removals and type changes.
+    """
+    records = iter(
+        _query(
+            repo,
+            "diff",
+            "--cached",
+            "--raw",
+            "--no-renames",
+            "--no-ext-diff",
+            "-z",
+            "--",
+            index_file=index_file,
+        ).split("\0")
+    )
+    entries = []
+    for record in records:
+        if not record:
+            continue
+        fields = record.split()
+        path = next(records, "")
+        if len(fields) != 5 or not fields[0].startswith(":") or not path:
+            raise OSError("invalid Git index change")
+        entries.append(IndexChange(path, fields[0][1:], fields[1], fields[4]))
+    return entries
+
+
+def registered_submodules(repo: str | Path) -> list[str]:
+    """Paths declared by the working-tree .gitmodules, without initializing them.
+
+    An absent file or absent declarations means no registrations. Invalid config
+    and failed reads raise rather than presenting unregistered paths as known.
+    """
+    root = _query(repo, "rev-parse", "--show-toplevel").removesuffix("\n")
+    manifest = Path(root) / ".gitmodules"
+    if not manifest.exists():
+        return []
+    result = gitcmd.git(
+        repo,
+        "config",
+        "--null",
+        "--file",
+        str(manifest),
+        "--get-regexp",
+        r"^submodule\..*\.path$",
+        raw=True,
+    )
+    if result.rc == 1:  # git config distinguishes no matching keys from read errors.
+        return []
+    if not result.ok:
+        raise OSError(result.err or "cannot read submodule registrations")
+    return [record.split("\n", 1)[1] for record in result.out.split("\0") if record]
+
+
+def staged_patch(repo: str | Path, path: str) -> str:
+    """Raw zero-context patch for a literal path; failed reads raise."""
+    return _query(
+        repo,
+        "--literal-pathspecs",
+        "diff",
+        "--cached",
+        "--no-ext-diff",
+        "--no-textconv",
+        "-U0",
+        "--",
+        path,
+    )
+
+
+def working_tree_differences(repo: str | Path, index: IndexView) -> list[str]:
+    """Paths whose raw working bytes/modes differ from a captured index.
+
+    @spec Clean filters are not applied: transformed staged bytes are a difference.
+    Includes untracked files, deletions, symlinks, conflicts and gitlink references.
+    Does not validate the project, acquire a writer lock or change the index.
+    @link component://docs/git.md
+    """
+    root = Path(repo).resolve()
+    listed = gitcmd.git(
+        repo, "ls-files", "--cached", "--others", "--exclude-standard", "-z", raw=True
+    )
+    if not listed.ok:
+        raise OSError(f"cannot observe working-tree inputs: {listed.err}")
+    original = {entry.path: entry for entry in index_view(repo).entries}
+    names = {
+        name
+        for name in listed.out.split("\0")
+        if name
+        and (os.path.lexists(root / name) or original.get(name) and original[name].mode == "160000")
+    }
+    candidates = {entry.path: entry for entry in index.entries}
+    different = names.symmetric_difference(candidates)
+    for name in names.intersection(candidates):
+        entry, path = candidates[name], root / name
+        if entry.stage != 0:
+            different.add(name)
+            continue
+        if entry.mode == "160000":
+            # A deinitialized gitlink has no child checkout; its index OID is the input.
+            if (path / ".git").exists():
+                child = gitcmd.git(path, "rev-parse", "HEAD")
+                if not child.ok:
+                    raise OSError(f"cannot read gitlink {name!r}: {child.err}")
+                oid = child.out.strip()
+            else:
+                oid = original[name].oid if name in original else ""
+            if entry.oid != oid:
+                different.add(name)
+            continue
+        info = path.lstat()
+        algorithm = "sha256" if len(entry.oid) == 64 else "sha1"
+        if stat.S_ISLNK(info.st_mode):
+            data = os.fsencode(os.readlink(path))
+            digest = hashlib.new(algorithm, f"blob {len(data)}\0".encode() + data).hexdigest()
+            mode = "120000"
+        elif stat.S_ISREG(info.st_mode):
+            hasher = hashlib.new(algorithm, f"blob {info.st_size}\0".encode())
+            with path.open("rb") as source:
+                while chunk := source.read(65536):
+                    hasher.update(chunk)
+            digest = hasher.hexdigest()
+            mode = "100755" if info.st_mode & stat.S_IXUSR else "100644"
+        else:
+            different.add(name)
+            continue
+        if (entry.oid, entry.mode) != (digest, mode):
+            different.add(name)
+    return sorted(different)