git-worktrees 0.1.0__py3-none-any.whl

worktrees/forge.py

@@ -0,0 +1,115 @@
+"""What the forge says about a branch, when git cannot tell.
+
+A branch merged as part of a stack is the case content cannot answer. Its
+changes reach the head branch across several squashes, and the intermediate
+state it holds differs from the final one in the same regions, so a stale
+branch whose work is upstream and a branch with real work left look exactly
+alike to a diff.
+
+The forge knows. It is asked last, because it costs a round trip and because
+it can be wrong about work pushed after the merge, which is why the answer is
+cross-checked against the commits an upstream has not got.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+from .git import options
+
+
+@dataclass(frozen=True)
+class Request:
+    """A pull or merge request for a branch."""
+
+    number: int
+    state: str  # MERGED, CLOSED, OPEN
+    noun: str  # what that forge calls it
+
+
+def available() -> str:
+    """The forge CLI on PATH, or empty when there is none."""
+    for tool in ("gh", "glab"):
+        if shutil.which(tool):
+            return tool
+    return ""
+
+
+def request_for(
+    branch: str,
+    repo: str | os.PathLike[str] | None = None,
+) -> Request | None:
+    """The newest request whose head is this branch, or None.
+
+    None covers every way of not knowing: no CLI, not authenticated, no
+    remote, no request. The caller treats that as "the forge said nothing"
+    rather than as "no".
+    """
+    tool = available()
+    if not tool:
+        return None
+
+    if tool == "gh":
+        argv = [
+            "gh",
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "all",
+            "--limit",
+            "1",
+            "--json",
+            "number,state",
+        ]
+        noun = "pull request"
+    else:
+        argv = [
+            "glab",
+            "mr",
+            "list",
+            "--source-branch",
+            branch,
+            "--all",
+            "--output",
+            "json",
+        ]
+        noun = "merge request"
+
+    options.log.append(tuple(argv))
+    if options.verbose:
+        import shlex
+        import sys
+
+        print("+ " + shlex.join(argv), file=sys.stderr)
+
+    try:
+        proc = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=os.fspath(repo) if repo else None,
+            timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if proc.returncode != 0:
+        return None
+
+    try:
+        rows = json.loads(proc.stdout or "[]")
+    except json.JSONDecodeError:
+        return None
+    if not rows:
+        return None
+
+    row = rows[0]
+    number = row.get("number") or row.get("iid") or 0
+    state = str(row.get("state", "")).upper()
+    return Request(int(number), state, noun)

worktrees/git.py

@@ -0,0 +1,302 @@
+"""Every git command this program can run.
+
+A decorated function's spec is the command, written the way you would type it,
+with `$name` where a value goes. Reading a module top to bottom gives the
+complete list of git calls that can be issued, and `worktrees --explain`
+prints it.
+
+`shlex.split` runs once, at decoration time, on the literal spec. Only then is
+each token scanned for placeholders. That ordering is the safety property: the
+splitting is already over before any value is seen, so a branch named
+`feat$(touch /tmp/PWNED)`, `a"b` or `has space` lands as exactly one argv
+element. Nothing is ever a shell string.
+
+`$` rather than `{}` because git's revision syntax is full of braces:
+`^{tree}`, `^{commit}` and `@{upstream}` pass through a spec untouched.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import os
+import shlex
+import subprocess
+import sys
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+Argv = tuple[str, ...]
+
+
+class GitError(RuntimeError):
+    """git exited with a code the caller did not declare acceptable."""
+
+
+class Refused(Exception):
+    """The guard will not issue this command. No flag reaches past it."""
+
+
+@dataclass
+class Run:
+    """What one git call produced."""
+
+    code: int
+    out: str
+    err: str
+
+    def __bool__(self) -> bool:
+        return self.code == 0
+
+    @property
+    def lines(self) -> list[str]:
+        return self.out.splitlines()
+
+
+@dataclass
+class Options:
+    """Set once by the CLI, read by every call."""
+
+    verbose: bool = False
+    # Every argv issued, in order. A test asserts on this; nothing else reads
+    # it, so it costs a list append.
+    log: list[Argv] = field(default_factory=list)
+
+
+options = Options()
+
+
+@dataclass(frozen=True)
+class Command:
+    """A decorated git call, for --explain."""
+
+    name: str
+    doc: str
+    mutates: bool
+    ok: tuple[int, ...]
+    shape: Argv
+
+
+_registry: list[Command] = []
+
+
+def commands() -> list[Command]:
+    """Every git command the program can issue, in declaration order."""
+    return list(_registry)
+
+
+# --------------------------------------------------------------------------
+# the guard
+# --------------------------------------------------------------------------
+
+# Each of these destroys work git cannot give back. They are refused
+# absolutely: there is no flag, and --yes least of all. The check runs on the
+# resolved argv inside the wrapper, so a caller cannot assemble one past it.
+_ABSOLUTE = "refusing to run"
+
+
+def _has(argv: Sequence[str], *flags: str) -> bool:
+    return any(a in flags for a in argv)
+
+
+def _short(argv: Sequence[str], letter: str) -> bool:
+    """A bundled short flag: -f matches, and so does -fdx."""
+    return any(
+        a.startswith("-") and not a.startswith("--") and letter in a[1:] for a in argv
+    )
+
+
+def guard(argv: Sequence[str]) -> None:
+    """Raise Refused for a command that can lose work."""
+    if not argv:
+        raise Refused("empty git command")
+    head = argv[0]
+    rest = argv[1:]
+
+    if head == "reset" and _has(argv, "--hard"):
+        raise Refused(f"{_ABSOLUTE} `git reset --hard`; it discards the working tree")
+    if head in ("checkout", "switch") and (
+        _short(rest, "f") or _has(rest, "--force", "--discard-changes")
+    ):
+        raise Refused(
+            f"{_ABSOLUTE} a forced `git {head}`; it discards the working tree"
+        )
+    if head == "clean" and (_short(rest, "f") or _has(rest, "--force")):
+        raise Refused(f"{_ABSOLUTE} `git clean -f`; nothing restores what it deletes")
+    if head == "push" and (_short(rest, "f") or _has(rest, "--force")):
+        raise Refused(
+            f"{_ABSOLUTE} a bare `git push --force`; use --force-with-lease instead"
+        )
+    if (
+        head == "worktree"
+        and rest
+        and rest[0] == "remove"
+        and (_short(rest, "f") or _has(rest, "--force"))
+    ):
+        raise Refused(
+            f"{_ABSOLUTE} `git worktree remove --force`; it takes uncommitted work "
+            "and ignored files without a word"
+        )
+    if head == "branch" and (
+        _has(rest, "-D") or (_has(rest, "--delete") and _has(rest, "--force"))
+    ):
+        raise Refused(
+            f"{_ABSOLUTE} `git branch -D`; a branch is deleted on proof of merge "
+            "or not at all"
+        )
+
+
+# --------------------------------------------------------------------------
+# the decorator
+# --------------------------------------------------------------------------
+
+
+class GitCall(Protocol):
+    """What a decorated function becomes: its own arguments, plus `repo`."""
+
+    __name__: str
+
+    def __call__(
+        self, *args: Any, repo: str | os.PathLike[str] | None = None, **kwargs: Any
+    ) -> Run: ...
+
+
+def _placeholders(token: str) -> list[str]:
+    """The parameter names a spec token refers to."""
+    names, i = [], 0
+    while i < len(token):
+        if token[i] != "$":
+            i += 1
+            continue
+        if token[i + 1 : i + 2] == "$":
+            i += 2
+            continue
+        j = i + 2 if token[i + 1 : i + 2] == "*" else i + 1
+        k = j
+        while k < len(token) and (token[k].isalnum() or token[k] == "_"):
+            k += 1
+        if k > j:
+            names.append(token[j:k])
+        i = max(k, i + 1)
+    return names
+
+
+def _expand(token: str, bound: Mapping[str, Any]) -> list[str]:
+    """One spec token becomes one argv element, or several for a `$*splat`.
+
+    `$$` is a literal `$`, and so is a `$` with no name after it, so a
+    `--format=` string can hold one without meaning a parameter.
+    """
+    if "$*" in token:
+        return [str(v) for v in bound[token[token.index("$*") + 2 :]]]
+    out, i = "", 0
+    while i < len(token):
+        if token[i] != "$":
+            out += token[i]
+            i += 1
+            continue
+        if token[i + 1 : i + 2] == "$":
+            out += "$"
+            i += 2
+            continue
+        j = i + 1
+        while j < len(token) and (token[j].isalnum() or token[j] == "_"):
+            j += 1
+        if j == i + 1:
+            out += "$"
+            i += 1
+            continue
+        out += str(bound[token[i + 1 : j]])
+        i = j
+    return [out]
+
+
+def git(
+    spec: str,
+    *,
+    ok: Iterable[int] = (0,),
+    mutates: bool = False,
+    env: Mapping[str, str] | None = None,
+) -> Callable[[Callable[..., Any]], GitCall]:
+    """Turn a spec into a function that runs it.
+
+    spec     the command as you would type it, with `$name` where a value goes
+    ok       exit codes that mean an answer rather than a failure
+    mutates  takes the repository's shared refs, so it runs serially
+    env      pinned environment, for a command whose output must be reproducible
+
+    A value goes in three ways. `$name` anywhere, including inside a token, so
+    `--format=$fmt` stays one element. `$*name` splats a list at that position.
+    Anything the body returns is appended as a tail, for arguments with no
+    fixed place.
+    """
+    if not isinstance(spec, str):
+        raise TypeError(
+            '@git takes the command as a string: @git("worktree list -z"). '
+            f"Got {type(spec).__name__}."
+        )
+    accept = tuple(ok)
+    tokens = shlex.split(spec)
+
+    def decorate(fn: Callable[..., Any]) -> GitCall:
+        signature = inspect.signature(fn)
+        # At import, not at the call. A spec naming a parameter the function
+        # does not have is a typo, and this is the moment it is cheapest to
+        # hear about.
+        for token in tokens:
+            for name in _placeholders(token):
+                if name not in signature.parameters:
+                    raise NameError(
+                        f"{fn.__name__}: spec names ${name}, which is not a "
+                        f"parameter of {fn.__name__}{signature}"
+                    )
+
+        @functools.wraps(fn)
+        def call(
+            *args: Any, repo: str | os.PathLike[str] | None = None, **kwargs: Any
+        ) -> Run:
+            bound = signature.bind(*args, **kwargs)
+            bound.apply_defaults()
+            argv: list[str] = []
+            for token in tokens:
+                argv += _expand(token, bound.arguments)
+            tail = fn(*args, **kwargs)
+            if tail:
+                argv += [str(t) for t in tail]
+            guard(argv)
+
+            full = ["git"]
+            if repo is not None:
+                full += ["-C", os.fspath(repo)]
+            full += argv
+
+            options.log.append(tuple(full))
+            if options.verbose:
+                # shlex.join, so the printed line pastes back into a shell.
+                print("+ " + shlex.join(full), file=sys.stderr)
+            environ = None
+            if env is not None:
+                environ = {**os.environ, **env}
+            proc = subprocess.run(
+                full, capture_output=True, text=True, env=environ, check=False
+            )
+            if proc.returncode not in accept:
+                raise GitError(
+                    f"git {shlex.join(argv)} exited {proc.returncode}: "
+                    f"{proc.stderr.strip() or '(no output)'}"
+                )
+            return Run(proc.returncode, proc.stdout, proc.stderr)
+
+        _registry.append(
+            Command(
+                name=fn.__name__,
+                doc=(fn.__doc__ or "").strip().splitlines()[0] if fn.__doc__ else "",
+                mutates=mutates,
+                ok=accept,
+                shape=tuple(tokens),
+            )
+        )
+        return call
+
+    return decorate

worktrees/layout.py

@@ -0,0 +1,52 @@
+"""Where a worktree lives.
+
+Derived rather than configured, so two independently-invoked tools cannot
+disagree about a location neither can be told: `<PARENT>/.worktrees/<NAME>/
+<REPO>`, where PARENT is the directory holding the main checkout and REPO is
+its name.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from . import repo as R
+
+
+def worktrees_root(main: str) -> Path:
+    """The directory every worktree of this repository sits under."""
+    return Path(main).parent / ".worktrees"
+
+
+def destination(name: str, main: str) -> Path:
+    """Where the worktree for branch `name` belongs.
+
+    A branch name may hold slashes, and they become directories, which is why
+    the repository name goes last: `feat/oauth` gives
+    `.worktrees/feat/oauth/<repo>` rather than colliding with `.worktrees/feat`.
+    """
+    return worktrees_root(main) / name / Path(main).name
+
+
+def owner_of(candidate: str, repo: str | os.PathLike[str] | None = None) -> str:
+    """The repository owning the checkout at `candidate`, when it is not ours.
+
+    Empty when we own it, or when there is no repository there at all.
+
+    git is what answers this. `git worktree list` cannot: a worktree belonging
+    to another repository is one this repository has never heard of, so the
+    list comes back empty and reads exactly like "nothing is there", which is
+    how a `gwa` that should have refused lands you in somebody else's
+    checkout.
+    """
+    theirs = R.common_dir(repo=candidate)
+    if not theirs or not theirs.out.strip():
+        return ""
+    ours = R.common_dir(repo=repo)
+    if not ours or not ours.out.strip():
+        return ""
+    t = Path(theirs.out.strip()).resolve()
+    if t == Path(ours.out.strip()).resolve():
+        return ""
+    return str(t.parent)

worktrees/merged.py

@@ -0,0 +1,103 @@
+"""Is a branch's change already in the head branch?
+
+`git branch --merged` answers for the merge git can see. Most branches now end
+in a squash, which rewrites their commits into one, so git sees a branch whose
+commits appear nowhere in the head branch: the same shape as a branch nobody
+ever merged. Reaping on that reading loses work; refusing on it means never
+reaping anything.
+
+By hand the two are indistinguishable. `squashed` and `unmerged` both report
+NOT merged and both sit one commit ahead. Opposite correct actions, no signal
+between them.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .git import git
+
+# commit-tree fails outright when user.email is unset, and a fixed identity
+# keeps the synthetic commit reproducible. Nothing references it, so the next
+# gc collects it.
+_SYNTHETIC = {
+    "GIT_AUTHOR_NAME": "worktrees",
+    "GIT_AUTHOR_EMAIL": "worktrees@localhost",
+    "GIT_AUTHOR_DATE": "@0 +0000",
+    "GIT_COMMITTER_NAME": "worktrees",
+    "GIT_COMMITTER_EMAIL": "worktrees@localhost",
+    "GIT_COMMITTER_DATE": "@0 +0000",
+}
+
+
+@git("merge-base --is-ancestor $ref $head", ok=(0, 1))
+def is_ancestor(ref: str, head: str) -> None:
+    """Non-zero means 'no', not 'broken'."""
+
+
+@git("merge-base $a $b", ok=(0, 128))
+def merge_base(a: str, b: str) -> None:
+    """The commit two refs last had in common."""
+
+
+@git("rev-parse $ref^{tree}", ok=(0, 128))
+def tree_of(ref: str) -> None:
+    """The tree a ref points at."""
+
+
+@git("commit-tree $tree -p $parent -m _", env=_SYNTHETIC, ok=(0, 128))
+def commit_tree(tree: str, parent: str) -> None:
+    """Replay a tree as one commit on top of a parent."""
+
+
+@git("cherry $head $synth", ok=(0, 128))
+def cherry(head: str, synth: str) -> None:
+    """Compare by patch content, which is what a squash preserves."""
+
+
+def squash_merged(
+    branch: str, head: str, repo: str | os.PathLike[str] | None = None
+) -> bool:
+    """Is the change `branch` makes already in `head`?
+
+    Replay the branch's tree as a single commit on the merge base and let
+    `git cherry` say whether that patch is upstream. A leading '-' means it is.
+    """
+    ref = f"refs/heads/{branch}"
+
+    tree = tree_of(ref, repo=repo)
+    if not tree or not tree.out.strip():
+        return False
+
+    # A branch leaving the head branch's tree exactly as it found it has
+    # nothing left to contribute, whatever its history says.
+    head_tree = tree_of(head, repo=repo)
+    if head_tree and head_tree.out.strip() == tree.out.strip():
+        return True
+
+    base = merge_base(head, ref, repo=repo)
+    if not base or not base.out.strip():
+        return False
+
+    synth = commit_tree(tree.out.strip(), base.out.strip(), repo=repo)
+    if not synth or not synth.out.strip():
+        return False
+
+    verdict = cherry(head, synth.out.strip(), repo=repo)
+    lines = verdict.lines if verdict else []
+    return bool(lines) and lines[0].startswith("-")
+
+
+def merged_reason(
+    branch: str, head: str, repo: str | os.PathLike[str] | None = None
+) -> str:
+    """'merged', 'squash-merged', or '' when neither.
+
+    refs/heads/ explicitly: a branch name used as a revision resolves to a tag
+    first, so a tag and a branch sharing a name would answer about the tag.
+    """
+    if is_ancestor(f"refs/heads/{branch}", head, repo=repo):
+        return "merged"
+    if squash_merged(branch, head, repo=repo):
+        return "squash-merged"
+    return ""

worktrees/new_branch.py

@@ -0,0 +1,79 @@
+"""Start a branch off a head branch that was fetched a moment ago.
+
+The base is <remote>/<head> as it stands after the fetch, not the local copy
+of it, so the branch is already on top of what the server has and nothing has
+to be rebased afterwards.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from . import repo as R
+from .git import git
+
+
+@git("check-ref-format --branch $name", ok=(0, 1, 128))
+def check_ref_format(name: str) -> None:
+    """Would git accept this as a branch name?"""
+
+
+@git("rev-parse --short $ref", ok=(0, 128))
+def short_sha(ref: str) -> None:
+    """The short sha a ref names."""
+
+
+@git("switch --create $name --no-track $base", mutates=True)
+def switch_create(name: str, base: str) -> None:
+    """--no-track, so the head branch does not become this branch's upstream.
+
+    A branch off refs/remotes/<remote>/main that tracked it would take it as
+    its upstream, and `git push` would target the head branch.
+    """
+
+
+@dataclass(frozen=True)
+class Started:
+    branch: str
+    base: str  # the full ref
+    sha: str
+
+
+class Refusal(Exception):
+    """Why no branch was made. The message is the whole answer."""
+
+
+def create(
+    name: str,
+    fetch: bool,
+    warn: object = None,
+    repo: str | os.PathLike[str] | None = None,
+) -> Started:
+    """Fetch, then branch `name` off the head branch and check it out."""
+    if not check_ref_format(name, repo=repo):
+        raise Refusal(f"{name} is not a valid branch name")
+    if R.ref_exists(f"refs/heads/{name}", repo=repo):
+        # Native git, so the message names a command that exists for somebody
+        # who installed the package without the shell plugin.
+        raise Refusal(f"{name} is already a branch; git switch {name} checks it out")
+
+    remote = R.remote(repo=repo)
+    if fetch and remote and not R.fetch(remote, repo=repo) and callable(warn):
+        # An offline machine still gets a branch, off whatever it last saw,
+        # and the line at the end names the commit it got.
+        warn(f"{remote} could not be fetched; branching from what is already here")
+
+    base, warning = R.head_ref(remote, online=fetch, repo=repo)
+    if warning and callable(warn):
+        warn(warning)
+    if not base:
+        hint = remote or "origin"
+        raise Refusal(
+            "cannot tell which branch this repository branches from; record it "
+            f"with: git remote set-head {hint} --auto"
+        )
+
+    sha = short_sha(base, repo=repo)
+    switch_create(name, base, repo=repo)
+    return Started(name, base, sha.out.strip() if sha else "")