git-worktrees 0.1.0__tar.gz

git_worktrees-0.1.0/.agents/skills/release/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: release
+description: Release a version of this package to PyPI. Bumps the version on a release branch, opens and merges the pull request once its checks pass, then tags the merged commit so publish.yml uploads it. Use when the user says "release", "cut a release", "ship x.y.z", or "/release x.y.z".
+user-invocable: true
+allowed-tools: Bash(git:*), Bash(gh:*), Bash(uv:*), Bash(rt:*), Bash(scripts/*.bash:*)
+---
+
+# release
+
+Release `$ARGUMENTS` of this package. The argument is the version, with or
+without a leading `v`; strip it and use the bare `x.y.z` everywhere below.
+
+With no argument, ask which version. Do not guess one from the commits.
+
+Every step is one command. Run them in order, read what each says before
+running the next, and stop at the first failure rather than working around
+it. Nothing here is worth improvising: a release that goes wrong is on PyPI
+forever.
+
+## 1. Everything that has to be true first
+
+```bash
+git fetch --all --prune
+rt release::prechecks <version> \
+    --branch main \
+    --check-registry-url "https://pypi.org/pypi/$(uv version | cut -d' ' -f1)/<version>/json"
+```
+
+That checks the shape of the version, a clean working tree, that the tag is
+free on the remote, that the version is after the newest release tag, that
+HEAD is on main, and that PyPI does not already carry it. If it refuses, say
+what it said and stop. Do not fix a dirty tree by stashing on the user's
+behalf.
+
+`rt` is `releasetools/cli`, installed with `brew install releasetools/tap/releasetools-cli`
+or the installer in its README. Every check it runs refuses when it cannot
+prove what it was asked to prove, so a doubtful answer stops the release
+rather than passing it.
+
+## 2. The branch, the notes, and the bump
+
+```bash
+git switch --create release/v<version> --no-track origin/main
+```
+
+Then run `/release-notes:draft <version>`, from the ReleaseTools plugin. It
+rules on every commit since the previous tag, writes the body to
+`.git/RELEASE_EDITMSG`, and puts the entry in `CHANGELOG.md` under
+`## <version> - <date>`. It shows the draft and waits before its last step,
+so the user changes it there.
+
+Do not write that entry by hand and do not skip it: `publish.yml` reads the
+section back out for the GitHub release, and `build` refuses a tag whose
+version has no section.
+
+```bash
+uv version <version>
+git commit --all --message "Release <version>"
+git push --set-upstream origin refs/heads/release/v<version>
+```
+
+`uv version` rewrites `pyproject.toml` and re-locks, so the commit carries
+those two files and `CHANGELOG.md`. Check that with `git show --stat`
+before pushing: a commit
+missing `uv.lock` fails `uv sync --locked` in CI, and it fails after the
+merge rather than before it.
+
+Branch from `origin/main` rather than from `main`, so a stale local copy
+cannot become the release.
+
+## 3. The pull request, and its checks
+
+```bash
+gh pr create --base main --title "Release <version>" --body "..."
+gh pr checks --watch --fail-fast
+```
+
+The body is the changelog entry just written. It is already the summary,
+already reviewed by the reader, and writing a second one invites the two to
+disagree.
+
+`--watch` blocks. When it reports a failure, report which check failed and
+its URL, and stop. The branch and the pull request stay; nothing has been
+tagged and nothing published.
+
+## 4. Merge, then wait for main
+
+```bash
+gh pr merge --rebase --delete-branch
+git switch main && git pull --ff-only
+rt github::await_workflow "$(git rev-parse HEAD)" tests.yml
+```
+
+`--rebase` keeps the commit message rather than replacing it with the pull
+request title.
+
+The wait matters. A rebase onto a main that moved is a tree neither the
+branch nor main has tested, and the tag must only ever land on a commit
+already proved green. `github::await_workflow` blocks until `tests.yml` finishes
+on that commit and exits non-zero if it failed.
+
+If it failed: `main` now carries the version bump and no release exists. Say
+so plainly. The fix is another pull request, and then this skill again at the
+same version, since no tag was created.
+
+## 5. Tag, which is what publishes
+
+```bash
+git tag --annotate v<version> --message "v<version>"
+git push origin refs/tags/v<version>
+gh run watch "$(gh run list --workflow publish.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status
+```
+
+Pushing the tag is the release. `publish.yml` re-checks the tag against
+`pyproject.toml`, that the commit is on `main`, and the tests, then builds
+once and uploads to TestPyPI before PyPI.
+
+Report the PyPI URL and the GitHub release URL when it finishes.
+
+## What this never does
+
+Move a tag. A tag names one commit forever; a version that needs a second
+attempt gets the next number. If `publish.yml` fails *after* the PyPI upload,
+in `verify` or `release`, re-run it with
+`gh workflow run publish.yml --ref v<version>` rather than re-tagging.
+
+Delete a release branch that has not merged, stash the user's work, force
+anything, or retry a failed check by re-running it in the hope it passes.

git_worktrees-0.1.0/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "release-notes@release-tools": true
+  }
+}

git_worktrees-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,202 @@
+name: Publish
+
+# Renaming this file breaks publishing. PyPI's Trusted Publishing matches a
+# request against the repository, this workflow's FILENAME and the environment,
+# so a rename means re-registering the publisher on PyPI first.
+#
+#   build -> publish-test -> publish -> release
+#
+# Nothing here creates a tag. A release is a version bump merged into main and
+# then tagged by hand, so the irreversible step is the last one and everything
+# before it is a normal reviewed change.
+#
+# TestPyPI gates the real upload deliberately: a PyPI upload cannot be undone
+# or replaced, so if the rehearsal fails there is nothing to pin against and
+# the run stops there.
+#
+# No API token is stored anywhere. See README, "Publishing a version".
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  # To re-run a release whose publish failed. Run it against a tag ref, not a
+  # branch: every guard below reads the tag at HEAD.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Built once and handed to every job below, so what reaches PyPI is
+  # byte-for-byte what TestPyPI accepted.
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Reading another workflow's runs. Without it the tests guard below
+      # gets 403 from /actions/workflows/tests.yml and refuses every release,
+      # which is the safe direction and still a release that cannot happen.
+      actions: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          # A tag-ref checkout fetches only the tag it is checking out, and
+          # check-tag-version.bash asks for every tag at HEAD.
+          fetch-tags: true
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install the release tools
+        uses: releasetools/cli@v0
+
+      # Four guards, cheapest first. The tag has to name a version the
+      # repository actually carries, that version has to have a changelog
+      # entry, the commit has to be one main took, and its tests have to have
+      # passed already. All of them here in build, because the release job
+      # runs after the PyPI upload and a refusal there would be too late.
+      - name: Check the tag matches the project version
+        run: rt git::assert_tag_version "$(uv version --short)"
+
+      - name: Check the changelog has an entry for it
+        run: rt changelog::section "${GITHUB_REF_NAME#v}" >/dev/null
+
+      # github:: rather than git::, because this checkout is shallow and
+      # merge-base answers from the history it has: on a truncated one it
+      # reports a commit main genuinely took as not on main, and refuses a
+      # release that should go ahead. The API needs no local history.
+      - name: Check the commit is on main
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: rt github::assert_on_branch main
+
+      - name: Wait for the tests on this commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: rt github::await_workflow "$GITHUB_SHA" tests.yml
+
+      - name: Install dependencies
+        run: uv sync --all-extras --locked
+
+      # The tag is the last chance to catch a regression, and it costs 20s.
+      - name: Run tests
+        run: uv run --no-sync pytest tests -q
+
+      - name: Build
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-test:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    # Binds this job to the trusted publisher registered for `testpypi`.
+    environment: testpypi
+    permissions:
+      # Lets the job mint the OIDC token PyPI exchanges for a short-lived,
+      # scoped credential. Without it uv has nothing to present.
+      id-token: write
+      contents: read
+    steps:
+      # `--index testpypi` resolves that name from [[tool.uv.index]] in
+      # pyproject.toml, which is not part of the built artifact.
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        # `always` rather than the default `automatic`: fail loudly if OIDC is
+        # unavailable instead of quietly looking for a token.
+        run: uv publish --index testpypi --trusted-publishing always
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: publish-test
+    # Binds this job to the trusted publisher registered for `pypi`. Add a
+    # required reviewer on this environment for a manual gate before anything
+    # reaches the real index.
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install the release tools
+        uses: releasetools/cli@v0
+
+      - name: Publish
+        run: uv publish --trusted-publishing always
+
+      # An index serves what it has just accepted only after a delay, and a fixed
+      # sleep either wastes time or fails a publish that worked. This backs off
+      # across about 7.75 minutes and stops as soon as the version is there.
+      - name: Wait for the PyPI index to catch up
+        run: |
+          rt net::await_url "https://pypi.org/pypi/$(uv version | tr ' ' '/')/json"
+
+      - name: Verify it installs from PyPI
+        run: scripts/verify-publish.bash --prod
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: publish
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Install the release tools
+        uses: releasetools/cli@v0
+
+      # What was written for this version, not a list of pull request titles.
+      # build already proved the section exists, before anything was published.
+      - name: Read the changelog entry
+        run: rt changelog::section "${GITHUB_REF_NAME#v}" >RELEASE_NOTES.md
+
+      - name: Release
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3
+        with:
+          body_path: RELEASE_NOTES.md
+          make_latest: true

git_worktrees-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,77 @@
+name: Tests
+
+on:
+  # Every pull request, not only those into main: a stacked branch targets the
+  # one below it, and a filter on `main` leaves that pull request with no
+  # checks at all.
+  pull_request:
+  push:
+    branches:
+      - main
+
+# Least privilege: this reads the repository and nothing else. Without a
+# default, GITHUB_TOKEN's scopes come from the repository setting, which is
+# invisible from here.
+permissions:
+  contents: read
+
+# A second push to a pull request cancels the run still going for the first.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up uv and Python
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras --locked
+
+      # ruff and mypy both run from here, so what CI checks and what a commit
+      # checks are the same versions pinned in the same file.
+      - name: Run pre-commit
+        run: uv run --no-sync pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      # One version failing is a fact about that version, so let the others
+      # finish and say which.
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Set up uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        # --locked fails the run on a stale uv.lock, rather than quietly
+        # resolving something the lock file never described.
+        run: uv sync --all-extras --locked
+
+      # The suite drives real git: it builds repositories, adds worktrees and
+      # removes them. Recording the version makes a failure that is git's
+      # rather than ours readable from the log alone.
+      - name: Record the git version
+        run: git --version
+
+      - name: Run tests
+        run: uv run --no-sync pytest tests -q

git_worktrees-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+dist/

git_worktrees-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      # keep-sorted start
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-docstring-first
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      # keep-sorted end
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.3.1
+    hooks:
+      - id: mypy
+        # The suite imports the package and pytest; without these mypy reads
+        # every one of them as Any and reports nothing about how they are used.
+        additional_dependencies: ["pytest==9.1.1"]
+
+  - repo: https://github.com/google/keep-sorted
+    rev: v0.10.0
+    hooks:
+      - id: keep-sorted

git_worktrees-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

git_worktrees-0.1.0/AGENTS.md

@@ -0,0 +1,230 @@
+# Working in this repository
+
+A Python CLI for git worktrees. `pyproject.toml` declares one console script
+per command; `src/worktrees/` holds them; `tests/` drives the entry points
+through `subprocess` so env, cwd, both streams and the exit code stay per-test.
+
+```console
+uv sync --all-extras
+uv run --no-sync pytest tests
+uv run --no-sync pre-commit run --all-files
+```
+
+## Binaries and shell functions are not interchangeable
+
+A shell function of a given name beats a binary of that name in bash, zsh and
+fish, and in fish it beats it in `fish -c` too, where the function is autoloaded
+from `functions/`. So a command that exists as both runs different code from a
+prompt and from a script unless the function is a pure adapter.
+
+The rule: **a function exists only for a command that must change the caller's
+directory, it carries the same name as the binary, and its body does nothing but
+call `command <name>` and `cd` to what that prints.**
+
+| | changes directory | ships as |
+| --- | --- | --- |
+| `gws`, `gwp`, `gwnb`, `gwrot` | no | a console script, and nothing else |
+| a command that lands you somewhere | yes | a console script, plus a function of the same name |
+
+A binary cannot `cd` its caller. That is the only thing shell code is here for,
+and any logic that reaches a shell file is logic a script cannot call.
+
+Two traps a shim has to handle, both measured:
+
+- fish splits command substitution on newlines, so a path containing one
+  arrives as two elements. `(command gwa $argv | string collect)` keeps it
+  whole. bash and zsh strip only trailing newlines, so `"$(gwa)"` is already
+  correct there.
+- that pipeline's `$status` belongs to `string collect`, which returns 1
+  whenever it collected nothing, which is the failure case. The command's own
+  code is `$pipestatus[1]`.
+
+```fish
+function gwa --wraps gwa
+    set -l dest (command gwa $argv | string collect)
+    set -l code $pipestatus[1]
+    test $code -eq 0; or return $code
+    test -n "$dest"; or return 0
+    cd -- $dest
+end
+```
+
+`command` is what stops the function calling itself, in all three shells.
+
+## Two commands are alpha
+
+`gwnb` and `gwrot` start branches, not worktrees. `origin new-branch` and
+`origin rotate` do the same job, only one of the two sets survives, and
+nothing has decided which. So they match `origin` rather than improve on it:
+the name format, the stem-stripping and the remote-aware collision check are
+copied, and a difference between them is a decision somebody has to make
+later. Say so wherever they are documented.
+
+Exit codes are the one deliberate divergence. `origin` has a single non-zero
+code and draws no line between a usage error and a runtime one; this CLI
+keeps argparse's 2 for a usage error.
+
+## Where shell code goes
+
+Fisher copies `functions/`, `completions/` and `conf.d/` from the repository
+root and nothing else. Antidote takes a `path:` into the repository and wants a
+`<name>.plugin.zsh` there. So the two live in different places:
+
+```
+functions/gwa.fish                   fish, installed by Fisher
+completions/gwa.fish
+zsh/plugins/worktrees/worktrees.plugin.zsh    zsh, installed by Antidote
+zsh/plugins/worktrees/functions/gwa
+zsh/plugins/worktrees/completions/_gwa
+```
+
+Neither manager puts a binary on `$PATH`. The console scripts arrive through
+`uv tool install` from the published package, which is a separate step.
+
+Nothing installs this from a checkout on the user's disk. It is consumed as a
+third-party plugin and a third-party tool, so anything that assumes a local
+clone at a known path is wrong here.
+
+A completion asks the CLI for its candidates rather than deriving them. The
+ranking is tested in Python; a shell file that reimplements it is a second
+answer to the same question.
+
+## The picker is Python's, and there is no fzf
+
+Building the candidate list, matching a query against it, ranking, deciding
+what each row shows, reading the answer back: all of it in the CLI. No shell
+file holds a candidate, a format string or a rank, and nothing spawns an
+external picker.
+
+The set is small. Across the repositories this was written for, the largest
+number of linked worktrees in one is four. A fuzzy finder is the wrong
+instrument at that size, and a numbered prompt reads faster:
+
+```
+1  fix-parser     ~/git/.worktrees/fix-parser/repo
+2  add-tests      ~/git/.worktrees/add-tests/repo
+>
+```
+
+Dropping `fzf` is less code, not more. It removes the spawn, the tty rules
+around it, and the fallback branch a machine without `fzf` would otherwise
+need.
+
+Matching is substring first, then subsequence, which is the one idea worth
+taking from `fzf`: the query's letters appearing in order, ranked by how
+tightly they cluster. About twenty lines, `difflib` not required.
+
+```
+'parse'  -> ['fix-parser']
+'tst'    -> ['add-tests', 'try-something']
+'ruff'   -> ['renovate/ruff-0.x']
+```
+
+Two rules, both the shape `gwp`'s prompt already has:
+
+- One match takes it outright, with no prompt at all.
+- No terminal, no prompt. Refuse at exit 2 and name the flag that answers
+  without one, rather than blocking on something nothing can drive.
+
+`--json` and `--list` answer the same question without any of this, and an
+agent uses those.
+
+## Every git command is one spec
+
+The spec is the command as you would type it, with `$name` where a value goes.
+The module reads as the list of commands the program can run, and `--explain`
+prints the specs themselves.
+
+```python
+@git("merge-base --is-ancestor $ref $head", ok=(0, 1))
+def is_ancestor(ref, head): ...
+
+
+@git("--no-optional-locks status --porcelain --ignored=traditional")
+def ignored_paths(): ...
+
+
+@git("commit-tree $tree -p $parent -m _", env=_SYNTHETIC, ok=(0, 128))
+def commit_tree(tree, parent): ...
+```
+
+`shlex.split` runs once, at decoration time, on the literal spec. Only then is
+each token scanned for a placeholder. That ordering is the whole safety
+property: the splitting is over before any value is seen, so a branch named
+`$(id)`, `a"b` or `has space` lands as exactly one argv element. git accepts
+the first two as branch names, and there is a test that creates them.
+
+`$` rather than `{}`, because git's revision syntax is full of braces:
+`^{tree}`, `^{commit}` and `@{upstream}` pass through untouched. `$$` is a
+literal `$`, and so is a `$` with no name after it.
+
+Three ways to place a value: `$name` anywhere, including inside a token so
+`--format=$fmt` stays one element; `$*name` splats a list at that position;
+and anything the body returns is appended as a tail, for arguments with no
+fixed place. Names bind from `inspect.signature`, so there is no second
+mapping to keep in step, and a spec naming a parameter the function does not
+have raises `NameError` at import.
+
+The form catches its own bugs. `-C $path status --porcelain
+--no-optional-locks` is wrong, because `--no-optional-locks` is a git global
+and belongs before the subcommand. That is visible in a spec and invisible in
+a tuple.
+
+A command's name says what the caller gets, echoing the git command where the
+two can agree. `worktree_list`, `worktree_prune` and `worktree_remove` read as
+the subcommands they are; `is_ancestor` beats `merge_base`, because
+`merge-base --is-ancestor` answers a yes/no question and that answer is what
+the caller wants.
+
+A spec with `ok=` wide enough to swallow an error is a spec that has to be
+tested on what it returns rather than on its exit code. `upstream_of` takes
+`ok=(0, 1, 128)`, so a typo in one of its flags exits 128, reads as "no
+upstream", and turns every branch into `unknown` with nothing failing.
+
+`guard()` runs on the resolved argv inside the wrapper, not at declaration, so
+no call site can assemble its way past it. `reset --hard`, a forced `checkout`
+or `switch`, `clean -f`, a bare `push --force`, `worktree remove --force` and
+`branch -D` are refused absolutely. There is no flag, and `--yes` least of all.
+
+`verdicts.py` declares no mutating command. `prune.py` declares the six that
+mutate. A read-only command may not call one: a test reads the verbose log and
+asserts it.
+
+## Content cannot settle a stacked branch
+
+`merged_reason` answers by content: an ancestor, or a patch already upstream.
+That works for a branch squashed whole into one commit and fails for one
+merged as part of a stack, where the changes arrive across several squashes
+and the branch keeps an intermediate state the head branch edited further.
+
+Measured on this repository's own stack: `rotate` changed `README.md` by
++54/-5 from the merge base and the head branch by +96/-6 over the same
+regions. `git merge-tree` reports a conflict, and a diff cannot tell that
+from real work left over. There is no content probe that answers this.
+
+So the forge answers it, asked last because it costs a round trip and only
+where git already failed. A merged request is cross-checked against
+`unpushed_count`: it speaks for what reached it, never for commits nobody
+pushed, and no upstream at all stays `unknown` rather than becoming zero.
+`--no-forge` keeps a run offline.
+
+## Three verdicts, and the third is not a softer second
+
+`remove` was proved finished, `keep` has a reason not to be, and `unknown` could
+not tell. "No upstream, so nothing says whether this was pushed" is a different
+fact from "not merged", and printing them the same way invites somebody to act
+on the wrong one. `prune.removable()` returns the `remove` set and both commands
+call it, so what one prints and the other removes cannot drift.
+
+## Reproduce a failure before asserting its fix
+
+Two holes in git are the reason this exists: a squash merge inverts
+`git branch -d`, and `git worktree remove` deletes ignored files at exit 0
+without a word. Each has a test that reproduces the raw git behaviour and a
+test that asserts the fix. A suite that only asserts the fix passes on unfixed
+code forever.
+
+The fixture needs no global git config, no signing key, no forge and no
+network. `GIT_CONFIG_GLOBAL` carries that: without it git still reads
+`$HOME/.gitconfig`, and setting `HOME` alone still leaves
+`$XDG_CONFIG_HOME/git/config`.