git-worktrees 0.1.0__tar.gz → 0.2.0__tar.gz

{git_worktrees-0.1.0 → git_worktrees-0.2.0}/.github/workflows/publish.yml

@@ -14,7 +14,8 @@ name: Publish
 # 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".
+# No API token is stored anywhere. See docs/DEVELOPMENT.md, "Publishing a
+# version".
 
 on:
   push:

{git_worktrees-0.1.0 → git_worktrees-0.2.0}/AGENTS.md

@@ -23,7 +23,7 @@ call `command <name>` and `cd` to what that prints.**
 
 | | changes directory | ships as |
 | --- | --- | --- |
-| `gws`, `gwp`, `gwnb`, `gwrot` | no | a console script, and nothing else |
+| `gws`, `gwp`, `gwnb`, `gwrot`, `gwh` | 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,
@@ -85,9 +85,16 @@ 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.
+A completion asks the CLI for its candidates rather than deriving them, and
+`--complete` is how: `gw --complete` prints every subcommand and shorthand,
+`gwl --complete` prints every worktree, both as name and description separated
+by a tab, which fish reads directly and zsh splits for `_describe`. Hidden from
+`--help`, because a person has `gwh` and `--list` for the same answers.
+
+No shell file holds a candidate or a rank. What each file does carry is its own
+command's flags, and `tests/test_completions.py` diffs those against `--help`
+in both directions for both shells: a renamed flag fails there rather than
+going quiet in a completion nobody is watching.
 
 ## The picker is Python's, and there is no fzf
 
@@ -101,9 +108,9 @@ 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
->
+  1  fix-parser     /home/you/git/.worktrees/fix-parser/repo
+  2  add-tests      /home/you/git/.worktrees/add-tests/repo
+which? [1-2, or blank to cancel]
 ```
 
 Dropping `fzf` is less code, not more. It removes the spawn, the tty rules
@@ -123,12 +130,57 @@ 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.
-- No terminal, no prompt. Refuse at exit 2 and name the flag that answers
+- No terminal, no prompt. Refuse at exit 3 and name the flag that answers
   without one, rather than blocking on something nothing can drive.
 
+Two more about what is in the list at all:
+
+- The main checkout is a destination. It is the one that is always there and
+  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.
+
 `--json` and `--list` answer the same question without any of this, and an
 agent uses those.
 
+## One row per command, under every name it answers to
+
+`_COMMANDS` in `cli.py` is the table. A row carries the function, the flags,
+the one-line description, the console script, the argument shape, the
+shorthands and whether the command changes the caller's directory. `gws`,
+`gw status`, `gw st` and `gw s` reach the same function because that row says
+so, and `gwh` prints the table rather than a second list that can disagree
+with it.
+
+`_canonical()` raises at import when two rows answer to one name. A dict
+comprehension would keep the last one and leave a command reachable under a
+name that runs a different one.
+
+A shorthand is for typing, so it is short and it is not clever: the first
+letters of the word, or the two-letter name the same job has in git and in a
+shell. `rm` and `mv` mean what they mean everywhere else.
+
+## Colour is a property of the stream, not of the program
+
+`render.py` holds both halves of it: the codes, and a table whose columns line
+up. `render.setup()` runs once per invocation and decides per stream.
+
+Padding runs on the text and painting after it. The other order counts an
+escape sequence as width, and every column under a coloured cell sits crooked
+by exactly the length of the code.
+
+stdout carries the path `cd $(gwa x)` reads and the JSON `jq` parses, so a
+redirect, a pipe, a non-empty `NO_COLOR`, or `TERM=dumb` mean the bytes go out
+as they would have without the module. `NO_COLOR=` is not a request to turn it
+off: that is the no-color.org rule, and it is why `supported` tests the value
+and not the key. `--json` is never painted at all:
+the colour is applied at the call site that formats a table, and the JSON
+paths do not pass through one.
+
 ## Every git command is one spec
 
 The spec is the command as you would type it, with `$name` where a value goes.
@@ -186,9 +238,8 @@ 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.
+`verdicts.py` declares no mutating command. A read-only command may not call
+one: a test reads the verbose log and asserts it.
 
 ## Content cannot settle a stacked branch
 

git_worktrees-0.2.0/CHANGELOG.md

@@ -0,0 +1,172 @@
+# 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/).
+
+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
+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.2.0 - 2026-09-11
+
+A squash-merged branch goes with its checkout, every removal names the
+ignored files it deletes, `gwl` finds every worktree and `gwp` says why it
+removed nothing. Every command is also reachable by a short name, output takes
+colour, and both shells complete every command.
+
+A branch the probe proved squash-merged is deleted with its worktree. It used
+to survive: the verdict came from comparing content, and the delete then went
+through `git branch -d`, which reads history and refuses exactly that case, so
+`gwp` removed the checkout and left the branch behind with git's refusal
+printed under it. The delete is now `git update-ref -d <ref> <sha>` against the
+sha the verdict was formed on, so a commit landing between the verdict and the
+removal fails it rather than going with it. `git branch -D` stays refused, and
+so does `update-ref -d` with no sha, which is the same thing spelled longer.
+
+Every removal names the ignored files it is about to delete, not just the ones
+under `--delete-ignored`. `gwr --force` used to print a worktree, remove it,
+and say nothing about the `.env` inside it; `git worktree remove` takes the
+whole directory whatever flag got it there, so `--delete-ignored` decides
+consent and never decides what is deleted.
+
+`gwr` no longer calls a finished branch unfinished. A worktree holding ignored
+files was refused with `is not finished: squash-merged, but holds 6 ignored
+path(s)`, contradicting itself in one line, and the flag it offered was
+`--force`, which keeps a branch whose work already landed and deletes those
+files anyway. It now says `is finished` and names `--delete-ignored` alone.
+
+`gwl` offers the main checkout, and never the worktree you are standing in.
+In a repository with one linked worktree, standing in it, `gwl` printed
+nothing and exited 0: the main checkout was filtered out of the candidates,
+leaving one, which the picker took outright and handed back the path you were
+already at. `gwl main` now finds the main checkout whatever branch it stands
+on, two worktrees and no query go to the other one, and asking for the one
+you are in says `already in <branch>` and stays put. `--list` shows every
+worktree and marks that one. A repository with no linked worktrees says so
+and names `gwa`, where it used to answer as though nothing were there.
+
+`gws --json` carries `ignored` and `sha` on every verdict. The count of
+ignored paths reads as a number rather than as a phrase inside `why`, and the
+sha is the commit the verdict was formed against, which is the value a caller
+would otherwise have to go and read for itself.
+
+`gwp` with nothing removable prints the verdict table. It used to print
+`nothing to remove; gws says why`, so the reason each worktree stayed cost a
+second command to read.
+
+`gwh` is the help, so nothing needs `gw --help` typed out. It joins `gwa`,
+`gwl`, `gwm`, `gwr`, `gws`, `gwp`, `gwnb`, `gwrot` and `gw` on `$PATH`, and
+`gw` still takes the same set as subcommands. `gw` with no subcommand prints
+that table too, where it used to print argparse's usage. `gw` has its own
+entry point now, so a usage error from it names `gw` rather than `worktrees`.
+
+Every subcommand answers to a shorthand as well as its name: `s` and `st` for
+`status`, `p` for `prune`, `a` for `add`, `l` and `ls` for `list`, `m` and
+`mv` for `move`, `rm` for `remove`, `nb` and `new` for `new-branch`, `rot` for
+`rotate`, `h` for `help`. One table in the CLI carries every name, so what
+`gwh` prints, what the completions offer and what `gw` accepts cannot
+disagree, and it refuses to import if two commands ever claim one name.
+
+Output is coloured, and `NO_COLOR` turns it off. The check reads the value
+rather than the key, which is the no-color.org rule: `NO_COLOR=` unsets the
+request instead of making it. A redirect or a pipe turns colour off as well,
+because `cd $(gwa x)` and `jq` read that output and neither wants escapes.
+
+Completion covers every command in fish and in zsh, ten files per shell. The
+candidates come from the CLI and never from a shell file: `gw --complete`
+prints every subcommand and shorthand, `gwl --complete` and `gwr --complete`
+print worktrees, each as a name and a description separated by a tab, which
+fish reads directly and zsh splits for `_describe`. A command added to the
+table needs no edit in either shell.
+
+`gwl` and `gwr` do not offer the same set. `gwr` cannot remove the main
+checkout, so offering it would complete to "no worktree matches"; for `gwl`
+it is the one destination always there.
+
+`gwa` says when it leaves something behind. It creates the directories before
+git is asked, so a refusal used to strand an empty one silently.
+
+The worktree picker prints destinations in full rather than abbreviating them
+to `~/git/...`. The abbreviation was not what got printed and not what you
+could paste.
+
+### Choices
+
+A branch is deleted by `update-ref -d <ref> <sha>` rather than by `branch -D`.
+Both force the delete; only one names what it expects to find, which turns a
+concurrent commit into a failure instead of a loss. The guard reads that last
+argument rather than counting the arguments: git takes `""` as "no old value"
+and deletes the branch at exit 0, so a rule checking the shape would have
+passed the one spelling that matters. `branch -d` was the
+original choice and it inverts on the case this tool exists for: it reads
+history, a squash merge leaves none, and deferring to it meant the content
+probe bought the checkout and never the branch.
+
+Completion flags live in the shell files, because that is the half that rots
+without failing: rename a flag and nothing breaks, the candidate just stops
+being offered. `test_completions.py` diffs both shells against `--help` in
+both directions rather than trusting either copy, and drives every candidate
+`gwr` offers back through `gwr` rather than comparing against a second copy
+of the filter.
+
+## 0.1.0 - 2026-09-11
+
+The first release. Eight commands for git worktrees, four of which answer a
+question and print it, and four of which land you somewhere.
+
+`gws` says which of a repository's worktrees are finished and why, in three
+verdicts. `remove` was proved finished, `keep` has a reason not to be, and
+`unknown` could not tell. It removes nothing and has no flag that could.
+
+`gwp` removes the ones `gws` marks `remove`, under the same flags, printing
+what goes and the command that puts it back before asking. `-y` skips the
+question, and a run whose stdin is not a terminal refuses rather than
+blocking.
+
+Two failures in git are why those two exist. A squash merge makes
+`git branch -d` report "not fully merged" and point at `-D`, which deletes
+anything; the probe replays the branch's tree as one commit on the merge
+base and asks `git cherry` whether that patch is already upstream. And
+`git worktree remove` deletes `.env` and `node_modules/` at exit 0 with no
+`--force` and no word about it, so ignored paths are counted and the
+worktree is kept until you pass `--delete-ignored`.
+
+Where content cannot tell, the forge is asked. A branch merged as part of a
+stack is that case: its changes reach the head branch across several
+squashes, so a diff cannot separate it from a branch with work left. A
+merged pull request settles it, cross-checked against the commits an
+upstream has not got. `--no-forge` decides from git alone.
+
+`gwa NAME` creates a worktree at `<PARENT>/.worktrees/<NAME>/<REPO>` and
+prints where it is. `gwl [QUERY]` picks one of the existing ones, taking a
+single match outright and asking when there are several. `gwm NEW` renames
+this worktree's branch and moves the checkout to match. `gwr` removes one
+whose branch is finished, and the branch with it.
+
+Those four change your shell's directory, which a binary cannot do, so each
+ships a shell function of the same name for fish and for zsh. The function
+reads the path the binary printed and does the `cd`, and carries nothing
+else.
+
+`gwnb NAME` starts a branch off the head branch as the remote has it after a
+fetch. `gwrot` starts the next branch in a series, named
+`<stem>-YYYY-MM-DD_NNN` at the first number free today. **Both are alpha and
+may go**: they start branches rather than worktrees, `origin new-branch` and
+`origin rotate` already do that, and only one of the two sets survives.
+
+Six git commands are refused wherever they appear and whatever flags are
+passed: `reset --hard`, a forced `checkout` or `switch`, `clean -f`, a bare
+`push --force`, `worktree remove --force`, and `branch -D`. A branch is
+deleted on git's own proof of merge or not at all.
+
+Every command takes `--json`, so an agent reads verdicts as data rather than
+parsing a table. Data goes to stdout and every diagnostic to stderr, the
+prompts included, so `--json` parses in every mode. `--version` reports the
+version of the installed distribution.
+
+Python 3.11 or newer, and no dependencies.