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

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

@@ -156,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.3.0 → git_worktrees-0.4.0}/CHANGELOG.md

@@ -17,6 +17,65 @@ 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.4.0 - 2026-09-21
+
+### Security
+
+Forge queries ignore `GH_REPO` and `GITLAB_REPO`, so a merged request in
+another repository cannot authorize removal here.
+
+Printed branch restoration commands and `gwnb` checkout hints quote branch
+names so shell metacharacters are treated as part of the name.
+
+### Added
+
+`gws` reports how many worktrees under the shared `.worktrees` directory
+belong to other repositories, with the count in `gws --json` as `neighbours`.
+
+### Fixed
+
+After a failed fetch, worktree assessments use local refs and skip forge
+queries.
+
+`gwl` and `gwr` shell completions omit paths containing newlines, which
+cannot fit their one-row-per-line format; those worktrees remain reachable
+by name or path.
+
+Pressing Ctrl-C at a worktree selection or removal prompt exits with code
+130 and no traceback. No worktree is selected or removed.
+
+## 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-worktrees
-Version: 0.3.0
+Version: 0.4.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
@@ -64,6 +64,10 @@ function, because a binary cannot change its caller's directory.
 
 `worktrees` is the same program under its long name.
 
+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.
+
 `gws` and `gwp` are what this tool is for and their behaviour is settled.
 
 **`gwnb` and `gwrot` are alpha and may go.** They start branches rather than
@@ -160,6 +164,12 @@ subcommand and shorthand, `gwl --complete` prints every worktree, and both
 shells narrow what those return, so the matching stays in one place and a
 command added to the table needs no edit in either shell.
 
+One row a line, `label<TAB>path`. A worktree whose path holds a newline is
+left out of that listing, because both shells would read it as two rows and
+offer the tail as a worktree of its own. `gwa` cannot make such a path, since
+it derives from a branch name and git refuses a newline in a ref, and the
+worktree is still reachable by name or path.
+
 Neither manager puts a binary on `$PATH`, which is why the two installs stay
 separate.
 
@@ -168,19 +178,30 @@ 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
+2 worktree(s) under /home/you/git/.worktrees belong to another repository
 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.
+count are on stdout; everything after them is on stderr.
+
+Every repository in the same parent directory keeps its worktrees under that
+one `.worktrees` root, so some of the directories in there are a sibling's.
+`gws` counts those and says so, because nothing else does, and `--json`
+carries the same count as `neighbours`. No command here reads or removes
+them, and the count comes from walking the root rather than from asking git.
 
 On a terminal the verdict carries its own colour, `remove` green, `keep` blue
 and `unknown` yellow, with the branch in bold and the path dimmed. That
@@ -204,7 +225,13 @@ squashes, so the intermediate state it holds differs from the final one in
 the same regions, and a diff cannot separate a stale branch from one with
 work left. A merged pull request settles it, cross-checked against the
 commits an upstream has not got, because a request speaks for what reached
-it and nothing about what never did. `--no-forge` decides from git alone.
+it and nothing about what never did. `--no-forge` decides from git alone, and
+so does a run whose fetch just failed.
+
+The question goes to the repository the command is standing in and nowhere
+else. `GH_REPO` and `GITLAB_REPO` beat that directory, so both are dropped
+before `gh` or `glab` runs; everything else in the environment, the token
+included, is passed through.
 
 A record left behind by a directory somebody deleted by hand is nobody's
 verdict. `gws` names how many there are; clearing them is `git worktree prune`,
@@ -326,13 +353,18 @@ 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`.
@@ -443,7 +475,10 @@ print one thing each and have nothing to be quiet about, takes `--json`, `-q`,
 
 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.
+where `--no-fetch` sends it on request. The forge is not asked either: it is
+over the same network, and `gh` waits 30 seconds before saying so, once per
+branch. `--no-fetch` alone says nothing about the network, so it leaves the
+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
@@ -498,7 +533,9 @@ is refused with them: it deletes refs without `-d` appearing at all.
 The Python, the tests and the release procedure are in
 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). The rules the code follows are in
 [AGENTS.md](AGENTS.md). What changed in each release is in
-[CHANGELOG.md](CHANGELOG.md).
+[CHANGELOG.md](CHANGELOG.md). What was decided and what must not break,
+including the alternatives that were closed, is in
+[docs/REFERENCE.md](docs/REFERENCE.md).
 
 ## Licence
 

{git_worktrees-0.3.0 → git_worktrees-0.4.0}/README.md

@@ -38,6 +38,10 @@ function, because a binary cannot change its caller's directory.
 
 `worktrees` is the same program under its long name.
 
+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.
+
 `gws` and `gwp` are what this tool is for and their behaviour is settled.
 
 **`gwnb` and `gwrot` are alpha and may go.** They start branches rather than
@@ -134,6 +138,12 @@ subcommand and shorthand, `gwl --complete` prints every worktree, and both
 shells narrow what those return, so the matching stays in one place and a
 command added to the table needs no edit in either shell.
 
+One row a line, `label<TAB>path`. A worktree whose path holds a newline is
+left out of that listing, because both shells would read it as two rows and
+offer the tail as a worktree of its own. `gwa` cannot make such a path, since
+it derives from a branch name and git refuses a newline in a ref, and the
+worktree is still reachable by name or path.
+
 Neither manager puts a binary on `$PATH`, which is why the two installs stay
 separate.
 
@@ -142,19 +152,30 @@ 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
+2 worktree(s) under /home/you/git/.worktrees belong to another repository
 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.
+count are on stdout; everything after them is on stderr.
+
+Every repository in the same parent directory keeps its worktrees under that
+one `.worktrees` root, so some of the directories in there are a sibling's.
+`gws` counts those and says so, because nothing else does, and `--json`
+carries the same count as `neighbours`. No command here reads or removes
+them, and the count comes from walking the root rather than from asking git.
 
 On a terminal the verdict carries its own colour, `remove` green, `keep` blue
 and `unknown` yellow, with the branch in bold and the path dimmed. That
@@ -178,7 +199,13 @@ squashes, so the intermediate state it holds differs from the final one in
 the same regions, and a diff cannot separate a stale branch from one with
 work left. A merged pull request settles it, cross-checked against the
 commits an upstream has not got, because a request speaks for what reached
-it and nothing about what never did. `--no-forge` decides from git alone.
+it and nothing about what never did. `--no-forge` decides from git alone, and
+so does a run whose fetch just failed.
+
+The question goes to the repository the command is standing in and nowhere
+else. `GH_REPO` and `GITLAB_REPO` beat that directory, so both are dropped
+before `gh` or `glab` runs; everything else in the environment, the token
+included, is passed through.
 
 A record left behind by a directory somebody deleted by hand is nobody's
 verdict. `gws` names how many there are; clearing them is `git worktree prune`,
@@ -300,13 +327,18 @@ 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`.
@@ -417,7 +449,10 @@ print one thing each and have nothing to be quiet about, takes `--json`, `-q`,
 
 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.
+where `--no-fetch` sends it on request. The forge is not asked either: it is
+over the same network, and `gh` waits 30 seconds before saying so, once per
+branch. `--no-fetch` alone says nothing about the network, so it leaves the
+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
@@ -472,7 +507,9 @@ is refused with them: it deletes refs without `-d` appearing at all.
 The Python, the tests and the release procedure are in
 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). The rules the code follows are in
 [AGENTS.md](AGENTS.md). What changed in each release is in
-[CHANGELOG.md](CHANGELOG.md).
+[CHANGELOG.md](CHANGELOG.md). What was decided and what must not break,
+including the alternatives that were closed, is in
+[docs/REFERENCE.md](docs/REFERENCE.md).
 
 ## Licence
 

{git_worktrees-0.3.0 → git_worktrees-0.4.0}/docs/DEVELOPMENT.md

@@ -24,7 +24,9 @@ invisible to it, so CI is the first thing to format a file you just wrote.
 
 
 The rules this code follows, and the reasoning behind them, are in
-[AGENTS.md](../AGENTS.md). This file is what to run.
+[AGENTS.md](../AGENTS.md). What was decided, what must not break and which
+failure classes have a test are in [REFERENCE.md](REFERENCE.md). This file is
+what to run.
 
 ## Layout