git-worktrees 0.2.3__tar.gz → 0.3.1__tar.gz

{git_worktrees-0.2.3 → git_worktrees-0.3.1}/.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.3 → git_worktrees-0.3.1}/.github/workflows/publish.yml

@@ -4,16 +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
-#                                     \-> verify
+#   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".
@@ -31,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
@@ -104,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:
@@ -111,44 +124,10 @@ jobs:
           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
+    needs: build
     # 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.

git_worktrees-0.3.1/.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.3 → git_worktrees-0.3.1}/.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:

{git_worktrees-0.2.3 → git_worktrees-0.3.1}/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.
 
@@ -139,10 +156,14 @@ Two more about what is in the list at all:
   the one a finished branch leaves you in, so leaving it out leaves out the
   only answer that is always right. `main` finds it whatever branch it stands
   on, because its label carries the word, once.
-- The worktree you are standing in is listed and never offered. Picking it is
-  the one answer that takes you nowhere, and a picker whose single candidate
-  is where you already are prints nothing at all, which reads as a broken
-  command.
+- The worktree you are standing in is shown and never offered. It carries a
+  `*` rather than a number, because picking it is the one answer that takes
+  you nowhere. Leaving it out of the list entirely is worse: the list then
+  shows fewer rows than `git worktree list` does, and reads as though
+  something went missing rather than as where you already are. The main
+  checkout is in `gws` and `gwp` for the same reason, kept and never
+  proposed, and out of `gwr`'s candidates because `git worktree remove`
+  refuses it whatever flag it is given.
 
 `--json` and `--list` answer the same question without any of this, and an
 agent uses those.

{git_worktrees-0.2.3 → git_worktrees-0.3.1}/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,79 @@ 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.1 - 2026-09-20
+
+`gws` and `gwp` list the main checkout, and `gwl`'s picker shows the
+worktree you are standing in. Both listings used to leave those rows out, so
+a repository with the main checkout and one worktree showed one row where
+`git worktree list` shows two, which reads as though something went missing
+rather than as where you already are.
+
+The main checkout is `keep`, with `it is the main checkout, and never
+removable`. Nothing proposes it, and `git worktree remove` answers
+`fatal: '<path>' is a main working tree` whatever flag it is given, so `gwr`
+still does not offer it.
+
+The one you are standing in carries a `*` rather than a number:
+
+```
+  *  cleanup                           /home/you/git/.worktrees/cleanup/repo
+  1  docs-ship-with-the-change (main)  /home/you/git/repo
+which? [1-1, or blank to cancel]
+```
+
+Two things move with those rows. The counts include the main checkout, so a
+repository with one linked worktree reads `1 removable, 1 kept, 0 unclear`
+where it read `1 removable, 0 kept, 0 unclear`, and `gws --json` and
+`gwp --json` carry the extra verdict. A caller filtering on
+`verdict == "remove"` is unaffected; one reading `verdicts[0]` gets the main
+checkout now.
+
+`no worktrees besides the main checkout` is on stderr rather than stdout, and
+says `; gwa NAME makes one`. The table is always on stdout now, so stdout is
+never that sentence instead.
+
+## 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

{git_worktrees-0.2.3 → git_worktrees-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-worktrees
-Version: 0.2.3
+Version: 0.3.1
 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
@@ -148,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.
 
@@ -166,17 +168,21 @@ separate.
 ```console
 $ gws
 VERDICT  BRANCH         WHY                                                                                PATH
+keep     main           it is the main checkout, and never removable                                       /home/you/git/repo
 keep     dirty-work     it has uncommitted changes                                                         /home/you/git/.worktrees/dirty-work/repo
 keep     holds-secrets  merged, but holds 2 ignored path(s); pass --delete-ignored                         /home/you/git/.worktrees/holds-secrets/repo
 unknown  never-pushed   not merged into origin/main, and no upstream says whether its commits were pushed  /home/you/git/.worktrees/never-pushed/repo
 remove   squash-merged  squash-merged                                                                      /home/you/git/.worktrees/squash-merged/repo
 
-1 removable, 2 kept, 1 unclear
+1 removable, 3 kept, 1 unclear
 unclear, and gwp does not touch these: never-pushed
 gwp removes the 1 marked removable
 ```
 
-Rows come in `git worktree list` order. Paths are absolute wherever this
+Rows come in `git worktree list` order, the main checkout first. It is there
+so the table shows what `git worktree list` shows; nothing proposes it, and
+`git worktree remove` answers `fatal: '<path>' is a main working tree`
+whatever flag it is given. Paths are absolute wherever this
 prints one, so a row can be pasted into the next command. The table and the
 count are on stdout; the two lines after them are on stderr.
 
@@ -283,9 +289,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
@@ -310,25 +317,31 @@ $ 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
-  1  dirty-work     /home/you/git/.worktrees/dirty-work/repo
-  2  holds-secrets  /home/you/git/.worktrees/holds-secrets/repo
-  3  never-pushed   /home/you/git/.worktrees/never-pushed/repo
+$ gwl                # standing in never-pushed
+  *  never-pushed    /home/you/git/.worktrees/never-pushed/repo
+  1  main            /home/you/git/repo
+  2  dirty-work      /home/you/git/.worktrees/dirty-work/repo
+  3  holds-secrets   /home/you/git/.worktrees/holds-secrets/repo
 which? [1-3, or blank to cancel]
 ```
 
+The one you are standing in is marked `*` and carries no number. It is where
+you are rather than somewhere to go, and a list without it shows three rows
+where `git worktree list` shows four.
+
 Matching is substring first and then subsequence, so `tst` finds `add-tests`,
 and a substring hit always outranks a loose one. Without a terminal `gwl`
 refuses at exit 3 and names `--list` and `--json`.

{git_worktrees-0.2.3 → git_worktrees-0.3.1}/README.md

@@ -122,8 +122,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.
 
@@ -140,17 +142,21 @@ separate.
 ```console
 $ gws
 VERDICT  BRANCH         WHY                                                                                PATH
+keep     main           it is the main checkout, and never removable                                       /home/you/git/repo
 keep     dirty-work     it has uncommitted changes                                                         /home/you/git/.worktrees/dirty-work/repo
 keep     holds-secrets  merged, but holds 2 ignored path(s); pass --delete-ignored                         /home/you/git/.worktrees/holds-secrets/repo
 unknown  never-pushed   not merged into origin/main, and no upstream says whether its commits were pushed  /home/you/git/.worktrees/never-pushed/repo
 remove   squash-merged  squash-merged                                                                      /home/you/git/.worktrees/squash-merged/repo
 
-1 removable, 2 kept, 1 unclear
+1 removable, 3 kept, 1 unclear
 unclear, and gwp does not touch these: never-pushed
 gwp removes the 1 marked removable
 ```
 
-Rows come in `git worktree list` order. Paths are absolute wherever this
+Rows come in `git worktree list` order, the main checkout first. It is there
+so the table shows what `git worktree list` shows; nothing proposes it, and
+`git worktree remove` answers `fatal: '<path>' is a main working tree`
+whatever flag it is given. Paths are absolute wherever this
 prints one, so a row can be pasted into the next command. The table and the
 count are on stdout; the two lines after them are on stderr.
 
@@ -257,9 +263,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
@@ -284,25 +291,31 @@ $ 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
-  1  dirty-work     /home/you/git/.worktrees/dirty-work/repo
-  2  holds-secrets  /home/you/git/.worktrees/holds-secrets/repo
-  3  never-pushed   /home/you/git/.worktrees/never-pushed/repo
+$ gwl                # standing in never-pushed
+  *  never-pushed    /home/you/git/.worktrees/never-pushed/repo
+  1  main            /home/you/git/repo
+  2  dirty-work      /home/you/git/.worktrees/dirty-work/repo
+  3  holds-secrets   /home/you/git/.worktrees/holds-secrets/repo
 which? [1-3, or blank to cancel]
 ```
 
+The one you are standing in is marked `*` and carries no number. It is where
+you are rather than somewhere to go, and a list without it shows three rows
+where `git worktree list` shows four.
+
 Matching is substring first and then subsequence, so `tst` finds `add-tests`,
 and a substring hit always outranks a loose one. Without a terminal `gwl`
 refuses at exit 3 and names `--list` and `--json`.