git-worktrees 0.1.0__py3-none-any.whl

worktrees/pick.py

@@ -0,0 +1,105 @@
+"""Choosing one worktree out of the handful this repository has.
+
+No fzf. The largest number of linked worktrees in one repository here is
+four, and at that size a numbered prompt reads faster than a fuzzy finder
+and costs no dependency, no spawn, no tty rules and no absent-fzf fallback.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Sequence
+
+from .git import Refused
+from .repo import Worktree
+
+
+def subsequence(query: str, text: str) -> tuple[int, int] | None:
+    """The one idea worth taking from fzf: the query's letters in order.
+
+    Returns how tightly they cluster and where they start, so `tst` finds
+    `add-tests`. None when they do not all appear.
+    """
+    q, t = query.lower(), text.lower()
+    first: int | None = None
+    last = seen = 0
+    for i, ch in enumerate(t):
+        if seen < len(q) and ch == q[seen]:
+            if first is None:
+                first = i
+            last, seen = i, seen + 1
+    if seen < len(q) or first is None:
+        return None
+    return last - first, first
+
+
+def matches(query: str, worktrees: Sequence[Worktree]) -> list[Worktree]:
+    """Substring first, then subsequence, each group in its own order.
+
+    A substring hit always beats a subsequence one, so typing more of a name
+    never moves it down the list.
+
+    Substring looks at the branch and the path; subsequence looks at the
+    branch alone. Every path here contains `.worktrees`, which supplies a
+    `t`, a `w` and an `o` to any query that wants them, so a loose match
+    against the path finds everything and means nothing.
+    """
+    if not query:
+        return list(worktrees)
+    q = query.lower()
+    exact: list[tuple[int, Worktree]] = []
+    loose: list[tuple[int, Worktree]] = []
+    for wt in worktrees:
+        label, path = wt.label.lower(), wt.path.lower()
+        if q in label:
+            exact.append((label.index(q), wt))
+            continue
+        if q in path:
+            exact.append((len(label) + path.index(q), wt))
+            continue
+        rank = subsequence(query, wt.label)
+        if rank is not None:
+            loose.append((rank[0], wt))
+    return [wt for _, wt in exact] + [wt for _, wt in loose]
+
+
+def choose(
+    candidates: Sequence[Worktree],
+    show: Callable[[str], None],
+    ask: Callable[[str], str] | None = None,
+) -> Worktree | None:
+    """One match takes it outright. Otherwise ask, and None means cancelled.
+
+    A run whose stdin is not a terminal is refused rather than left to block:
+    an agent or a pipe reaching a prompt would hang, and --json answers the
+    same question without one.
+    """
+    if not candidates:
+        return None
+    if len(candidates) == 1:
+        return candidates[0]
+
+    if ask is None:
+        if not sys.stdin.isatty():
+            raise Refused(
+                f"{len(candidates)} worktrees match and this is not a terminal; "
+                "narrow the query, or use --list or --json"
+            )
+        ask = _prompt
+
+    width = max(len(wt.label) for wt in candidates)
+    for i, wt in enumerate(candidates, 1):
+        show(f"{i:>3}  {wt.label:<{width}}  {wt.path}")
+    answer = ask(f"which? [1-{len(candidates)}, or blank to cancel] ").strip()
+    if not answer:
+        return None
+    if not answer.isdigit() or not 1 <= int(answer) <= len(candidates):
+        raise Refused(f"{answer} is not one of 1 to {len(candidates)}")
+    return candidates[int(answer) - 1]
+
+
+def _prompt(text: str) -> str:
+    """The question on stderr, the answer from stdin, so stdout stays data."""
+    sys.stderr.write(text)
+    sys.stderr.flush()
+    return sys.stdin.readline()

worktrees/prune.py

@@ -0,0 +1,170 @@
+"""Removing the worktrees `status` marked `remove`, and nothing else."""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from . import repo as R
+from .git import GitError, Refused, git
+from .verdicts import REMOVE, Verdict
+
+
+@git("worktree prune", mutates=True)
+def worktree_prune() -> None:
+    """Clear git's bookkeeping for worktrees somebody deleted by hand."""
+
+
+@git("worktree remove -- $path", mutates=True)
+def worktree_remove(path: str) -> None:
+    """Drop a checkout. Refuses on its own when the worktree is dirty."""
+
+
+@git("branch -d -- $branch", mutates=True)
+def branch_delete(branch: str) -> None:
+    """-d, never -D: git's own proof of merge is the only proof accepted."""
+
+
+@git("rev-parse --verify $ref", ok=(0, 128))
+def sha_of(ref: str) -> None:
+    """The sha a ref names, for the line that puts it back."""
+
+
+@git("cat-file -t $sha", ok=(0, 128))
+def object_type(sha: str) -> None:
+    """What kind of object a sha is. Every printed sha must be a commit."""
+
+
+def removable(verdicts: list[Verdict]) -> list[Verdict]:
+    """The `remove` rows, which is the whole of what prune may touch.
+
+    The one place the set is derived. `status` prints these as `remove` and
+    `prune` removes these, so the two cannot drift.
+    """
+    return [v for v in verdicts if v.verdict == REMOVE]
+
+
+def restore_line(branch: str, repo: str | os.PathLike[str] | None = None) -> str:
+    """The command that puts a branch back, or '' when no sha can be proved.
+
+    The sha is checked to be a commit. The bug's signature is a correctly
+    shaped restore line carrying the wrong sha, so the check is on the object
+    and not on the sentence.
+    """
+    if not branch:
+        return ""
+    sha = sha_of(f"refs/heads/{branch}", repo=repo)
+    text = sha.out.strip() if sha else ""
+    if not text:
+        return ""
+    kind = object_type(text, repo=repo)
+    if not kind or kind.out.strip() != "commit":
+        return ""
+    return f"git branch {branch} {text}"
+
+
+def plan(
+    go: list[Verdict],
+    delete_ignored: bool,
+    say: Callable[[str], None],
+    repo: str | os.PathLike[str] | None = None,
+) -> None:
+    """Print what would go, and what puts it back, before anything does.
+
+    --quiet and --yes do not silence this.
+    """
+    for v in go:
+        say(f"{v.label}  {v.path}")
+        restore = restore_line(v.branch, repo=repo)
+        if restore:
+            say(f"  restore with: {restore}")
+        if delete_ignored:
+            for path in R.ignored_paths(v.path):
+                say(f"  deleting ignored, unrecoverable: {path}")
+
+
+def _prompt(text: str) -> str:
+    """The question on stderr, the answer from stdin.
+
+    Not `input`, which puts its prompt on stdout: stdout carries the result
+    and nothing else, so `--json` stays parseable in every mode.
+    """
+    sys.stderr.write(text)
+    sys.stderr.flush()
+    return sys.stdin.readline()
+
+
+def confirm(count: int, ask: Callable[[str], str] | None = None) -> bool:
+    """Ask before removing. Anything but yes is no.
+
+    A run whose stdin is not a terminal cannot answer, so it is refused
+    rather than left to block: an agent or a pipe reaches this and would
+    otherwise hang forever holding the repository's worktrees.
+    """
+    if ask is None:
+        if not sys.stdin.isatty():
+            raise Refused(
+                f"not a terminal, so nothing can answer for the {count} above; "
+                "pass --yes to remove them"
+            )
+        ask = _prompt
+    return ask(f"remove {count} worktree(s)? [y/N] ").strip().lower() in ("y", "yes")
+
+
+def sweep(
+    go: list[Verdict],
+    delete_ignored: bool,
+    say: Callable[[str], None],
+    repo: str | os.PathLike[str] | None = None,
+) -> int:
+    """Remove each one, in order. Returns how many failed.
+
+    Serial because `worktree remove` and `branch -d` take the repository's
+    shared refs and its worktrees/ directory. One that git refuses is not a
+    reason to abandon the rest.
+    """
+    main = R.main_worktree(repo)
+    failed = 0
+    for v in go:
+        try:
+            worktree_remove(v.path, repo=repo)
+        except (GitError, Refused) as exc:
+            say(f"{v.label} kept: {exc}")
+            failed += 1
+            continue
+
+        _prune_empty_parents(Path(v.path).parent, main)
+
+        if v.branch:
+            try:
+                # -d, so git's own proof of merge decides. A squash-merged
+                # branch is refused here and kept: the checkout goes, the
+                # branch stays, and the restore line is not needed.
+                branch_delete(v.branch, repo=repo)
+            except (GitError, Refused) as exc:
+                say(f"branch {v.branch} kept: {exc}")
+
+    worktree_prune(repo=repo)
+    return failed
+
+
+def _prune_empty_parents(start: Path, main: str) -> None:
+    """Remove the directories that removing a worktree left empty.
+
+    Up to the worktrees root and never past it. rmdir refuses a directory
+    holding anything, which is the whole guard.
+    """
+    if not main:
+        return
+    root = Path(main).parent / ".worktrees"
+    d = start
+    while d == root or root in d.parents:
+        try:
+            d.rmdir()
+        except OSError:
+            return
+        if d == root:
+            return
+        d = d.parent

worktrees/repo.py

@@ -0,0 +1,323 @@
+"""What this repository is: its worktrees, its remote, its head branch."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .git import git
+
+# --------------------------------------------------------------------------
+# the git calls
+# --------------------------------------------------------------------------
+
+
+@git("worktree list --porcelain -z")
+def worktree_list() -> None:
+    """Every worktree, NUL-delimited."""
+
+
+@git("remote")
+def remotes() -> None:
+    """The names of every remote."""
+
+
+@git("config --get $key", ok=(0, 1))
+def config_get(key: str) -> None:
+    """One config value. Exit 1 means unset, not broken."""
+
+
+@git("symbolic-ref --quiet $ref", ok=(0, 1, 128))
+def symbolic_ref(ref: str) -> None:
+    """What a symbolic ref points at."""
+
+
+@git("symbolic-ref --quiet --short HEAD", ok=(0, 1, 128))
+def current_branch() -> None:
+    """The checked-out branch, short. Exit 1 on a detached HEAD."""
+
+
+@git("show-ref --verify --quiet $ref", ok=(0, 1))
+def ref_exists(ref: str) -> None:
+    """Does this exact ref exist?"""
+
+
+@git("for-each-ref --count=1 --format=%(refname) $prefix")
+def first_ref_under(prefix: str) -> None:
+    """One ref under a prefix, or nothing."""
+
+
+@git("for-each-ref --count=1 --contains $sha")
+def refs_containing(sha: str) -> None:
+    """One ref reaching this commit, or nothing."""
+
+
+# @{upstream} survives the spec: braces are git's revision syntax, not a
+# placeholder, which is why placeholders are spelled with $.
+@git("rev-parse --abbrev-ref --symbolic-full-name $branch@{upstream}", ok=(0, 1, 128))
+def upstream_of(branch: str) -> None:
+    """The upstream a branch tracks. Failure means unknown, not none."""
+
+
+@git("rev-list --count $a..$b", ok=(0, 128))
+def count_between(a: str, b: str) -> None:
+    """How many commits b has that a does not."""
+
+
+@git("rev-parse --show-toplevel", ok=(0, 128))
+def toplevel() -> None:
+    """The root of the worktree we stand in."""
+
+
+@git("rev-parse --path-format=absolute --git-common-dir", ok=(0, 128))
+def common_dir() -> None:
+    """The repository directory every worktree of it shares."""
+
+
+# --no-optional-locks is a git global, so it goes before the subcommand, which
+# a spec shows and a tuple hides. Without it a listing writes another
+# worktree's index and contends with a `git add` there.
+@git("--no-optional-locks status --porcelain")
+def status_porcelain() -> None:
+    """Tracked and untracked changes, one line each."""
+
+
+# --ignored=traditional collapses an ignored directory into one entry, so
+# node_modules/ is one line rather than forty thousand.
+@git("--no-optional-locks status --porcelain --ignored=traditional")
+def status_with_ignored() -> None:
+    """The same, plus the gitignored paths git otherwise never mentions."""
+
+
+@git("fetch --prune $remote", mutates=True)
+def fetch(remote: str) -> None:
+    """Refresh every remote-tracking ref, dropping the ones that are gone."""
+
+
+@git("remote set-head $remote --auto", mutates=True)
+def set_head_auto(remote: str) -> None:
+    """Ask the server which branch it serves by default."""
+
+
+# --------------------------------------------------------------------------
+# worktree records
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Worktree:
+    path: str
+    sha: str
+    branch: str  # empty when detached or bare
+    flags: frozenset[str]  # any of bare, detached, locked, prunable
+
+    @property
+    def label(self) -> str:
+        return self.branch or "(detached)"
+
+
+def worktrees(repo: str | os.PathLike[str] | None = None) -> list[Worktree]:
+    """Every worktree of this repository, main checkout first.
+
+    `git worktree list --porcelain -z` NUL-terminates each attribute and ends
+    a record with an empty one. Without -z git separates attributes by
+    newline, so a directory name holding one parses into two worktrees,
+    neither of which exists.
+    """
+    out = worktree_list(repo=repo).out
+    found: list[Worktree] = []
+    seen: set[str] = set()
+    path = sha = branch = ""
+    flags: set[str] = set()
+
+    def emit() -> None:
+        nonlocal path, sha, branch, flags
+        if path:
+            # The same directory under two spellings is still one worktree.
+            key = str(Path(path).resolve())
+            if key not in seen:
+                seen.add(key)
+                found.append(Worktree(path, sha, branch, frozenset(flags)))
+        path = sha = branch = ""
+        flags = set()
+
+    for attr in out.split("\0"):
+        if attr.startswith("worktree "):
+            emit()
+            path = attr[len("worktree ") :]
+        elif attr.startswith("HEAD "):
+            sha = attr[len("HEAD ") :]
+        elif attr.startswith("branch "):
+            branch = attr[len("branch ") :].removeprefix("refs/heads/")
+        elif attr in ("bare", "detached"):
+            flags.add(attr)
+        elif attr.startswith("locked"):
+            flags.add("locked")
+        elif attr.startswith("prunable"):
+            flags.add("prunable")
+    emit()
+    return found
+
+
+def main_worktree(repo: str | os.PathLike[str] | None = None) -> str:
+    """The original checkout. git lists it first."""
+    records = worktrees(repo)
+    return records[0].path if records else ""
+
+
+# --------------------------------------------------------------------------
+# refs
+# --------------------------------------------------------------------------
+
+
+def full_ref(name: str, repo: str | os.PathLike[str] | None = None) -> str:
+    """The full ref naming branch `name`.
+
+    A bare name used as a revision is resolved as a tag before a branch, so a
+    tag called `origin/main` is what `origin/main` means to merge-base, cherry
+    and ^{tree}. Point that tag at a commit containing an unmerged branch and
+    the branch reads as merged: deleted, at exit 0, with nothing to say it
+    happened.
+
+    Remote-tracking first, because that is what a head branch normally is. A
+    name with no remote-tracking ref is spelled under refs/heads/ whether or
+    not it exists: a name resolving to nothing beats one resolving to a tag.
+    """
+    if not name:
+        return ""
+    if ref_exists(f"refs/remotes/{name}", repo=repo):
+        return f"refs/remotes/{name}"
+    return f"refs/heads/{name}"
+
+
+def ref_name(ref: str) -> str:
+    """The ref as a person says it."""
+    return ref.removeprefix("refs/remotes/").removeprefix("refs/heads/")
+
+
+def remote(repo: str | os.PathLike[str] | None = None) -> str:
+    """The remote this repository belongs to, or empty when it has none.
+
+    `origin` is a convention, not a fact. remote.pushDefault is deliberately
+    not a rung: it names where commits go, not where they come from, and the
+    two differ in exactly the case that makes the question worth asking, a
+    fork you push to and an upstream you branch from.
+    """
+    names = remotes(repo=repo).lines
+    if not names:
+        return ""
+    if len(names) == 1:
+        return names[0]
+
+    stated = [config_get("checkout.defaultRemote", repo=repo).out.strip()]
+    branch = current_branch(repo=repo).out.strip()
+    if branch:
+        stated.append(config_get(f"branch.{branch}.remote", repo=repo).out.strip())
+
+    for candidate in stated:
+        if candidate and candidate != "." and candidate in names:
+            return candidate
+    return "origin" if "origin" in names else names[0]
+
+
+def head_ref(
+    remote_name: str,
+    online: bool,
+    repo: str | os.PathLike[str] | None = None,
+) -> tuple[str, str]:
+    """The full ref this repository branches from, and a warning or ''.
+
+    Returns a full ref, never `origin/main`: every merge question below uses
+    it as a revision, and a bare name resolves to a tag first.
+    """
+    if remote_name:
+        # 1. The repository's own answer, recorded at clone time from what the
+        #    server advertises, so it tells master from main without guessing.
+        #    Ignored when it dangles, which is what a server-side rename
+        #    leaves behind.
+        symref = symbolic_ref(f"refs/remotes/{remote_name}/HEAD", repo=repo).out.strip()
+        if symref and ref_exists(symref, repo=repo):
+            return symref, ""
+
+        # set-head can only point at a remote-tracking ref, so don't spend a
+        # round trip when the repository has none.
+        tracking = first_ref_under(f"refs/remotes/{remote_name}", repo=repo).out.strip()
+        if online and tracking and set_head_auto(remote_name, repo=repo):
+            symref = symbolic_ref(
+                f"refs/remotes/{remote_name}/HEAD", repo=repo
+            ).out.strip()
+            if symref and ref_exists(symref, repo=repo):
+                return symref, ""
+
+    # 2. Conventional names, decisive only when exactly one exists.
+    #    Remote-tracking first: a repository can have a remote and no
+    #    refs/remotes at all, because a remote added by hand was never fetched.
+    found: list[str] = []
+    if remote_name:
+        found = [
+            f"{remote_name}/{c}"
+            for c in ("main", "master", "trunk")
+            if ref_exists(f"refs/remotes/{remote_name}/{c}", repo=repo)
+        ]
+    if not found:
+        found = [
+            c
+            for c in ("main", "master", "trunk")
+            if ref_exists(f"refs/heads/{c}", repo=repo)
+        ]
+    if not found:
+        return "", ""
+
+    # 3. Guess, and be honest that it is one.
+    warning = ""
+    if len(found) > 1:
+        warning = (
+            f"{remote_name}/HEAD is unset and " if remote_name else ""
+        ) + f"{', '.join(found)} all exist, guessing {found[0]}"
+        if remote_name:
+            warning += f"; settle it with: git remote set-head {remote_name} --auto"
+    return full_ref(found[0], repo=repo), warning
+
+
+# --------------------------------------------------------------------------
+# per-worktree questions
+# --------------------------------------------------------------------------
+
+
+def is_dirty(path: str) -> bool:
+    """Uncommitted work, which is what makes `git worktree remove` refuse."""
+    return bool(status_porcelain(repo=path).out.strip())
+
+
+def ignored_paths(path: str) -> list[str]:
+    """The gitignored paths inside a worktree.
+
+    `git status --porcelain` does not mention these, so a checkout holding
+    .env and node_modules/ reads clean, and `git worktree remove` deletes both
+    at exit 0 without --force and without a word. Nothing in git brings them
+    back: no ref ever pointed at them.
+    """
+    return [
+        line[3:]
+        for line in status_with_ignored(repo=path).lines
+        if line.startswith("!! ")
+    ]
+
+
+def unpushed_count(
+    branch: str, repo: str | os.PathLike[str] | None = None
+) -> int | None:
+    """Commits the upstream has not got, or None when there is no upstream.
+
+    None is not zero. Branches made here do not track, so "no upstream" is the
+    normal state, and reporting zero would quietly disarm the guard for
+    exactly those.
+    """
+    up = upstream_of(branch, repo=repo)
+    if not up or not up.out.strip():
+        return None
+    counted = count_between(up.out.strip(), f"refs/heads/{branch}", repo=repo)
+    if not counted:
+        return None
+    return int(counted.out.strip() or 0)