git-worktrees 0.4.3__tar.gz → 0.5.0__tar.gz

{git_worktrees-0.4.3 → git_worktrees-0.5.0}/AGENTS.md

@@ -29,16 +29,18 @@ 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, when that is a directory.**
+call `command <name>` and `cd` to what that prints, when that is a directory,
+and print it otherwise.**
 
 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
+on the same stream a destination arrives on. A shim that cannot tell them
+apart tries to `cd` into a JSON object, and one that only refuses to prints
+nothing at all. `fish -c 'gwl --json'` reaches the
 function too, so this is the agent path as much as the human one.
 
 | | changes directory | ships as |
 | --- | --- | --- |
-| `gws`, `gwp`, `gwnb`, `gwrot`, `gwh` | no | a console script, and nothing else |
+| `gws`, `gwp`, `gwbs`, `gwbd`, `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,
@@ -60,12 +62,19 @@ function gwa --wraps gwa
     set -l code $pipestatus[1]
     test $code -eq 0; or return $code
     test -n "$dest"; or return 0
+    test -d "$dest"; or begin; printf '%s\n' $dest; return 0; end
     cd -- $dest
 end
 ```
 
 `command` is what stops the function calling itself, in all three shells.
 
+One other kind of function exists: a shortcut, a banged name that calls a shim
+with its flags fixed and does nothing else. `gwr!` is `gwr --delete-ignored`.
+It calls the `gwr` function rather than `command gwr`, so the caller still
+lands where the binary says, and it has no console script of its own.
+`SHORTCUTS` in `tests/test_shims.py` lists them and holds each to one line.
+
 ## Two commands are alpha
 
 `gwnb` and `gwrot` start branches, not worktrees. `origin new-branch` and
@@ -120,17 +129,34 @@ external picker.
 
 The set is small. Across the repositories this was written for, the largest
 number of linked worktrees in one is four. A fuzzy finder is the wrong
-instrument at that size, and a numbered prompt reads faster:
+instrument at that size, and a list moved through with the arrow keys reads
+faster:
 
 ```
-  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]
+  #  WORKTREE    BRANCH      PATH
+> 1  fix-parser  fix-parser  /home/you/git/.worktrees/fix-parser/repo
+  2  add-tests   add-tests   /home/you/git/.worktrees/add-tests/repo
+which? [up/down and enter, 1-2, or esc to cancel]
 ```
 
-Dropping `fzf` is less code, not more. It removes the spawn, the tty rules
-around it, and the fallback branch a machine without `fzf` would otherwise
-need.
+Up and down move the highlight and wrap, enter takes it, a digit takes that
+row outright, and esc or ctrl-d cancels. The terminal goes into cbreak mode
+through the stdlib's `termios`, so ctrl-c still raises `KeyboardInterrupt`.
+Both switches use `TCSANOW`: `TCSAFLUSH` discards keys typed before the list
+appears, and `TCSADRAIN` blocks on an echo queue nothing reads, which is how
+the pty tests hang.
+
+The list is redrawn in place when stderr is a terminal that can move its
+cursor. On `TERM=dumb`, or a stderr that is not a terminal, it is printed
+once and each move prints the row it lands on, so nothing writes a cursor
+code where it would show up as text.
+
+A query that is exactly one worktree's branch or path is that worktree
+alone. `gwr one` beside `one-more` is not a question, and neither is
+`gwr "$(gwl two)"`.
+
+Dropping `fzf` is less code, not more. It removes the spawn and the fallback
+branch a machine without `fzf` would otherwise need.
 
 Matching is substring first, then subsequence, which is the one idea worth
 taking from `fzf`: the query's letters appearing in order, ranked by how
@@ -156,21 +182,27 @@ 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 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.
+- In `gwl`, a linked worktree you are standing in is shown and never
+  offered. It carries a `*` rather than a number and the highlight skips it,
+  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 offered even
+  from inside it, with a `*` after its name, since from a subdirectory it is
+  the way back to the top.
+- In `gwr`, the main checkout is shown dimmed and unnumbered, because `git
+  worktree remove` refuses it whatever flag it is given, and the highlight
+  starts on the worktree you are standing in. `gws` and `gwp` keep the main
+  checkout in their lists for the same reason, and never propose it.
 
 `--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,
+`_COMMANDS` in `cli.py` holds the top-level commands; `_BRANCH_COMMANDS`
+holds `branch status` and `branch delete`. `command_rows()` lists the
+executable commands for help and completion checks. 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
@@ -203,9 +235,40 @@ 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.
+and not the key. `--json` and `gwl --list` are never painted at all, even
+on a terminal: both are what a script reads. The colour is applied at the
+call site that formats a table, and neither path passes a code to one.
+
+`progress.py` draws a spinner on stderr and one line saying what is being
+checked, while `gws`, `gwp` and `gwr` fetch and judge. It runs only when
+stderr is a terminal that can clear a line, and never under `-q` or `-v`,
+since the verbose log writes to the line it redraws. Anything else printed on
+stderr while it spins goes through `progress.line`, which clears the spinner
+first.
+
+## A recent fetch, and a forge answer that cannot change, are reused
+
+The README's "What is reused, and for how long" table lists every case and
+its lifetime. It is the one copy: the constants are `cli._FRESH`,
+`forge._IDLE_FOR` and `forge._PUSHED_FOR`, and a change to one changes that
+table in the same commit.
+
+The fetch is most of what an assessment costs: about 1.1 s of a 1.9 s `gws`
+here, 750 ms of it the SSH handshake. `_should_fetch` decides for all eight
+commands that fetch. FETCH_HEAD is written per worktree, so
+`repo.fetched_at` reads every copy.
+
+An open request is reused only when it cannot merge until its author pushes;
+`forge._idle` holds that rule. Anything that could merge it on its own, or
+soon, means asking every time. No request on a pushed branch lasts a minute
+because a push is how a request gets opened, and from here it is usually
+the next step. A forge that fails to answer is never kept: `_ask` returns a
+`NONE` request for an empty answer and None for no answer, and only the
+first is cached.
+
+The per-worktree checks run on eight threads. Each is independent, and the
+time goes waiting on git and on `gh`, one round trip per branch git cannot
+settle.
 
 ## Every git command is one spec
 
@@ -289,6 +352,18 @@ one: a test reads the verbose log and asserts it.
 
 ## Content cannot settle a stacked branch
 
+Branch assessment is documented in `docs/commands/branch-status.md`, and
+deletion in `docs/commands/branch-delete.md`. `gwbs` assesses local refs,
+including branches without worktrees. `gwbd` rechecks its verdicts after
+confirmation and deletes refs with the full expected SHA and `--no-deref`.
+
+The branch content check compares every path changed from the merge base to
+the tip with the current head tree, including modes and deletions. It can
+prove a re-imported change even when the head branch has unrelated edits.
+Forge evidence must match the source tip, source repository, and target
+branch, with a merge commit contained in the head branch. A closed unmerged
+request is never proof. These branch checks do not change worktree verdicts.
+
 `merged_reason` answers by content: an ancestor, or a patch already upstream.
 That works for a branch squashed whole into one commit and fails for one
 merged as part of a stack, where the changes arrive across several squashes

{git_worktrees-0.4.3 → git_worktrees-0.5.0}/CHANGELOG.md

@@ -17,6 +17,41 @@ 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.5.0 - 2026-09-29
+
+### Added
+
+Local branches can be assessed with `worktrees branch status` (`gwbs`)
+and deleted with `worktrees branch delete` (`gwbd`). Deletion accepts
+exact names, offers a selector when no names are supplied, and supports
+`--all` and `--dry-run`. A branch qualifies through Git history, matching
+changed paths, or a merged GitHub PR or GitLab MR tied to its exact tip.
+The command protects checked-out branches, rechecks refs before deletion,
+and prints the command to restore each branch.
+
+`gwr!` runs `gwr --delete-ignored` in fish and zsh, permitting removal of
+ignored files while retaining the command's checks and directory change.
+Update the fish or zsh plugin to install this shortcut.
+
+### Changed
+
+`gwl` and `gwr` pick with the arrow keys from a table of worktree, branch and
+path: enter takes the highlighted row, a digit takes that row, and esc
+cancels. `gwl` offers the main checkout even from inside it. `gwr` shows
+the main checkout dimmed, starts on the worktree you stand in, and at a
+terminal asks for confirmation when a branch is unfinished (keeping the
+branch) or holds ignored files. An exact branch or path selects that
+worktree alone.
+
+`gwl --list` prints the same columns and is never coloured. `gws` and `gwp`
+print BRANCH, PATH, VERDICT, WHY. The `gwa`, `gwl`, `gwm` and `gwr` shell
+functions print `--list` and `--json` output.
+
+`gws`, `gwp` and `gwr` show a spinner naming the check in progress and judge
+worktrees in parallel. Every command that fetches reuses a fetch under 10
+minutes old, and forge answers that cannot change yet are kept; the README
+lists each case. `--force-refresh` fetches and asks again.
+
 ## 0.4.3 - 2026-09-22
 
 ### Fixed

{git_worktrees-0.4.3 → git_worktrees-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-worktrees
-Version: 0.4.3
+Version: 0.5.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
@@ -31,18 +31,21 @@ Description-Content-Type: text/markdown
 
 Git worktree commands that refuse to lose work.
 
-`gws`, `gwp`, `gwnb`, `gwrot` and `gwh` answer a question and print it. `gwa`,
-`gwl`, `gwm` and `gwr` land you somewhere, and each of those needs a shell
-function, because a binary cannot change its caller's directory.
+`gws`, `gwp`, `gwbs`, `gwbd`, `gwnb`, `gwrot`, and `gwh` run as console
+scripts. `gwa`, `gwl`, `gwm`, and `gwr` change the caller's directory and need
+a shell function of the same name.
 
 | | |
 | --- | --- |
 | `gws` | say which worktrees are finished, and why. Removes nothing, and has no flag that could |
 | `gwp` | remove the ones `gws` marks removable, having asked first |
+| `gwbs [NAME ...]` | assess local branches, including those without worktrees |
+| `gwbd [NAME ...]` | delete branches proved finished, with confirmation and undo commands |
 | `gwa NAME [BASE]` | create a worktree for `NAME` and land you in it |
 | `gwl [QUERY]` | pick one of this repository's worktrees and land you in it |
 | `gwm NEW` | rename this worktree's branch and move the checkout to match |
 | `gwr [QUERY]` | remove a worktree whose branch is finished, and the branch |
+| `gwr! [QUERY]` | `gwr --delete-ignored`, a shell function in fish and zsh |
 | `gwnb NAME` | alpha. Fetch, then branch `NAME` off the head branch and check it out |
 | `gwrot` | alpha. Start the next branch after this one, or catch the head branch up |
 | `gwh` | print that table, with every name each command answers to |
@@ -54,6 +57,8 @@ function, because a binary cannot change its caller's directory.
 | --- | --- |
 | `gws` | `gw status`, `st`, `s` |
 | `gwp` | `gw prune`, `p` |
+| `gwbs` | `gw branch status` |
+| `gwbd` | `gw branch delete` |
 | `gwa` | `gw add`, `a` |
 | `gwl` | `gw list`, `ls`, `l` |
 | `gwm` | `gw move`, `mv`, `m` |
@@ -64,6 +69,11 @@ function, because a binary cannot change its caller's directory.
 
 `worktrees` is the same program under its long name.
 
+The command reference covers [branch status](docs/commands/branch-status.md)
+and [branch delete](docs/commands/branch-delete.md), including content proofs,
+GitHub and GitLab merge evidence, selection, and recovery. `gwbd` with no
+arguments opens a selector; `gwbd --all --dry-run` previews every branch.
+
 Ctrl-C interrupts a running command with exit code 130 and no traceback.
 At a selection or removal prompt, it cancels without choosing or removing
 a worktree.
@@ -121,7 +131,7 @@ Python 3.11 or newer, and no dependencies. The standard library answers every
 question this asks, so an invocation pays for the interpreter and nothing
 else.
 
-That is the whole install for `gws`, `gwp`, `gwnb`, `gwrot` and `gwh`. The
+That installs `gws`, `gwp`, `gwbs`, `gwbd`, `gwnb`, `gwrot`, and `gwh`. The
 four that land you somewhere need a shell function too, and every command has
 a completion, both of which arrive through a plugin manager.
 
@@ -132,7 +142,7 @@ fisher install MihaiBojin/worktrees
 ```
 
 Fisher copies `functions/` and `completions/` from the repository root, so the
-four functions and ten completions land together. Nothing has to be sourced.
+five functions and ten completions land together. Nothing has to be sourced.
 
 ### zsh
 
@@ -143,7 +153,7 @@ MihaiBojin/worktrees path:zsh/plugins/worktrees   # in zsh_plugins.txt
 ```
 
 The plugin puts its own `functions/` and `completions/` on `fpath` and
-autoloads the four. Completion needs `compinit`, which most zsh setups already
+autoloads the five. Completion needs `compinit`, which most zsh setups already
 run; without one, add it after the plugin loads:
 
 ```zsh
@@ -177,12 +187,12 @@ 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
+BRANCH         PATH                                         VERDICT  WHY
+main           /home/you/git/repo                           keep     it is the main checkout, and never removable
+dirty-work     /home/you/git/.worktrees/dirty-work/repo     keep     it has uncommitted changes
+holds-secrets  /home/you/git/.worktrees/holds-secrets/repo  keep     merged, but holds 2 ignored path(s); pass --delete-ignored
+never-pushed   /home/you/git/.worktrees/never-pushed/repo   unknown  not merged into origin/main, and no upstream says whether its commits were pushed
+squash-merged  /home/you/git/.worktrees/squash-merged/repo  remove   squash-merged
 
 1 removable, 3 kept, 1 unclear
 2 worktree(s) under /home/you/git/.worktrees belong to another repository
@@ -288,10 +298,10 @@ away:
 
 ```console
 $ gwp
-VERDICT  BRANCH         WHY                                                                         PATH
-keep     dirty-work     it has uncommitted changes                                                  /home/you/git/.worktrees/dirty-work/repo
-keep     holds-secrets  squash-merged, but holds 2 ignored path(s); pass --delete-ignored           /home/you/git/.worktrees/holds-secrets/repo
-unknown  never-pushed   not merged into main, and no upstream says whether its commits were pushed  /home/you/git/.worktrees/never-pushed/repo
+BRANCH         PATH                                         VERDICT  WHY
+dirty-work     /home/you/git/.worktrees/dirty-work/repo     keep     it has uncommitted changes
+holds-secrets  /home/you/git/.worktrees/holds-secrets/repo  keep     squash-merged, but holds 2 ignored path(s); pass --delete-ignored
+never-pushed   /home/you/git/.worktrees/never-pushed/repo   unknown  not merged into main, and no upstream says whether its commits were pushed
 
 nothing to remove; 0 removable, 2 kept, 1 unclear
 ```
@@ -311,7 +321,7 @@ name goes last, so `auth/oauth` cannot collide with `auth`.
 $ gwa fix-parser          # creates it and lands you in it
 $ gwl parse               # one match takes it outright
 $ gwm parser-v2           # renames the branch and moves the checkout
-$ gwr                     # removes the one you are standing in
+$ gwr                     # asks which, starting on the one you are in
 ```
 
 Each prints one destination on stdout, which is what the shell function
@@ -335,10 +345,11 @@ whatever branch it stands on, and `--list` marks the one you are in:
 
 ```console
 $ gwl --list
-  main           /home/you/git/repo
-  dirty-work     /home/you/git/.worktrees/dirty-work/repo
-  holds-secrets  /home/you/git/.worktrees/holds-secrets/repo
-* never-pushed   /home/you/git/.worktrees/never-pushed/repo
+   WORKTREE       BRANCH         PATH
+   repo           main           /home/you/git/repo
+   dirty-work     dirty-work     /home/you/git/.worktrees/dirty-work/repo
+   holds-secrets  holds-secrets  /home/you/git/.worktrees/holds-secrets/repo
+*  never-pushed   never-pushed   /home/you/git/.worktrees/never-pushed/repo
 ```
 
 It never offers that one. Picking it is the one answer that cannot take you
@@ -352,28 +363,42 @@ already in dirty-work
 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:
+asks, however many there are:
 
 ```console
 $ 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]
+  #  WORKTREE       BRANCH         PATH
+  *  never-pushed   never-pushed   /home/you/git/.worktrees/never-pushed/repo
+> 1  repo           main           /home/you/git/repo
+  2  dirty-work     dirty-work     /home/you/git/.worktrees/dirty-work/repo
+  3  holds-secrets  holds-secrets  /home/you/git/.worktrees/holds-secrets/repo
+which? [up/down and enter, 1-3, or esc 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.
+WORKTREE is the directory under `.worktrees`, or the main checkout's own
+directory name. It parts from BRANCH when somebody switches branch inside a
+worktree. Up and down move the highlight, enter takes it, a digit takes that
+row outright, and esc cancels.
+
+A linked worktree 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. The main checkout is always
+numbered, even when you are inside it, and carries a `*` after its name
+then: from a subdirectory, picking it takes you back to the top.
 
 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`.
 
-`gwr` refuses a branch that is not finished and says why, the same verdict
-`gws` prints. `--force` removes the checkout and keeps the branch: the
-worktree was in the way, the work was not.
+`gwr` lists the main checkout dimmed and unnumbered, since git will not
+remove it, and starts the highlight on the worktree you are standing in. A
+name or path that is exactly one worktree's, as `gwl --list` and `gwl` print
+them, takes that one without asking which.
+
+`gwr` says why a branch is not finished, the same verdict `gws` prints. At a
+terminal it then asks whether to remove the checkout anyway, and keeps the
+branch: the worktree was in the way, the work was not. `--force` is the same
+answer without the question, and `--yes` on its own refuses.
 
 A finished branch whose worktree holds ignored files is refused too, and named
 as finished, because it is:
@@ -383,11 +408,19 @@ $ gwr holds-secrets
 holds-secrets is finished: squash-merged, but holds 2 ignored path(s); pass --delete-ignored
 ```
 
+At a terminal, and without `--yes`, `gwr` asks instead: it names every
+ignored path and removes the worktree on a `y`. `--yes` never answers that
+question, so a script still needs `--delete-ignored`.
+
 `--force` is not the answer to that one. It deletes those files just the same,
 since `git worktree remove` takes the whole directory, and it keeps a branch
 whose work already landed. Every ignored path is named before anything is
 deleted, under `--delete-ignored` and under `--force` alike.
 
+`gwr!` is `gwr --delete-ignored`, for when the ignored files are ones you meant
+to lose. It is a shell function in fish and zsh, not a console script, and it
+calls the `gwr` function so you still land where `gwr` says.
+
 ## gwnb and gwrot (alpha)
 
 Both are alpha and both start branches rather than worktrees. See the note
@@ -466,15 +499,42 @@ 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`, `--no-forge`, `-y` |
-| `gwa`, `gwnb`, `gwrot` | `--no-fetch` |
+| `gws` | `--branch NAME`, `--no-fetch`, `--force-refresh`, `--delete-ignored`, `--no-forge` |
+| `gwp` | those five, and `-y` |
+| `gwr` | `-f`, `--delete-ignored`, `--no-fetch`, `--force-refresh`, `--no-forge`, `-y` |
+| `gwa`, `gwnb`, `gwrot` | `--no-fetch`, `--force-refresh` |
+| `gwbs` | `--no-fetch`, `--force-refresh`, `--no-forge` |
+| `gwbd` | those three, `--all`, `--dry-run` and `-y` |
 | `gwl` | `-l` |
 | `gwm`, `gwh` | none |
 
 `gw <command> --help` prints one command's own list.
 
+While `gws`, `gwp` and `gwr` fetch and judge, a spinner on stderr names the
+branch and the check in progress.
+
+### What is reused, and for how long
+
+A fetch and a question to the forge are most of what a run costs, so an answer
+that is still true is reused. `--force-refresh` fetches and asks again whatever
+is kept, and `--no-fetch` never fetches.
+
+| what | when | reused for |
+| --- | --- | --- |
+| a fetch, by `gws`, `gwp`, `gwr`, `gwbs`, `gwbd`, `gwa`, `gwnb`, `gwrot` | from any worktree of the repository | 10 minutes; the command says how old it is |
+| a request, merged or closed | on the commit it was asked about | until `--force-refresh` |
+| a request, open | a draft, a conflict, or on GitLab a needed rebase, with no auto-merge and no check running | 10 minutes |
+| a request, open | auto-merge or merge-when-pipeline-succeeds set | never |
+| a request, open | a check still running or pending | never |
+| a request, open | the forge calls it mergeable, or cannot say | never |
+| no request | the branch has no upstream | 10 minutes |
+| no request | the branch has an upstream | 1 minute |
+| no answer | `gh`/`glab` missing, not signed in, failing or timing out | never |
+
+Forge answers live in `git-worktrees-forge.json` in the repository's common git
+directory, filed under the branch and its commit. A new commit on the branch is
+a new question, so nothing kept outlives the commit it was given for.
+
 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. The forge is not asked either: it is
@@ -485,7 +545,8 @@ forge asked.
 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
-bytes a pipe would have got, `--json` included. `NO_COLOR=` is not a request to
+bytes a pipe would have got. `--json` and `gwl --list` are never coloured, even
+on a terminal. `NO_COLOR=` is not a request to
 turn it off, which is the no-color.org rule.
 
 Every command is a console script, so a script reaches it with no shell loaded