@narumitw/pi-worktree 0.51.2 → 0.51.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +81 -51
- package/dist/index.ts +1893 -0
- package/dist/index.ts.map +7 -0
- package/package.json +9 -5
package/README.md
CHANGED
|
@@ -1,27 +1,20 @@
|
|
|
1
|
-
# 🌳 pi-worktree —
|
|
1
|
+
# 🌳 pi-worktree — Create, Switch, and Remove Git Worktrees in Pi
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-worktree) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Create, inspect, switch, remove, and prune Git worktrees through one guarded `/worktree` manager.
|
|
6
6
|
|
|
7
|
-
Pi cannot change its parent process
|
|
7
|
+
Because Pi cannot change its parent process directory with `cd`, the extension switches to a prepared Pi session whose cwd is the selected worktree and preserves the current conversation when possible.
|
|
8
8
|
|
|
9
9
|
## ✨ Features
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
- Switches among existing registered worktrees through Pi's public session replacement API.
|
|
19
|
-
- Removes unlocked, non-current linked worktrees and preserves their branches.
|
|
20
|
-
- Refuses removal when tracked, untracked, manually index-flagged, submodule, or current unreachable detached-commit data may be lost.
|
|
21
|
-
- Allows ignored-only data such as `node_modules/` after listing it in the destructive confirmation.
|
|
22
|
-
- Names recovery-only administrative commits in the destructive confirmation instead of making ordinary rebase/reset history block cleanup forever.
|
|
23
|
-
- Always previews stale metadata before pruning it and revalidates the preview after confirmation.
|
|
24
|
-
- Runs Git through argv-based subprocess calls, without interpolating user input into shell commands.
|
|
11
|
+
- Lists main, linked, current, detached, locked, and prunable worktrees with searchable status details.
|
|
12
|
+
- Creates a worktree from a new branch or an unoccupied local branch after previewing the exact base commit.
|
|
13
|
+
- Suggests a configurable path under `~/.worktrees/` and rejects unsafe, occupied, or ambiguous targets.
|
|
14
|
+
- Switches Pi to an existing or newly created worktree while preserving the conversation when possible.
|
|
15
|
+
- Removes only non-current unlocked worktrees after checking tracked, untracked, index, submodule, and detached-commit risk.
|
|
16
|
+
- Previews ignored files and stale metadata before confirmed removal or pruning, then revalidates the plan.
|
|
17
|
+
- Runs Git with argument arrays and never interpolates user input into shell commands.
|
|
25
18
|
|
|
26
19
|
## 📦 Install
|
|
27
20
|
|
|
@@ -38,11 +31,18 @@ pi -e npm:@narumitw/pi-worktree
|
|
|
38
31
|
Try this package locally from the repository root:
|
|
39
32
|
|
|
40
33
|
```bash
|
|
41
|
-
|
|
42
|
-
|
|
34
|
+
npm --workspace @narumitw/pi-worktree run build
|
|
35
|
+
pi -e ./packages/pi-worktree
|
|
43
36
|
```
|
|
44
37
|
|
|
45
|
-
|
|
38
|
+
The package declares `dist/index.ts`, so an unbuilt local checkout must be built before Pi loads the package directory.
|
|
39
|
+
|
|
40
|
+
## 🚀 Quick start
|
|
41
|
+
|
|
42
|
+
Run `/worktree` in TUI or RPC mode and choose the worktree action you need.
|
|
43
|
+
Every mutation shows package-owned safety checks and an exact confirmation before Git changes the worktree state.
|
|
44
|
+
|
|
45
|
+
## 💬 Commands
|
|
46
46
|
|
|
47
47
|
Run the command without arguments:
|
|
48
48
|
|
|
@@ -59,28 +59,31 @@ Choose one action:
|
|
|
59
59
|
- **Prune stale metadata** — inspect Git's dry-run output, then optionally run the matching prune.
|
|
60
60
|
- **Configure worktree root** — set a machine-local default root or submit a blank value to restore `~/.worktrees`.
|
|
61
61
|
|
|
62
|
-
The standard root menu shows the registered count, current path, effective worktree root, its source,
|
|
63
|
-
|
|
64
|
-
subcommands or expose argument autocomplete.
|
|
65
|
-
RPC dialogs; print and JSON modes reject the command observably.
|
|
66
|
-
inputs, searchable worktree identity selectors, preflight previews, and destructive confirmations remain
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
counts, configured upstream ahead/behind, and the last commit timestamp and subject. A missing
|
|
72
|
-
upstream is reported as **not configured**; it is not treated as proof that no commits are unpushed.
|
|
62
|
+
The standard root menu shows the registered count, current path, effective worktree root, its source, and any settings warning.
|
|
63
|
+
Escape closes it.
|
|
64
|
+
`/worktree` intentionally does not accept text subcommands or expose argument autocomplete.
|
|
65
|
+
Every change is initiated and confirmed through TUI or RPC dialogs; print and JSON modes reject the command observably.
|
|
66
|
+
Operation-specific branch/path inputs, searchable worktree identity selectors, preflight previews, and destructive confirmations remain extension-owned because they carry Git safety and commit-aware revalidation.
|
|
67
|
+
|
|
68
|
+
The status browser runs only when selected and has no watcher, timer, persistent cache, or network fetch.
|
|
69
|
+
Each card shows textual current/main/detached state, full snapshot HEAD, aggregate working-tree counts, configured upstream ahead/behind, and the last commit timestamp and subject.
|
|
70
|
+
A missing upstream is reported as **not configured**; it is not treated as proof that no commits are unpushed.
|
|
73
71
|
Bare, missing, prunable, or individually failing worktrees remain visible with an unavailable reason.
|
|
74
|
-
The snapshot is informational and can become stale immediately, so Remove still performs its stricter
|
|
75
|
-
inventory and identity checks.
|
|
72
|
+
The snapshot is informational and can become stale immediately, so Remove still performs its stricter inventory and identity checks.
|
|
76
73
|
|
|
77
74
|
## 🌿 Add defaults
|
|
78
75
|
|
|
79
|
-
For a new branch, the current symbolic branch is the default start point.
|
|
76
|
+
For a new branch, the current symbolic branch is the default start point.
|
|
77
|
+
If Pi is running from detached HEAD, the command requires an explicit commit-ish.
|
|
78
|
+
Git must resolve the start point to exactly one commit.
|
|
80
79
|
|
|
81
|
-
Before mutation, Add identifies whether the branch is new or existing and displays the provenance as the current branch, an explicit commit-ish, or an existing local branch together with its full resolved OID and target path.
|
|
80
|
+
Before mutation, Add identifies whether the branch is new or existing and displays the provenance as the current branch, an explicit commit-ish, or an existing local branch together with its full resolved OID and target path.
|
|
81
|
+
New branches are created from that approved OID even if the source ref later moves.
|
|
82
|
+
Existing branches are checked again immediately before mutation and the created worktree HEAD is verified afterward.
|
|
83
|
+
Git has no atomic compare-and-add operation for attaching an existing branch, so a post-add mismatch is retained for inspection rather than rolled back.
|
|
82
84
|
|
|
83
|
-
The default root is `~/.worktrees`, where `~` is Node's platform home directory.
|
|
85
|
+
The default root is `~/.worktrees`, where `~` is Node's platform home directory.
|
|
86
|
+
Suggestions use the registered main worktree's directory name, not the current linked-worktree cwd:
|
|
84
87
|
|
|
85
88
|
```text
|
|
86
89
|
main worktree: /home/user/workspace/project
|
|
@@ -89,13 +92,18 @@ root: /home/user/.worktrees
|
|
|
89
92
|
suggested: /home/user/.worktrees/project/feat-login
|
|
90
93
|
```
|
|
91
94
|
|
|
92
|
-
On Windows, the equivalent default is such as `C:\Users\Alice\.worktrees`.
|
|
95
|
+
On Windows, the equivalent default is such as `C:\Users\Alice\.worktrees`.
|
|
96
|
+
Branch `/` characters become `-`.
|
|
97
|
+
The extension does not add hashes or collision suffixes: if two normalized paths collide or the target already exists, Add stops before Git mutation.
|
|
93
98
|
|
|
94
|
-
Leave the path input blank to accept the suggestion.
|
|
99
|
+
Leave the path input blank to accept the suggestion.
|
|
100
|
+
A custom absolute path is used directly; a custom relative path is resolved from the current Pi cwd.
|
|
101
|
+
The target itself must not exist, and its nearest existing ancestor must resolve without a broken or looping symbolic link.
|
|
102
|
+
Existing registered worktrees are never moved when this default changes.
|
|
95
103
|
|
|
96
104
|
The MVP does not expose `--force`, `-B`, `--detach`, `--orphan`, or lock options.
|
|
97
105
|
|
|
98
|
-
## ⚙️
|
|
106
|
+
## ⚙️ Settings
|
|
99
107
|
|
|
100
108
|
The machine-local user settings file is:
|
|
101
109
|
|
|
@@ -103,7 +111,8 @@ The machine-local user settings file is:
|
|
|
103
111
|
<getAgentDir()>/pi-worktree.json
|
|
104
112
|
```
|
|
105
113
|
|
|
106
|
-
For a default Pi installation this is typically `~/.pi/agent/pi-worktree.json`.
|
|
114
|
+
For a default Pi installation this is typically `~/.pi/agent/pi-worktree.json`.
|
|
115
|
+
Configure it through **Configure worktree root** or edit it manually:
|
|
107
116
|
|
|
108
117
|
```json
|
|
109
118
|
{
|
|
@@ -111,43 +120,60 @@ For a default Pi installation this is typically `~/.pi/agent/pi-worktree.json`.
|
|
|
111
120
|
}
|
|
112
121
|
```
|
|
113
122
|
|
|
114
|
-
`worktreeRoot` accepts `~`, a home-prefixed path such as `~/worktrees`, or a native-platform absolute path.
|
|
123
|
+
`worktreeRoot` accepts `~`, a home-prefixed path such as `~/worktrees`, or a native-platform absolute path.
|
|
124
|
+
It does not expand `$VAR`, `%VAR%`, or other shell syntax.
|
|
125
|
+
Empty, relative, NUL-containing, non-string, and invalid paths are rejected.
|
|
126
|
+
There is no project override or extension-specific environment variable.
|
|
115
127
|
|
|
116
|
-
A missing `worktreeRoot` uses `~/.worktrees`; the settings file is created only by a successful interactive change.
|
|
128
|
+
A missing `worktreeRoot` uses `~/.worktrees`; the settings file is created only by a successful interactive change.
|
|
129
|
+
Submitting a blank value in the interactive action removes the override.
|
|
130
|
+
Within one Pi process, queued saves run in invocation order, reread the latest valid document immediately before merging `worktreeRoot`, and preserve concurrent unknown-field edits.
|
|
131
|
+
Settings reload on every `session_start`, including `/reload` and workspace replacement; a successful interactive save applies immediately to the next Add flow.
|
|
117
132
|
|
|
118
|
-
Malformed or invalid settings are warned about but never overwritten, including an invalid edit made while a settings action is open.
|
|
133
|
+
Malformed or invalid settings are warned about but never overwritten, including an invalid edit made while a settings action is open.
|
|
134
|
+
An initial failure uses `~/.worktrees`; a later failure retains the last valid effective root.
|
|
135
|
+
Interactive configuration remains blocked until the invalid file is fixed manually.
|
|
136
|
+
Failed publication leaves the prior file and effective runtime root unchanged, and the save queue remains usable after rejection.
|
|
119
137
|
|
|
120
138
|
## 🔀 Pi workspace switching
|
|
121
139
|
|
|
122
140
|
Switching uses Pi's public `SessionManager` and `ctx.switchSession()` APIs:
|
|
123
141
|
|
|
124
142
|
1. The command waits for Pi to become fully idle so the current assistant/tool results are persisted.
|
|
125
|
-
2. A linear persisted session is forked into the target worktree.
|
|
143
|
+
2. A linear persisted session is forked into the target worktree.
|
|
144
|
+
If `/tree` currently points at an older branch, the documented session entries for that active branch are written to the target instead, so switching cannot jump to a newer serialized leaf.
|
|
126
145
|
3. Pi tears down the old cwd-bound runtime and creates the target runtime.
|
|
127
146
|
4. The extension reports success only through the fresh replacement-session context.
|
|
128
147
|
|
|
129
|
-
If the current session is completely empty, the extension creates a valid empty Pi session for the target.
|
|
148
|
+
If the current session is completely empty, the extension creates a valid empty Pi session for the target.
|
|
149
|
+
If the current session is ephemeral (`--no-session`), the extension copies its active conversation branch into a persisted target session so the workspace switch does not lose context.
|
|
130
150
|
|
|
131
|
-
A successfully created Git worktree is never rolled back merely because Pi session switching fails.
|
|
151
|
+
A successfully created Git worktree is never rolled back merely because Pi session switching fails.
|
|
152
|
+
Re-run `/worktree` and choose **Switch worktree** after resolving the reported Pi/session issue.
|
|
132
153
|
|
|
133
154
|
## 🛡️ Safety boundaries
|
|
134
155
|
|
|
135
156
|
- The main worktree and current worktree cannot be removed.
|
|
136
157
|
- Locked or stale worktrees cannot be removed through this extension.
|
|
137
|
-
- Dirty, untracked, initialized-submodule, and intentional `assume-unchanged`/`skip-worktree` index state causes removal to fail closed.
|
|
138
|
-
-
|
|
158
|
+
- Dirty, untracked, initialized-submodule, and intentional `assume-unchanged`/`skip-worktree` index state causes removal to fail closed.
|
|
159
|
+
Sparse-checkout-managed `skip-worktree` entries outside the active sparsity rules are allowed when Git's rule checker can confirm them; clear other intentional index flags before removing the worktree.
|
|
160
|
+
- Ignored-only files and directories do not block removal.
|
|
161
|
+
The confirmation lists them, and the extension rechecks the exact ignored inventory before Git deletes the worktree.
|
|
139
162
|
- A detached HEAD must be reachable from a local branch, tag, or remote ref before removal or prune.
|
|
140
|
-
- Removal and prune inspect reflogs, pseudorefs, per-worktree refs, and `FETCH_HEAD`.
|
|
163
|
+
- Removal and prune inspect reflogs, pseudorefs, per-worktree refs, and `FETCH_HEAD`.
|
|
164
|
+
Historical commits reachable only through this administrative recovery state are listed by full OID in the destructive confirmation; approval removes those recovery pointers, so Git may later garbage-collect the commits.
|
|
165
|
+
Create a branch or tag instead when any listed commit should survive.
|
|
141
166
|
- Staged-only administrative index state, a missing attached branch ref, or an unreachable current detached HEAD still blocks prune without an override.
|
|
142
167
|
- Removal never deletes a branch and never uses `--force`.
|
|
143
168
|
- Remove invokes only argv-based `git worktree remove <path>`; production runtime never invokes a shell, `rm`, `rm -rf`, or a Node filesystem directory-deletion API for worktrees.
|
|
144
|
-
- Prune always runs `git worktree prune --dry-run --verbose` before confirmation, inspects candidates omitted from porcelain, rechecks the exact preview and recovery-risk set after confirmation, and uses Git's default expiry.
|
|
169
|
+
- Prune always runs `git worktree prune --dry-run --verbose` before confirmation, inspects candidates omitted from porcelain, rechecks the exact preview and recovery-risk set after confirmation, and uses Git's default expiry.
|
|
170
|
+
Remove likewise rechecks worktree identity, inventory, administrative path, and the approved recovery-risk set before mutation.
|
|
145
171
|
- The status browser uses only local Git state and never fetches a remote; its cards never authorize Remove or Prune.
|
|
146
172
|
- The extension does not commit, push, fetch, rebase, repair, move, lock, or unlock worktrees.
|
|
147
173
|
|
|
148
174
|
Use Git directly when you intentionally need force removal, branch deletion, custom prune expiry, detach/orphan creation, move, repair, lock, unlock, or remote refresh behavior.
|
|
149
175
|
|
|
150
|
-
##
|
|
176
|
+
## 🚧 Limitations
|
|
151
177
|
|
|
152
178
|
- Git must be installed and the current Pi cwd must be inside a non-bare Git worktree.
|
|
153
179
|
- The command requires a UI-capable Pi mode; print and JSON modes cannot drive its dialogs.
|
|
@@ -166,10 +192,14 @@ packages/pi-worktree/
|
|
|
166
192
|
│ ├── settings.ts
|
|
167
193
|
│ ├── status.ts
|
|
168
194
|
│ └── worktree.ts
|
|
195
|
+
├── dist/ # Generated source-mapped Jiti runtime
|
|
196
|
+
├── scripts/
|
|
197
|
+
│ └── build-runtime.mjs
|
|
169
198
|
├── test/
|
|
170
199
|
│ ├── add-command.test.ts
|
|
171
200
|
│ ├── command-test-support.ts
|
|
172
201
|
│ ├── command.test.ts
|
|
202
|
+
│ ├── build-runtime.test.ts
|
|
173
203
|
│ ├── git.integration.test.ts
|
|
174
204
|
│ ├── git.test.ts
|
|
175
205
|
│ ├── remove-ignored-command.test.ts
|