git-worktrees 0.2.1__tar.gz → 0.3.0__tar.gz

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/.agents/skills/release/SKILL.md

@@ -43,7 +43,7 @@ rather than passing it.
 git switch --create release/v<version> --no-track origin/main
 ```
 
-Then run `/release-notes:draft <version>`, from the ReleaseTools plugin. It
+Then run `/release-notes:prepare <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,
@@ -86,15 +86,18 @@ tagged and nothing published.
 ## 4. Merge, then wait for main
 
 ```bash
-gh pr merge --rebase --delete-branch
+gh pr merge --squash --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.
+`--squash`, because the `main` ruleset requires signed commits and linear
+history: GitHub cannot sign the commits a rebase merge writes and refuses it
+with `Base branch requires signed commits`, and a merge commit is off. A
+squash is signed by GitHub's web-flow key, which is expected here and not
+something to route around. The subject becomes `Release <version> (#NN)`.
 
-The wait matters. A rebase onto a main that moved is a tree neither the
+The wait matters. A squash 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.
@@ -113,7 +116,14 @@ gh run watch "$(gh run list --workflow publish.yml --limit 1 --json databaseId -
 
 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.
+once, installs the wheel it built and uploads it to PyPI. There is no
+TestPyPI upload here; `testpypi.yml` published this commit when the merge put
+it on `main`.
+
+`release` needs that upload alone, so the GitHub release appears while
+`verify` is still installing from PyPI. A red `verify` under a green
+`publish` means the index has not caught up, not that the version is
+missing.
 
 Report the PyPI URL and the GitHub release URL when it finishes.
 

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/.github/workflows/publish.yml

@@ -4,15 +4,18 @@ name: Publish
 # 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
+#   build -> publish -> release
+#                    \-> verify
 #
 # 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.
+# There is no TestPyPI rehearsal. testpypi.yml publishes every commit on main
+# there as <version>.post<epoch> and installs it back, so the tree this tag
+# names has already proved it uploads to an index and installs from one. What
+# is left to prove before the upload PyPI cannot take back is that the wheel
+# runs, and build installs it and does that.
 #
 # No API token is stored anywhere. See docs/DEVELOPMENT.md, "Publishing a
 # version".
@@ -30,7 +33,7 @@ permissions:
 
 jobs:
   # Built once and handed to every job below, so what reaches PyPI is
-  # byte-for-byte what TestPyPI accepted.
+  # byte-for-byte what was tested and installed here.
   build:
     name: Build
     runs-on: ubuntu-latest
@@ -91,6 +94,11 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --locked
 
+      # Neither shell is on the image, and the shim tests fail rather than
+      # skip under CI, so this job needs them exactly as tests.yml does.
+      - name: Install fish and zsh
+        run: sudo apt-get update && sudo apt-get install -y fish zsh
+
       # 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
@@ -98,6 +106,17 @@ jobs:
       - name: Build
         run: uv build
 
+      # The wheel is not the tree: hatch_build.py writes _version.py into it,
+      # and one that lacks it falls back to the metadata lookup and says
+      # nothing. Installing it costs four seconds and happens before anything
+      # is uploaded anywhere.
+      - name: Install the wheel and run it
+        run: |
+          REPORTED="$(uv tool run --isolated --from dist/*.whl gw version)"
+          DECLARED="$(uv version --short)"
+          echo "the wheel reports $REPORTED, pyproject declares $DECLARED" >&2
+          [ "$REPORTED" = "$DECLARED" ]
+
       - name: Upload distributions
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
@@ -105,20 +124,18 @@ jobs:
           path: dist/
           if-no-files-found: error
 
-  publish-test:
-    name: Publish to TestPyPI
+  publish:
+    name: Publish to PyPI
     runs-on: ubuntu-latest
     needs: build
-    # Binds this job to the trusted publisher registered for `testpypi`.
-    environment: testpypi
+    # 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:
-      # 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
 
@@ -135,22 +152,24 @@ jobs:
           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
+        run: uv publish --trusted-publishing always
 
-  publish:
-    name: Publish to PyPI
+  # Uploaded and installable are two claims with two timings, so they are two
+  # jobs. An index serves what it has accepted only after a delay of its own
+  # choosing: 0.2.1 took longer than the script waited, and a release that had
+  # published correctly went red and had to be re-run by hand. This job holds
+  # the second claim, `release` needs only the first, and a red `verify` says
+  # PyPI is slow rather than that the version is not out.
+  verify:
+    name: Verify it installs from 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
+    needs: publish
     permissions:
-      id-token: write
       contents: read
     steps:
+      # The script reads the name and version from pyproject.toml through
+      # `uv version`, and installs from the index rather than from the
+      # artifact, so there is nothing to download here.
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
@@ -160,22 +179,6 @@ jobs:
           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, so the
-      # script retries the resolution rather than polling a different endpoint
-      # first: the JSON API answered for 0.2.0 while the simple index uv reads
-      # had not caught up, and the run went red on a publish that had worked.
       - name: Verify it installs from PyPI
         run: scripts/verify-publish.bash --prod
 

git_worktrees-0.3.0/.github/workflows/testpypi.yml

@@ -0,0 +1,69 @@
+name: TestPyPI
+
+# Renaming this file breaks the upload. TestPyPI'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 TestPyPI first.
+#
+# Every commit on main is published here as <version>.post<epoch>. A build made
+# after <version> shipped is a post release of it, which is what PEP 440's post
+# segment says, and it sorts above <version> and below the next patch, so the
+# newest snapshot is what TestPyPI serves.
+#
+# This is what proves the publishing path. The tree a release tag names has
+# already been uploaded and installed back from an index by the time the tag
+# exists, which is why publish.yml rehearses nothing of its own.
+#
+# The suite is not run again here. tests.yml runs it on this same commit, and a
+# snapshot a test would have caught costs one number on a test index.
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  snapshot:
+    name: Publish a snapshot
+    runs-on: ubuntu-latest
+    # Binds this job to the trusted publisher registered for `testpypi`.
+    environment: testpypi
+    permissions:
+      # Lets the job mint the OIDC token TestPyPI 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, and the script reads the version from the same file.
+      - 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
+
+      # Epoch seconds rather than the run number: a re-run repeats the number
+      # and TestPyPI refuses the duplicate, while the clock has moved on.
+      # `--frozen` writes pyproject.toml and leaves uv.lock alone, which is
+      # correct here because nothing in this job resolves dependencies.
+      - name: Number the snapshot
+        run: uv version --frozen "$(uv version --short).post$(date +%s)"
+
+      - name: Build
+        run: uv build
+
+      - 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
+
+      # Uploaded is not installable, and this is the claim the release path
+      # inherits from these runs.
+      - name: Verify it installs from TestPyPI
+        run: scripts/verify-publish.bash

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/.github/workflows/tests.yml

@@ -56,6 +56,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
 
+      # python-version makes setup-uv run `uv python install`, so each entry
+      # gets a uv-managed cpython-X.Y.Z rather than whatever the runner image
+      # ships. Packagers differ enough to matter: one that links its C
+      # extensions into the executable and one that dlopens 76 of them do not
+      # start in the same time. scripts/README.md has the measurement.
       - name: Set up uv and Python ${{ matrix.python-version }}
         uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
@@ -67,11 +72,17 @@ jobs:
         # resolving something the lock file never described.
         run: uv sync --all-extras --locked
 
+      # Neither shell is on the image. Without them the nine assertions that
+      # drive a real fish or zsh call pytest.skip, which is invisible in
+      # `pytest -q`, so the run goes green without either shim ever running.
+      - name: Install fish and zsh
+        run: sudo apt-get update && sudo apt-get install -y fish zsh
+
       # 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
+        run: git --version && fish --version && zsh --version
 
       - name: Run tests
         run: uv run --no-sync pytest tests -q

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 .mypy_cache/
 .venv/
 dist/
+
+# Written by hatch_build.py during a build.
+src/worktrees/_version.py

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/AGENTS.md

@@ -6,10 +6,20 @@ through `subprocess` so env, cwd, both streams and the exit code stay per-test.
 
 ```console
 uv sync --all-extras
+uv run --no-sync pre-commit install
 uv run --no-sync pytest tests
 uv run --no-sync pre-commit run --all-files
 ```
 
+`pre-commit run --all-files` reads `git ls-files`, so a file that is new and
+unstaged is invisible to it. Stage before running the hooks, or install them
+and let the commit do it.
+
+Read [scripts/README.md](scripts/README.md) before measuring anything. It says
+what is worth timing and what is not, and why every interpreter the benchmark
+touches comes from uv: a run that compares packagers rather than versions
+produces a number that looks like a CPython regression and is not one.
+
 ## Binaries and shell functions are not interchangeable
 
 A shell function of a given name beats a binary of that name in bash, zsh and
@@ -19,7 +29,12 @@ 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.**
+call `command <name>` and `cd` to what that prints, when that is a directory.**
+
+The last clause is not a hedge. `--json` and `--list` print what was asked for
+on the same stream a destination arrives on, and a shim that cannot tell them
+apart tries to `cd` into a JSON object. `fish -c 'gwl --json'` reaches the
+function too, so this is the agent path as much as the human one.
 
 | | changes directory | ships as |
 | --- | --- | --- |
@@ -129,7 +144,9 @@ tightly they cluster. About twenty lines, `difflib` not required.
 
 Two rules, both the shape `gwp`'s prompt already has:
 
-- One match takes it outright, with no prompt at all.
+- A query that narrows to one takes it outright, with no prompt at all. No
+  query asks however many there are, because being moved without being asked
+  is not what `gwl` with no argument means.
 - No terminal, no prompt. Refuse at exit 3 and name the flag that answers
   without one, rather than blocking on something nothing can drive.
 
@@ -238,10 +255,30 @@ 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.
 
+The two calls that reach the network, `fetch` and `remote set-head --auto`,
+take `ok=(0, 128)` for the same reason in reverse: a remote that cannot be
+reached is an answer rather than a failure. The caller reads the result, says
+so on stderr, and carries on with the refs already here, which is where
+`--no-fetch` sends it on request. It also stops asking: a failed fetch means
+the head-branch ladder is told it is offline, rather than spending a second
+round trip proving it.
+
+One `git status --porcelain --ignored=traditional` answers both questions a
+worktree is asked. It is a strict superset of plain `--porcelain`, so `dirty`
+is "a line that does not start with `!! `" and `ignored` is the rest. Asking
+both ways was 18 of an assessment's 35 calls over nine worktrees.
+
 `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.
+or `switch`, `clean -f`, a bare `push --force`, `worktree remove --force`,
+`branch -D` and an `update-ref` delete that names no full sha are refused
+absolutely. There is no flag, and `--yes` least of all.
+
+Those seven are `RULES`, a tuple, each row carrying the name `--explain`
+prints, the clause the refusal ends with, and the test. The footer `--explain`
+prints is built from it. A rule written in one place and described in another
+is a rule that goes quiet: the hand-written footer fell a rule behind the
+moment `update-ref` was added, and nothing failed.
 
 `verdicts.py` declares no mutating command. A read-only command may not call
 one: a test reads the verbose log and asserts it.

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/CHANGELOG.md

@@ -1,9 +1,14 @@
 # Changelog
 
 Newest first. Each entry says what changed for somebody running these
-commands, and the choices behind it. Dates are ISO 8601, versions follow
-[Semantic Versioning](https://semver.org/spec/v2.0.0.html), and the shape
-follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+commands, and the choices behind it. Dates are ISO 8601, released versions
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and the
+shape follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Every version below was tagged and published. The snapshots `main` sends to
+TestPyPI are neither, and they are numbered `<version>.post<epoch>`, which
+PEP 440 orders after the release it follows and SemVer does not describe at
+all. `docs/DEVELOPMENT.md` says how and why.
 
 An entry earns its place by being observable. If running a command produces
 no different result, no different output and no different exit code, it is
@@ -12,6 +17,80 @@ not in here, whatever it cost to build.
 A release closes with a `### Choices` section when a decision in it is worth
 the reader's time: what was chosen, and what the alternative failed to do.
 
+## 0.3.0 - 2026-09-20
+
+`gwl` with no query asks which worktree rather than moving you to one.
+Whenever exactly one was left it took it outright, so a repository holding
+the main checkout and one worktree moved you without a word, and running it
+twice walked you back and forth. A query that narrows to one has already said
+which and still takes it outright. Without a terminal it now refuses at exit
+3 and names `--list` and `--json`, where it used to print a path, so
+`cd $(gwl)` in a script stops working. `gwl <query>` is unchanged.
+
+`gwl --list` no longer tries to `cd` into its own listing, and `--json` no
+longer tries to `cd` into the JSON. The shell function reads what the binary
+printed and moves you there, and those two modes print on the same stream a
+destination arrives on, so every one of them ended in a failed `cd`. `gwa
+--json` was the worst: the worktree was created and then the move failed, so
+the run looked broken and was not. It reached `gwa`, `gwl`, `gwm` and `gwr`
+in both fish and zsh, and `fish -c 'gwl --json'` too, because a fish function
+wins there. **That fix lives in the shell functions, so `uv tool upgrade`
+alone does not deliver it; update the fish or zsh plugin as well.**
+
+An invocation costs about 18 ms less on Python 3.11 and about 12 ms less on
+3.14. `gw version` was 48.4 ms and is 30.5 ms on 3.11.13, and was 55.6 ms and
+is 43.1 ms on 3.14.7, measured from installed wheels on one machine. Four
+changes account for it: the command you typed imports only what it needs
+rather than every command, records are plain classes rather than dataclasses,
+the parser is built for the subcommand you asked for rather than all eleven,
+and `json` is imported only where it is printed. `difflib`, which named the
+closest command when you mistyped one, is no longer imported to start.
+
+### Choices
+
+`gwl` asks whenever no query was given, even when the repository holds one
+other worktree. Taking it outright reads as a toggle: the command moves you,
+and moves you back, and never says where. Prompting for a single option looks
+redundant until it is the difference between being shown your options and
+being sent somewhere. A query is the way to skip it, and it always was.
+
+`gwl` without a terminal exits 3, joining `gwp`, which 0.2.3 moved there for
+the same reason. A script can then tell a refusal from a typo: 2 is
+argparse's code for a usage error and 3 is nobody else's.
+
+## 0.2.3 - 2026-09-11
+
+An unreachable remote is an answer rather than a failure. Every command that
+touches the network used to exit 1 with git's own message, so the warnings
+written for the offline case never reached anybody. A failed fetch now says
+the refs are the ones already here, and the assessment carries on.
+
+Refusing to prompt exits 3 everywhere. `gwp` used to exit 2 when stdin was
+not a terminal, which is argparse's code for a usage error, so a script could
+not tell a refusal from a typo.
+
+Removing a worktree names the stash entries made on its branch. A stash
+outlives the branch while its subject goes on naming it, which is how it
+becomes unfindable.
+
+`gwr` asks the forge once, about the branch it is removing, instead of about
+every worktree: three round trips became one in a three-worktree repository.
+`--no-forge` turns it off there, as it already did for `gws` and `gwp`.
+
+`--explain` lists all seven refusals the guard enforces. The footer was
+written by hand and had been a rule behind since `update-ref` was added.
+
+An invocation costs about 15 ms less, and an assessment makes half as many
+`git status` calls.
+
+### Choices
+
+The version is written into the wheel at build time rather than read back
+through `importlib.metadata`, which cost 10 ms of a 67 ms invocation for a
+string two commands print. Deriving it from the tag with `hatch-vcs` was the
+alternative, and it inverts which of the tag and `pyproject.toml` has to
+agree with the other.
+
 ## 0.2.1 - 2026-09-11
 
 `--version` is gone from every command. `gw version`, or `gw v`, prints the

{git_worktrees-0.2.1 → git_worktrees-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-worktrees
-Version: 0.2.1
+Version: 0.3.0
 Summary: Git worktree commands that refuse to lose work.
 Project-URL: Bug reports, https://github.com/MihaiBojin/worktrees/issues/new
 Project-URL: Source, https://github.com/MihaiBojin/worktrees
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Provides-Extra: dev
+Requires-Dist: hatchling==1.28.0; extra == 'dev'
 Requires-Dist: pre-commit==4.6.1; extra == 'dev'
 Requires-Dist: pytest==9.1.1; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -147,8 +148,10 @@ autoload -Uz compinit && compinit
 
 ### What the shell code does
 
-Each function runs `command <name>`, reads the one path the binary printed and
-`cd`s there, and carries nothing else. `gws`, `gwp`, `gwnb`, `gwrot` and `gwh`
+Each function runs `command <name>` and `cd`s to what it printed, provided
+that is a directory. `--json` and `--list` print what was asked for on the
+same stream a destination arrives on, so the shim asks whether what it has is
+somewhere to go and stays put when it is not. `gws`, `gwp`, `gwnb`, `gwrot` and `gwh`
 change no directory, so they ship as console scripts alone and answer the same
 from a prompt and from a script.
 
@@ -222,6 +225,12 @@ function returns that set for both. What goes and what puts it back is printed
 before anything does, and neither `--quiet` nor `--yes` silences it. The sha in
 the restore line is full length, because that line is meant to be pasted.
 
+A stash made on a branch that is about to go is named too. `refs/stash` is
+per-repository and pins its own commits, so the entry survives the branch and
+`git stash branch <new> stash@{0}` still recovers it. What does not survive is
+the branch name in its subject, so the line says which entry is about to start
+pointing at nothing.
+
 The checkout goes through plain `git worktree remove`, so every refusal git
 makes still applies. The branch goes through `git update-ref -d`, naming the
 sha the verdict was formed against: a branch somebody committed to in between
@@ -240,7 +249,8 @@ squash-merged  /home/you/git/.worktrees/squash-merged/repo
 not a terminal, so nothing can answer for the 1 above; pass --yes to remove them
 ```
 
-That exits 2 and touches nothing. `gwp --yes --json` is what an agent runs.
+That exits 3 and touches nothing, the code every refusal uses. `gwp --yes --json`
+is what an agent runs.
 
 With nothing to remove it prints the table `gws` prints, rather than the name
 of the command that would have printed it. The reason each worktree stayed is
@@ -275,9 +285,10 @@ $ gwm parser-v2           # renames the branch and moves the checkout
 $ gwr                     # removes the one you are standing in
 ```
 
-Each prints one destination on stdout and nothing else, which is what the
-shell function reads. `gwr` prints a path **only** when you were standing in
-what it removed; empty output means stay put.
+Each prints one destination on stdout, which is what the shell function
+reads, and prints data there instead under `--json` and `--list`. `gwr` prints
+a path **only** when you were standing in what it removed; empty output, and
+output that is not a directory, both mean stay put.
 
 `gwm` is the one that is not a convenience. Renaming the directory you are
 standing in leaves the shell with a stale `$PWD` and every later command
@@ -302,16 +313,17 @@ $ gwl --list
 ```
 
 It never offers that one. Picking it is the one answer that cannot take you
-anywhere, and a picker whose single candidate is where you already are prints
-nothing at all, which reads as a broken command. So two worktrees and no query
-is not a question, and asking for the one you are in says so and stays put:
+anywhere, and asking for the one you are in says so and stays put:
 
 ```console
 $ gwl dirty          # standing in dirty-work
 already in dirty-work
 ```
 
-With more than one worth offering it asks, numbered:
+A query that narrows to one takes it outright. No query does not, even when
+the repository holds exactly one other worktree: `gwl` with no argument means
+show me the options, and being moved without being asked is not that. So it
+asks, numbered, however many there are:
 
 ```console
 $ gwl                # standing in the main checkout
@@ -422,13 +434,17 @@ print one thing each and have nothing to be quiet about, takes `--json`, `-q`,
 | --- | --- |
 | `gws` | `--branch NAME`, `--no-fetch`, `--delete-ignored`, `--no-forge` |
 | `gwp` | those four, and `-y` |
-| `gwr` | `-f`, `--delete-ignored`, `--no-fetch`, `-y` |
+| `gwr` | `-f`, `--delete-ignored`, `--no-fetch`, `--no-forge`, `-y` |
 | `gwa`, `gwnb`, `gwrot` | `--no-fetch` |
 | `gwl` | `-l` |
 | `gwm`, `gwh` | none |
 
 `gw <command> --help` prints one command's own list.
 
+A remote that cannot be reached is not fatal anywhere. The fetch fails, the
+command says so on stderr, and it answers from the refs already here, which is
+where `--no-fetch` sends it on request.
+
 Data goes to stdout and diagnostics to stderr, the prompt included, so `--json`
 is parseable in every mode. Colour is decided per stream and only for a
 terminal, so a redirect, a pipe, a non-empty `NO_COLOR` or `TERM=dumb` give the
@@ -460,12 +476,14 @@ and whatever a caller asks for:
 ```
 reset --hard      a forced checkout or switch      clean -f
 push --force      worktree remove --force          branch -D
+an update-ref delete that names no full sha
 ```
 
 The check runs on the argument list as it is about to be handed to git, so no
 code path can assemble its way past one. `gws --explain` prints every git
 command the program can issue, marking the ones that take the repository's
-shared refs and therefore run serially.
+shared refs and therefore run serially, and ends with that list of seven,
+generated from the rules rather than written out beside them.
 
 `--force-with-lease` is not `--force` and is allowed, and so is
 `update-ref -d <ref> <sha>`, which is how a branch is deleted here: against the