git-worktrees 0.1.0__py3-none-any.whl

worktrees/rotate.py

@@ -0,0 +1,142 @@
+"""Start the next branch in a series, or catch the head branch up.
+
+`new-branch` names a branch. This one works out the name, from the branch you
+are standing on, and starts it. Two commands rather than one with an optional
+argument: naming and continuing are different jobs, and a command doing both
+needs an "and" in its description.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from datetime import date
+
+from . import repo as R
+from .git import git
+from .new_branch import Refusal, short_sha, switch_create
+
+# <stem>-YYYY-MM-DD_NNN. Three digits, so the sequence cannot be read as
+# another field of the date the way a two-digit one beside -09-10 can.
+SUFFIX = re.compile(r"-\d{4}-\d{2}-\d{2}_\d{3}$")
+
+
+@git("merge --ff-only $ref", mutates=True)
+def merge_ff_only(ref: str) -> None:
+    """Never a rebase: rewriting local commits on the head branch is the
+    class this tooling refuses everywhere else."""
+
+
+@git("log --oneline --no-decorate $range")
+def log_oneline(range: str) -> None:
+    """The commits in a range, for saying which ones are in the way."""
+
+
+@dataclass(frozen=True)
+class Rotated:
+    branch: str
+    stem: str
+    base: str  # the full ref
+    sha: str
+
+
+@dataclass(frozen=True)
+class CaughtUp:
+    branch: str
+    at: str  # the ref it now matches
+
+
+def stem(branch: str) -> str:
+    """The branch with any suffix a previous rotation added taken off.
+
+    So four rotations in a day give four siblings rather than one name
+    carrying four suffixes.
+    """
+    return SUFFIX.sub("", branch)
+
+
+def next_name(
+    base_stem: str,
+    remote: str,
+    today: str | None = None,
+    repo: str | os.PathLike[str] | None = None,
+) -> str:
+    """`<stem>-YYYY-MM-DD_NNN` at the first NNN free today.
+
+    Free means free here and on the remote: a number nothing holds locally
+    but the remote already carries is not free, or two people rotate into the
+    same name.
+    """
+    day = today or date.today().isoformat()
+    for n in range(1, 1000):
+        name = f"{base_stem}-{day}_{n:03d}"
+        if R.ref_exists(f"refs/heads/{name}", repo=repo):
+            continue
+        if remote and R.ref_exists(f"refs/remotes/{remote}/{name}", repo=repo):
+            continue
+        return name
+    raise Refusal(f"every number from 001 to 999 is taken for {base_stem} on {day}")
+
+
+def rotate(
+    fetch: bool,
+    warn: object = None,
+    repo: str | os.PathLike[str] | None = None,
+) -> Rotated | CaughtUp:
+    """Start the next branch after this one, or catch the head branch up."""
+    branch = R.current_branch(repo=repo).out.strip()
+    if not branch:
+        raise Refusal(
+            "HEAD is detached, so there is no branch to name the next one "
+            "after; 'worktrees new-branch <name>' names one"
+        )
+
+    remote = R.remote(repo=repo)
+    if fetch and remote and not R.fetch(remote, repo=repo) and callable(warn):
+        warn(f"{remote} could not be fetched; working 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"
+        )
+
+    head_name = R.ref_name(base)
+    if remote:
+        head_name = head_name.removeprefix(remote + "/")
+
+    if branch == head_name:
+        return _catch_up(branch, base, repo=repo)
+
+    chosen = next_name(stem(branch), remote, repo=repo)
+    sha = short_sha(base, repo=repo)
+    switch_create(chosen, base, repo=repo)
+    return Rotated(chosen, stem(branch), base, sha.out.strip() if sha else "")
+
+
+def _catch_up(
+    branch: str, base: str, repo: str | os.PathLike[str] | None = None
+) -> CaughtUp:
+    """There is no chain to continue from the head branch, so bring it level.
+
+    --ff-only refuses when the local copy is ahead, which is the answer: those
+    commits are a change of their own and belong on a branch.
+    """
+    ahead = R.count_between(base, f"refs/heads/{branch}", repo=repo)
+    count = int(ahead.out.strip() or 0) if ahead else 0
+    if count:
+        listed = log_oneline(f"{base}..refs/heads/{branch}", repo=repo)
+        lines = "\n".join(f"  {line}" for line in listed.lines) if listed else ""
+        raise Refusal(
+            f"{branch} is {count} commit(s) ahead of {R.ref_name(base)}, so it "
+            f"cannot be fast-forwarded:\n{lines}\n"
+            "Those commits are a change of their own; "
+            "'worktrees new-branch <name>' puts them on one."
+        )
+    merge_ff_only(base, repo=repo)
+    return CaughtUp(branch, R.ref_name(base))

worktrees/verdicts.py

@@ -0,0 +1,161 @@
+"""One verdict per worktree. Nothing here mutates."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import forge
+from . import repo as R
+from .merged import merged_reason
+
+# The verdicts, each the instruction it gives. `unknown` is not `keep` with a
+# softer word: "no upstream, so nothing says whether this was pushed" is a
+# different fact from "this is not merged", and a sweep printing them the same
+# way invites somebody to act on the wrong one.
+REMOVE = "remove"
+KEEP = "keep"
+UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class Verdict:
+    verdict: str
+    branch: str  # empty when detached
+    path: str
+    why: str
+
+    @property
+    def label(self) -> str:
+        return self.branch or "(detached)"
+
+
+def stale(records: list[R.Worktree]) -> list[R.Worktree]:
+    """Records answering for a directory somebody deleted by hand.
+
+    `git worktree prune` is what clears them, so they are nobody's verdict:
+    neither command may propose removing a checkout that is not there.
+    """
+    return [w for w in records if "prunable" in w.flags]
+
+
+def assess(
+    records: list[R.Worktree],
+    only: str,
+    head: str,
+    head_branch: str,
+    delete_ignored: bool,
+    repo: str | os.PathLike[str] | None = None,
+    here: str | None = None,
+    ask_forge: bool = False,
+) -> list[Verdict]:
+    """Every worktree, in the order `git worktree remove` would refuse them.
+
+    Proposing something that would then be refused is a bug here, not a
+    surprise at the confirmation.
+
+    `here` is the checkout the caller is standing in, which is kept rather
+    than proposed. Pass "" to judge it like any other: `gwr` is asked for one
+    by name and steps out of it first, where a listing has no way to.
+    """
+    main = R.main_worktree(repo)
+    if here is None:
+        here = R.toplevel(repo=repo).out.strip()
+    head_name = R.ref_name(head)
+
+    out: list[Verdict] = []
+    for wt in records:
+        if "bare" in wt.flags or "prunable" in wt.flags or wt.path == main:
+            continue
+        if only and wt.branch != only:
+            continue
+
+        def say(verdict: str, why: str, wt: R.Worktree = wt) -> None:
+            out.append(Verdict(verdict, wt.branch, wt.path, why))
+
+        if here and Path(wt.path).resolve() == Path(here).resolve():
+            say(KEEP, "you are standing in it")
+            continue
+        if "locked" in wt.flags:
+            say(KEEP, "it is locked")
+            continue
+        if wt.branch and wt.branch == head_branch:
+            say(KEEP, "it is the head branch")
+            continue
+        if R.is_dirty(wt.path):
+            say(KEEP, "it has uncommitted changes")
+            continue
+
+        if not wt.branch:
+            # Detached: finished when some ref already reaches the commit,
+            # which is the question `git worktree remove` asks of one.
+            if R.refs_containing(wt.sha, repo=repo).out.strip():
+                say(REMOVE, "its commit is reached by a ref")
+            else:
+                say(UNKNOWN, f"no ref reaches {wt.sha}")
+            continue
+
+        reason = merged_reason(wt.branch, head, repo=repo)
+        if not reason and ask_forge:
+            reason, verdict = _forge_reason(wt.branch, repo=repo)
+            if verdict:
+                say(verdict, reason)
+                continue
+        if not reason:
+            if R.unpushed_count(wt.branch, repo=repo) is None:
+                say(
+                    UNKNOWN,
+                    f"not merged into {head_name}, and no upstream says whether "
+                    "its commits were pushed",
+                )
+            else:
+                say(KEEP, f"not merged into {head_name}")
+            continue
+
+        ignored = R.ignored_paths(wt.path)
+        if ignored and not delete_ignored:
+            say(
+                KEEP,
+                f"{reason}, but holds {len(ignored)} ignored path(s); "
+                "pass --delete-ignored",
+            )
+            continue
+
+        say(REMOVE, reason)
+    return out
+
+
+def _forge_reason(
+    branch: str, repo: str | os.PathLike[str] | None = None
+) -> tuple[str, str]:
+    """What the forge says, cross-checked against what it cannot see.
+
+    Returns (reason, verdict), or ("", "") when the forge said nothing and
+    the content probes keep the answer.
+
+    A merged request speaks for what was pushed. Commits an upstream has not
+    got were never in it, and a branch with no upstream at all leaves that
+    unknown rather than zero: branches made here do not track, so "no
+    upstream" is the normal state for exactly the ones this would otherwise
+    reap.
+    """
+    request = forge.request_for(branch, repo=repo)
+    if request is None or request.state not in ("MERGED", "CLOSED"):
+        return "", ""
+
+    lower = request.state.lower()
+    unpushed = R.unpushed_count(branch, repo=repo)
+    if unpushed is None:
+        return (
+            f"its {request.noun} is {lower}, but the branch has no upstream "
+            "to have been pushed to",
+            UNKNOWN,
+        )
+    if unpushed:
+        return (
+            f"its {request.noun} is {lower}, but {unpushed} commit(s) here "
+            "are not in it",
+            KEEP,
+        )
+    return f"its {request.noun} #{request.number} is {lower}", REMOVE

worktrees/worktree.py

@@ -0,0 +1,221 @@
+"""Adding, moving and removing a checkout.
+
+Each of these lands the caller somewhere, so each prints a destination on
+stdout and nothing else. A binary cannot cd its caller; the shim reads that
+line and does the move.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import layout
+from . import repo as R
+from .git import GitError, Refused, git
+from .new_branch import Refusal, check_ref_format
+from .prune import _prune_empty_parents, branch_delete, worktree_remove
+from .verdicts import REMOVE, Verdict, assess
+
+
+@git("worktree add --no-track -b $name -- $dest $base", mutates=True)
+def worktree_add(name: str, dest: str, base: str) -> None:
+    """--no-track, for the reason new-branch has it: a branch off the head
+    branch that tracked it would take it as its upstream."""
+
+
+@git("worktree add -- $dest $name", mutates=True)
+def worktree_add_existing(dest: str, name: str) -> None:
+    """A branch that already exists needs no -b, and -b would refuse."""
+
+
+@git("worktree move -- $old $new", mutates=True)
+def worktree_move(old: str, new: str) -> None:
+    """git updates its own bookkeeping, which a mv would leave behind."""
+
+
+@git("branch --move -- $old $new", mutates=True)
+def branch_move(old: str, new: str) -> None:
+    """--move, not --move --force: a rename onto a name that exists is a
+    collision to report rather than one to resolve."""
+
+
+@dataclass(frozen=True)
+class Landed:
+    """Where the caller should end up, and what happened to get there."""
+
+    path: str
+    branch: str
+    created: bool  # False when the branch was already here
+
+
+def add(
+    name: str,
+    base: str = "",
+    fetch: bool = True,
+    warn: object = None,
+    repo: str | os.PathLike[str] | None = None,
+) -> Landed:
+    """Create a worktree for `name` and say where it is."""
+    if not check_ref_format(name, repo=repo):
+        raise Refusal(f"{name} is not a valid branch name")
+
+    main = R.main_worktree(repo)
+    if not main:
+        raise Refusal("not inside a git repository")
+    dest = layout.destination(name, main)
+
+    for wt in R.worktrees(repo):
+        if wt.branch == name:
+            raise Refusal(f"{name} is already checked out at {wt.path}")
+
+    if dest.exists():
+        owner = layout.owner_of(str(dest), repo=repo)
+        if owner:
+            raise Refusal(f"{dest} belongs to {owner}, not to this repository")
+        raise Refusal(f"{dest} already exists and this repository does not own it")
+
+    remote = R.remote(repo=repo)
+    if fetch and remote and not R.fetch(remote, repo=repo) and callable(warn):
+        warn(f"{remote} could not be fetched; branching from what is already here")
+
+    existing = bool(R.ref_exists(f"refs/heads/{name}", repo=repo))
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if existing:
+        worktree_add_existing(str(dest), name, repo=repo)
+        return Landed(str(dest), name, created=False)
+
+    start = base or _head(remote, fetch, warn, repo=repo)
+    worktree_add(name, str(dest), start, repo=repo)
+    return Landed(str(dest), name, created=True)
+
+
+def _head(
+    remote: str,
+    fetch: bool,
+    warn: object,
+    repo: str | os.PathLike[str] | None = None,
+) -> str:
+    ref, warning = R.head_ref(remote, online=fetch, repo=repo)
+    if warning and callable(warn):
+        warn(warning)
+    if not ref:
+        hint = remote or "origin"
+        raise Refusal(
+            "cannot tell which branch this repository branches from; record it "
+            f"with: git remote set-head {hint} --auto"
+        )
+    return ref
+
+
+def move(
+    new: str,
+    repo: str | os.PathLike[str] | None = None,
+) -> Landed:
+    """Rename this worktree's branch and move the checkout to match.
+
+    Not a convenience. Renaming the directory you are standing in leaves the
+    shell with a stale $PWD and every later command failing, so the caller
+    has to be told where to go.
+    """
+    if not check_ref_format(new, repo=repo):
+        raise Refusal(f"{new} is not a valid branch name")
+
+    here = R.toplevel(repo=repo).out.strip()
+    if not here:
+        raise Refusal("not inside a git repository")
+    main = R.main_worktree(repo)
+    if Path(here).resolve() == Path(main).resolve():
+        raise Refusal(
+            "this is the main checkout, not a worktree; "
+            "git branch --move renames its branch"
+        )
+
+    old = R.current_branch(repo=here).out.strip()
+    if not old:
+        raise Refusal("HEAD is detached here, so there is no branch to rename")
+    if old == new:
+        raise Refusal(f"this worktree is already on {new}")
+    if R.ref_exists(f"refs/heads/{new}", repo=repo):
+        raise Refusal(f"{new} is already a branch")
+
+    dest = layout.destination(new, main)
+    if dest.exists():
+        raise Refusal(f"{dest} already exists")
+
+    # The branch first: `worktree move` leaves the branch alone, and a failed
+    # move after a rename is recoverable where the reverse loses the name.
+    branch_move(old, new, repo=repo)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        worktree_move(here, str(dest), repo=repo)
+    except (GitError, Refused):
+        branch_move(new, old, repo=repo)
+        raise
+    _prune_empty_parents(Path(here).parent, main)
+    return Landed(str(dest), new, created=False)
+
+
+def remove(
+    chosen: Verdict,
+    say: object,
+    repo: str | os.PathLike[str] | None = None,
+) -> str:
+    """Remove one worktree, and say where to go when it was this one.
+
+    Returns the main checkout when the caller was standing in what went, and
+    an empty string otherwise. Empty means stay put.
+
+    What goes and what puts it back is printed by the caller, before this is
+    reached, so that a run which stops at the confirmation has still said it.
+    """
+    here = R.toplevel(repo=repo).out.strip()
+    main = R.main_worktree(repo)
+    standing_in = bool(here) and Path(here).resolve() == Path(chosen.path).resolve()
+
+    if standing_in:
+        # git refuses to remove the worktree a process is sitting in only
+        # sometimes; leaving first makes it always safe and gives the shim a
+        # destination to move to.
+        os.chdir(main)
+
+    worktree_remove(chosen.path, repo=main)
+    _prune_empty_parents(Path(chosen.path).parent, main)
+    if chosen.branch:
+        try:
+            branch_delete(chosen.branch, repo=main)
+        except (GitError, Refused) as exc:
+            if callable(say):
+                say(f"  branch {chosen.branch} kept: {exc}")
+    return main if standing_in else ""
+
+
+def removable(
+    only: str,
+    head: str,
+    head_branch: str,
+    delete_ignored: bool,
+    repo: str | os.PathLike[str] | None = None,
+    ask_forge: bool = True,
+) -> list[Verdict]:
+    """Every worktree, judging the one you stand in like any other.
+
+    `gws` keeps it, because a listing cannot step out of a directory on your
+    behalf. `gwr` is asked for one by name and does step out, so the rule
+    that protects a listing would only hide the answer here.
+    """
+    return assess(
+        R.worktrees(repo),
+        only,
+        head,
+        head_branch,
+        delete_ignored,
+        repo=repo,
+        here="",
+        ask_forge=ask_forge,
+    )
+
+
+__all__ = ["REMOVE", "Landed", "add", "move", "removable", "remove"]