@narumitw/pi-worktree 0.51.6 → 0.51.8
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 +54 -78
- package/dist/index.ts +54 -227
- package/dist/index.ts.map +2 -2
- package/package.json +49 -53
- package/src/command.ts +605 -693
- package/src/git.ts +635 -731
- package/src/session.ts +77 -81
- package/src/settings.ts +211 -223
- package/src/status.ts +287 -309
- package/src/worktree.ts +26 -33
package/README.md
CHANGED
|
@@ -3,21 +3,23 @@
|
|
|
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
|
-
|
|
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.
|
|
6
|
+
Because `cd` cannot change Pi's parent process directory, switching prepares a Pi session whose cwd is the selected worktree and carries over the active conversation when possible.
|
|
8
7
|
|
|
9
8
|
## ✨ Features
|
|
10
9
|
|
|
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
|
|
10
|
+
- Lists main, linked, current, detached, locked, and prunable worktrees with searchable local status details.
|
|
11
|
+
- Creates a worktree from a new branch or an unoccupied local branch after showing the exact base commit.
|
|
13
12
|
- 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
|
|
16
|
-
-
|
|
17
|
-
-
|
|
13
|
+
- Switches Pi to an existing or newly created worktree while preserving the active conversation when possible.
|
|
14
|
+
- Removes only non-current, unlocked worktrees after checking tracked, untracked, index, submodule, and detached-commit risks.
|
|
15
|
+
- Shows ignored files and stale metadata before confirmed removal or pruning, then revalidates the approved plan.
|
|
16
|
+
- Passes arguments directly to Git without interpolating user input into shell commands.
|
|
18
17
|
|
|
19
18
|
## 📦 Install
|
|
20
19
|
|
|
20
|
+
This extension runs Git and writes settings and Pi sessions with Pi's process permissions.
|
|
21
|
+
Install it only from a source you trust.
|
|
22
|
+
|
|
21
23
|
```bash
|
|
22
24
|
pi install npm:@narumitw/pi-worktree
|
|
23
25
|
```
|
|
@@ -39,37 +41,16 @@ The package declares `dist/index.ts`, so an unbuilt local checkout must be built
|
|
|
39
41
|
|
|
40
42
|
## 🚀 Quick start
|
|
41
43
|
|
|
42
|
-
Run `/worktree` in TUI or RPC mode and choose
|
|
43
|
-
|
|
44
|
+
Run `/worktree` in TUI or RPC mode and choose an action.
|
|
45
|
+
Before each Git mutation, the extension runs its safety checks and shows the exact change for confirmation.
|
|
44
46
|
|
|
45
47
|
## 💬 Commands
|
|
46
48
|
|
|
47
|
-
Run the
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
Choose one action:
|
|
54
|
-
|
|
55
|
-
- **Worktree status** — browse a local snapshot for every registered worktree without fetching remotes.
|
|
56
|
-
- **Add worktree** — enter a branch, optional start point, and optional path; review exact base provenance, confirm creation, and optionally switch.
|
|
57
|
-
- **Switch worktree** — search for another existing worktree by displayed path, branch, or HEAD and continue this Pi conversation there.
|
|
58
|
-
- **Remove worktree** — search for a linked worktree by displayed path, branch, or HEAD, then remove it without deleting its branch; ignored-only data is listed for explicit confirmation.
|
|
59
|
-
- **Prune stale metadata** — inspect Git's dry-run output, then optionally run the matching prune.
|
|
60
|
-
- **Configure worktree root** — set a machine-local default root or submit a blank value to restore `~/.worktrees`.
|
|
61
|
-
|
|
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.
|
|
71
|
-
Bare, missing, prunable, or individually failing worktrees remain visible with an unavailable reason.
|
|
72
|
-
The snapshot is informational and can become stale immediately, so Remove still performs its stricter inventory and identity checks.
|
|
49
|
+
Run `/worktree` to inspect, create, switch, or remove Git worktrees, prune stale metadata, and configure the default root in TUI or RPC mode.
|
|
50
|
+
It accepts no arguments; print and JSON modes reject it before any Git call.
|
|
51
|
+
Git must be installed and Pi must be inside a non-bare worktree.
|
|
52
|
+
Destructive changes require confirmation and never delete branches; review [Safety boundaries](#-safety-boundaries), including ignored-file and recovery-pointer loss.
|
|
53
|
+
See [Add defaults](#-add-defaults) for creation rules and [Pi workspace switching](#-pi-workspace-switching) for conversation transfer and failure recovery.
|
|
73
54
|
|
|
74
55
|
## 🌿 Add defaults
|
|
75
56
|
|
|
@@ -77,7 +58,8 @@ For a new branch, the current symbolic branch is the default start point.
|
|
|
77
58
|
If Pi is running from detached HEAD, the command requires an explicit commit-ish.
|
|
78
59
|
Git must resolve the start point to exactly one commit.
|
|
79
60
|
|
|
80
|
-
Before mutation, Add identifies whether the branch is new or existing
|
|
61
|
+
Before mutation, Add identifies whether the branch is new or existing.
|
|
62
|
+
It shows the current branch, explicit commit-ish, or existing local branch used as provenance, plus the full resolved OID and target path.
|
|
81
63
|
New branches are created from that approved OID even if the source ref later moves.
|
|
82
64
|
Existing branches are checked again immediately before mutation and the created worktree HEAD is verified afterward.
|
|
83
65
|
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.
|
|
@@ -94,7 +76,8 @@ suggested: /home/user/.worktrees/project/feat-login
|
|
|
94
76
|
|
|
95
77
|
On Windows, the equivalent default is such as `C:\Users\Alice\.worktrees`.
|
|
96
78
|
Branch `/` characters become `-`.
|
|
97
|
-
The extension does not add hashes or collision suffixes
|
|
79
|
+
The extension does not add hashes or collision suffixes.
|
|
80
|
+
If normalized paths collide or the target already exists, Add stops before mutating Git state.
|
|
98
81
|
|
|
99
82
|
Leave the path input blank to accept the suggestion.
|
|
100
83
|
A custom absolute path is used directly; a custom relative path is resolved from the current Pi cwd.
|
|
@@ -125,9 +108,11 @@ It does not expand `$VAR`, `%VAR%`, or other shell syntax.
|
|
|
125
108
|
Empty, relative, NUL-containing, non-string, and invalid paths are rejected.
|
|
126
109
|
There is no project override or extension-specific environment variable.
|
|
127
110
|
|
|
128
|
-
A missing `worktreeRoot` uses `~/.worktrees
|
|
111
|
+
A missing `worktreeRoot` uses `~/.worktrees`.
|
|
112
|
+
A successful interactive change is the only operation that creates the settings file.
|
|
129
113
|
Submitting a blank value in the interactive action removes the override.
|
|
130
|
-
Within one Pi process, queued saves run in invocation order
|
|
114
|
+
Within one Pi process, queued saves run in invocation order.
|
|
115
|
+
Each save rereads the latest valid document before merging `worktreeRoot` and preserves concurrent edits to unknown fields.
|
|
131
116
|
Settings reload on every `session_start`, including `/reload` and workspace replacement; a successful interactive save applies immediately to the next Add flow.
|
|
132
117
|
|
|
133
118
|
Malformed or invalid settings are warned about but never overwritten, including an invalid edit made while a settings action is open.
|
|
@@ -137,41 +122,52 @@ Failed publication leaves the prior file and effective runtime root unchanged, a
|
|
|
137
122
|
|
|
138
123
|
## 🔀 Pi workspace switching
|
|
139
124
|
|
|
140
|
-
Switching uses Pi's public `SessionManager` and `ctx.switchSession()` APIs:
|
|
125
|
+
Switching uses Pi's public `SessionManager` and `ctx.switchSession()` APIs in this order:
|
|
141
126
|
|
|
142
127
|
1. The command waits for Pi to become fully idle so the current assistant/tool results are persisted.
|
|
143
128
|
2. A linear persisted session is forked into the target worktree.
|
|
144
|
-
If `/tree`
|
|
129
|
+
If `/tree` points at an older branch, only that active branch's documented session entries are written to the target.
|
|
130
|
+
Switching therefore cannot jump to a newer serialized leaf.
|
|
145
131
|
3. Pi tears down the old cwd-bound runtime and creates the target runtime.
|
|
146
132
|
4. The extension reports success only through the fresh replacement-session context.
|
|
147
133
|
|
|
148
134
|
If the current session is completely empty, the extension creates a valid empty Pi session for the target.
|
|
149
|
-
|
|
135
|
+
For an ephemeral session created with `--no-session`, the extension copies the active conversation branch into a persisted target session.
|
|
136
|
+
This preserves context across the workspace switch.
|
|
150
137
|
|
|
151
|
-
|
|
152
|
-
|
|
138
|
+
If switching fails after Add, the extension retains the successfully created Git worktree.
|
|
139
|
+
If Pi prepared a target session before the failure, it retains that session too.
|
|
140
|
+
Resolve the reported Pi or session issue, then run `/worktree` and choose **Switch worktree**.
|
|
153
141
|
|
|
154
142
|
## 🛡️ Safety boundaries
|
|
155
143
|
|
|
156
144
|
- The main worktree and current worktree cannot be removed.
|
|
157
145
|
- Locked or stale worktrees cannot be removed through this extension.
|
|
158
146
|
- 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
|
|
147
|
+
Sparse-checkout-managed `skip-worktree` entries outside the active sparsity rules are allowed when Git's rule checker confirms them.
|
|
148
|
+
Clear other intentional index flags before removing the worktree.
|
|
160
149
|
- Ignored-only files and directories do not block removal.
|
|
161
150
|
The confirmation lists them, and the extension rechecks the exact ignored inventory before Git deletes the worktree.
|
|
162
151
|
- A detached HEAD must be reachable from a local branch, tag, or remote ref before removal or prune.
|
|
163
152
|
- 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
|
|
153
|
+
Historical commits reachable only through this administrative recovery state are listed by full OID in the destructive confirmation.
|
|
154
|
+
Approval removes those recovery pointers, so Git may later garbage-collect the commits.
|
|
165
155
|
Create a branch or tag instead when any listed commit should survive.
|
|
166
156
|
- Staged-only administrative index state, a missing attached branch ref, or an unreachable current detached HEAD still blocks prune without an override.
|
|
167
157
|
- Removal never deletes a branch and never uses `--force`.
|
|
168
158
|
- 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.
|
|
169
|
-
- Prune
|
|
159
|
+
- Prune runs `git worktree prune --dry-run --verbose`, inspects candidates omitted from porcelain, and shows the result before confirmation.
|
|
160
|
+
After confirmation, it rechecks the exact preview and recovery-risk set before pruning with Git's default expiry.
|
|
170
161
|
Remove likewise rechecks worktree identity, inventory, administrative path, and the approved recovery-risk set before mutation.
|
|
171
162
|
- The status browser uses only local Git state and never fetches a remote; its cards never authorize Remove or Prune.
|
|
172
163
|
- The extension does not commit, push, fetch, rebase, repair, move, lock, or unlock worktrees.
|
|
173
164
|
|
|
174
|
-
|
|
165
|
+
Status is an on-demand local snapshot of each worktree's state, full HEAD, working-tree counts, upstream divergence, and last commit.
|
|
166
|
+
Unavailable worktrees remain visible with a reason.
|
|
167
|
+
A missing upstream means **not configured**, not proof that no commits are unpushed.
|
|
168
|
+
Snapshots can become stale immediately and never replace the stricter Remove and Prune checks.
|
|
169
|
+
|
|
170
|
+
Use Git directly for force removal, branch deletion, custom prune expiry, detach or orphan creation, move, repair, lock, unlock, and remote refresh operations.
|
|
175
171
|
|
|
176
172
|
## 🚧 Limitations
|
|
177
173
|
|
|
@@ -184,40 +180,20 @@ Use Git directly when you intentionally need force removal, branch deletion, cus
|
|
|
184
180
|
|
|
185
181
|
```text
|
|
186
182
|
packages/pi-worktree/
|
|
187
|
-
├── src/
|
|
188
|
-
│ ├── index.ts
|
|
189
|
-
│
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
│ ├── status.ts
|
|
194
|
-
│ └── worktree.ts
|
|
195
|
-
├── dist/ # Generated source-mapped Jiti runtime
|
|
196
|
-
├── scripts/
|
|
197
|
-
│ └── build-runtime.mjs
|
|
198
|
-
├── test/
|
|
199
|
-
│ ├── add-command.test.ts
|
|
200
|
-
│ ├── command-test-support.ts
|
|
201
|
-
│ ├── command.test.ts
|
|
202
|
-
│ ├── build-runtime.test.ts
|
|
203
|
-
│ ├── git.integration.test.ts
|
|
204
|
-
│ ├── git.test.ts
|
|
205
|
-
│ ├── remove-ignored-command.test.ts
|
|
206
|
-
│ ├── session.test.ts
|
|
207
|
-
│ ├── settings-command.test.ts
|
|
208
|
-
│ ├── settings.test.ts
|
|
209
|
-
│ ├── status-command.test.ts
|
|
210
|
-
│ └── status.test.ts
|
|
211
|
-
├── package.json
|
|
212
|
-
├── README.md
|
|
213
|
-
├── LICENSE
|
|
214
|
-
└── tsconfig.json
|
|
183
|
+
├── src/ # Authoritative implementation and helpers
|
|
184
|
+
│ ├── index.ts # Thin Pi entrypoint
|
|
185
|
+
│ └── worktree.ts # Worktree manager and lifecycle
|
|
186
|
+
├── dist/ # Generated Jiti runtime
|
|
187
|
+
├── scripts/build-runtime.mjs # Runtime builder
|
|
188
|
+
└── test/ # Behavior and lifecycle coverage
|
|
215
189
|
```
|
|
216
190
|
|
|
191
|
+
The generated runtime is built from `src/index.ts` and does not import back into `src`.
|
|
192
|
+
|
|
217
193
|
## 🔎 Keywords
|
|
218
194
|
|
|
219
195
|
`pi-package`, `pi-extension`, `git`, `worktree`, `workspace`, `session`
|
|
220
196
|
|
|
221
197
|
## 📄 License
|
|
222
198
|
|
|
223
|
-
MIT
|
|
199
|
+
[MIT](./LICENSE)
|