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

{git_worktrees-0.2.3 → 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.3 → git_worktrees-0.3.0}/.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.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.3 → 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:

{git_worktrees-0.2.3 → 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.
 

{git_worktrees-0.2.3 → 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,47 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-worktrees
-Version: 0.2.3
+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
@@ -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.
 
@@ -283,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
@@ -310,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

{git_worktrees-0.2.3 → git_worktrees-0.3.0}/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.
 
@@ -257,9 +259,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,16 +287,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

git_worktrees-0.3.0/docs/BENCHMARK.md

@@ -0,0 +1,88 @@
+# What an invocation costs
+
+Generated. Everything else this program does is a `git` subprocess or
+a forge round trip, and both are facts about a repository and a
+network rather than about the code, so starting is the only thing
+timed here.
+
+```console
+$ uv run scripts/benchmark.py > b.json
+$ uv run scripts/benchmark.py --markdown --from b.json > docs/BENCHMARK.md
+```
+
+The JSON keeps every module `-X importtime` named. This is one view of
+it, and a question about a module missing below is a filter rather
+than another run.
+
+Measured 2026-09-13T00:01:21Z against `7f9f332`, version 0.2.3, on macOS-26.6.2-arm64-arm-64bit-Mach-O. 50 runs each, wall clock divided, after 3 discarded.
+
+|  | 3.11.13 | 3.12.14 | 3.13.15 | 3.14.7 |
+| --- | --- | --- | --- | --- |
+| the interpreter alone | 16.9 ms | 18.8 ms | 19.4 ms | 19.7 ms |
+| gw version | 27.4 ms | 30.1 ms | 29.7 ms | 40.7 ms |
+| gwh | 27.6 ms | 29.8 ms | 29.6 ms | 40.3 ms |
+| gws --help | 28.0 ms | 31.0 ms | 30.6 ms | 41.5 ms |
+| /bin/echo, for scale | 2.5 ms | 2.5 ms | 2.6 ms | 2.6 ms |
+
+Every column is a uv-managed interpreter. That is the point of `--managed-python`:
+without it uv takes whatever it finds first, and a run compares packagers rather
+than versions. Homebrew's 3.14 ships 76 extension modules as shared objects
+where the build below ships 2, and on macOS every `dlopen` pays a code-signature
+check, which was worth 8 ms of interpreter startup on its own.
+
+| how each was built | 3.11.13 | 3.12.14 | 3.13.15 | 3.14.7 |
+| --- | --- | --- | --- | --- |
+| modules linked into the executable | 99 | 95 | 97 | 101 |
+| modules `dlopen`ed from `lib-dynload` | 4 | 3 | 2 | 2 |
+
+### 3.11.13, the 8 costliest imports
+
+| module | self | cumulative |
+| --- | --- | --- |
+| `typing` | 1.4 ms | 1.4 ms |
+| `enum` | 1.0 ms | 1.0 ms |
+| `time` | 0.6 ms | 0.6 ms |
+| `ipaddress` | 0.6 ms | 0.6 ms |
+| `urllib.parse` | 0.5 ms | 1.1 ms |
+| `gettext` | 0.5 ms | 0.5 ms |
+| `argparse` | 0.5 ms | 3.2 ms |
+| `pathlib` | 0.4 ms | 1.9 ms |
+
+### 3.12.14, the 8 costliest imports
+
+| module | self | cumulative |
+| --- | --- | --- |
+| `typing` | 1.5 ms | 1.6 ms |
+| `urllib.parse` | 0.9 ms | 1.8 ms |
+| `ipaddress` | 0.8 ms | 0.8 ms |
+| `enum` | 0.8 ms | 0.8 ms |
+| `time` | 0.6 ms | 0.6 ms |
+| `argparse` | 0.5 ms | 3.0 ms |
+| `site` | 0.5 ms | 3.5 ms |
+| `nt` | 0.5 ms | 0.5 ms |
+
+### 3.13.15, the 8 costliest imports
+
+| module | self | cumulative |
+| --- | --- | --- |
+| `typing` | 1.2 ms | 1.2 ms |
+| `enum` | 0.7 ms | 0.7 ms |
+| `time` | 0.6 ms | 0.6 ms |
+| `argparse` | 0.5 ms | 3.0 ms |
+| `gettext` | 0.5 ms | 0.5 ms |
+| `pathlib._local` | 0.5 ms | 1.3 ms |
+| `site` | 0.5 ms | 3.6 ms |
+| `encodings` | 0.5 ms | 1.1 ms |
+
+### 3.14.7, the 8 costliest imports
+
+| module | self | cumulative |
+| --- | --- | --- |
+| `typing` | 1.3 ms | 1.3 ms |
+| `enum` | 0.7 ms | 0.7 ms |
+| `time` | 0.7 ms | 0.7 ms |
+| `contextlib` | 0.6 ms | 1.9 ms |
+| `site` | 0.5 ms | 4.0 ms |
+| `argparse` | 0.5 ms | 2.8 ms |
+| `_collections_abc` | 0.5 ms | 0.5 ms |
+| `encodings` | 0.5 ms | 1.2 ms |