@stellar_ai/mcp_fossil_scm 0.1.1 → 0.1.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.
Files changed (55) hide show
  1. package/LICENSE +28 -0
  2. package/README.md +140 -113
  3. package/dist/capabilities.js +6 -7
  4. package/dist/cli.js +28 -24
  5. package/dist/config.js +7 -32
  6. package/dist/core/fossil.js +67 -79
  7. package/dist/core/gitignore.js +136 -0
  8. package/dist/core/sql.js +3 -2
  9. package/dist/index.js +8 -7
  10. package/dist/prompts.js +167 -0
  11. package/dist/server.js +6 -5
  12. package/dist/tools/admin.js +454 -86
  13. package/dist/tools/chat.js +22 -26
  14. package/dist/tools/common.js +14 -5
  15. package/dist/tools/forum.js +37 -29
  16. package/dist/tools/tickets.js +32 -11
  17. package/dist/tools/version-control.js +880 -105
  18. package/dist/tools/wiki.js +17 -18
  19. package/docs/README.md +31 -0
  20. package/docs/admin.md +663 -0
  21. package/docs/chat.md +152 -0
  22. package/docs/forum.md +146 -0
  23. package/docs/prompts.md +39 -0
  24. package/docs/tickets.md +179 -0
  25. package/docs/vcs.md +1089 -0
  26. package/docs/wiki.md +140 -0
  27. package/package.json +11 -6
  28. package/dist/capabilities.d.ts +0 -32
  29. package/dist/capabilities.js.map +0 -1
  30. package/dist/cli.d.ts +0 -27
  31. package/dist/cli.js.map +0 -1
  32. package/dist/config.d.ts +0 -27
  33. package/dist/config.js.map +0 -1
  34. package/dist/core/fossil.d.ts +0 -104
  35. package/dist/core/fossil.js.map +0 -1
  36. package/dist/core/sql.d.ts +0 -29
  37. package/dist/core/sql.js.map +0 -1
  38. package/dist/index.d.ts +0 -2
  39. package/dist/index.js.map +0 -1
  40. package/dist/server.d.ts +0 -13
  41. package/dist/server.js.map +0 -1
  42. package/dist/tools/admin.d.ts +0 -3
  43. package/dist/tools/admin.js.map +0 -1
  44. package/dist/tools/chat.d.ts +0 -10
  45. package/dist/tools/chat.js.map +0 -1
  46. package/dist/tools/common.d.ts +0 -9
  47. package/dist/tools/common.js.map +0 -1
  48. package/dist/tools/forum.d.ts +0 -3
  49. package/dist/tools/forum.js.map +0 -1
  50. package/dist/tools/tickets.d.ts +0 -8
  51. package/dist/tools/tickets.js.map +0 -1
  52. package/dist/tools/version-control.d.ts +0 -3
  53. package/dist/tools/version-control.js.map +0 -1
  54. package/dist/tools/wiki.d.ts +0 -3
  55. package/dist/tools/wiki.js.map +0 -1
package/docs/vcs.md ADDED
@@ -0,0 +1,1089 @@
1
+ # VCS 能力(`-c v`)工具說明
2
+
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後。所有行為都在 fossil 2.21 上實測。
4
+
5
+ `-c v` 註冊 40 個工具;要連 admin 一起用 `-c av`。
6
+
7
+ ---
8
+
9
+ ## 1. 能力概覽
10
+
11
+ | 工具 | 對應的 fossil 命令 |
12
+ | --- | --- |
13
+ | `fossil_status` | `fossil status` + `fossil extra` |
14
+ | `fossil_diff` | `fossil diff` |
15
+ | `fossil_cat` | `fossil cat <file> [-r REV]` |
16
+ | `fossil_finfo` | `fossil finfo [-i\|-s\|-p\|-l] <file>` |
17
+ | `fossil_ls` | `fossil ls [-r REV] [--age] [-v] [-t] [--hash]` |
18
+ | `fossil_extras` | `fossil extras` |
19
+ | `fossil_timeline` | `fossil timeline -n N` |
20
+ | `fossil_info` | `fossil info [target]` |
21
+ | `fossil_add` | `fossil add [-f] <files>` / `fossil add --reset` |
22
+ | `fossil_rm` | `fossil rm [--hard\|--soft] <files>` / `fossil rm --reset` |
23
+ | `fossil_mv` | `fossil mv --hard <old> <new>` |
24
+ | `fossil_addremove` | `fossil addremove` |
25
+ | `fossil_commit` | `fossil commit -m <msg>` |
26
+ | `fossil_revert` | `fossil revert [-r REV] [files]` |
27
+ | `fossil_clean` | `fossil clean -n\|-f\|--no-prompt` |
28
+ | `fossil_stash` | `fossil stash <action>` |
29
+ | `fossil_tag` | `fossil tag ls\|add\|cancel` |
30
+ | `fossil_branch` | `fossil branch ls\|new` |
31
+ | `fossil_merge` | `fossil merge [--integrate] [-n] <x>` |
32
+ | `fossil_update` | `fossil update [target]` |
33
+ | `fossil_undo` | `fossil undo [-n]` |
34
+ | `fossil_changes` | `fossil changes` |
35
+ | `fossil_annotate` | `fossil blame\|annotate\|praise <file>` |
36
+ | `fossil_grep` | `fossil grep <pattern> <files>` |
37
+ | `fossil_whatis` | `fossil whatis <name>` |
38
+ | `fossil_merge_base` | `fossil merge-base <v1> <v2>` |
39
+ | `fossil_leaves` | `fossil leaves` |
40
+ | `fossil_descendants` | `fossil descendants [checkin]` |
41
+ | `fossil_unpublished` | `fossil unpublished` |
42
+ | `fossil_search` | `fossil search [-a] [-n N] [-W WIDTH] <pattern>` |
43
+ | `fossil_artifact` | `fossil artifact <hash>` |
44
+ | `fossil_describe` | `fossil describe [version]` |
45
+ | `fossil_archive` | `fossil tarball\|zip <version> <outfile>` |
46
+ | `fossil_unversioned` | `fossil unversioned list\|cat\|add\|remove\|touch` |
47
+ | `fossil_touch` | `fossil touch [--now\|-c\|-C] [files]` |
48
+ | `fossil_amend` | `fossil amend <check-in> --comment/--tag/…` |
49
+ | `fossil_patch` | `fossil patch create\|diff\|apply <file>` |
50
+ | `fossil_bisect` | `fossil bisect good\|bad\|skip\|next\|log\|chart\|options\|reset\|run` |
51
+ | `fossil_sql` | `fossil sql --readonly -json <query>` |
52
+ | `fossil_ignore_from_gitignore` | 讀 `.gitignore`,寫 `.fossil-settings/ignore-glob` |
53
+
54
+ 標了 `destructiveHint: true` 的是 `fossil_rm` / `fossil_revert` / `fossil_clean` / `fossil_update` / `fossil_undo`:
55
+ 它們會覆蓋工作區內容,呼叫方應先確認,或先跑 `dry_run` / `-n` 預覽。除了 `fossil_sql` 可用 `repository` 直接查詢,其餘工具都需要 check-out(見 §2)。
56
+
57
+ ---
58
+
59
+ ## 2. 通用約定
60
+
61
+ - **`workspace`**:所有工具都接受,語義見 `docs/admin.md` §2.1。倉庫檔案不由這些工具指定——
62
+ 它們作用於 `workspace` 裡已經 open 的 check-out(`.fslckout`)。
63
+ - **沒有 check-out 時報錯**:fossil 原文 `use --repository or -R to specify the repository database`,
64
+ 包裝為 `isError: true`。
65
+ - **失敗格式** 與 admin 一致:
66
+
67
+ ```
68
+ ERROR: Fossil command failed (exit code 1).
69
+ <fossil stderr/stdout 原文>
70
+ COMMAND: fossil <argv>
71
+ WORKSPACE: /tmp/vd
72
+ ```
73
+
74
+ - **空輸出**:不同工具給不同的提示(`No differences found.` / `No untracked files.` / `No events.` 等),
75
+ 見各工具小節。
76
+ - **路徑參數不插入 `--`**:以 `-` 開頭的檔名會被 fossil 當成選項,需要呼叫方自行加 `./` 前綴。
77
+
78
+ ---
79
+
80
+ ## 3. 只讀工具
81
+
82
+ ### 3.1 `fossil_status`
83
+
84
+ 一次呼叫併發執行兩條命令,輸出分兩段:
85
+
86
+ ```bash
87
+ fossil status [-b]
88
+ fossil extra [--dotfiles] [--ignore GLOBS] # cwd = workspace,兩條並行
89
+ ```
90
+
91
+ | 參數 | 類型 | 必填/預設 | 說明 |
92
+ | --- | --- | --- | --- |
93
+ | `brief` | boolean | `false` | `-b`:只輸出狀態關鍵字 |
94
+ | `dotfiles` | boolean | `false` | `extra` 時包含點檔案 |
95
+ | `ignore` | string | — | `--ignore` 逗號分隔的 glob |
96
+ | `workspace` | string | 見 admin §2.1 | — |
97
+
98
+ 真實輸出(乾淨 check-out):
99
+
100
+ ```
101
+ --- STATUS ---
102
+ repository: /tmp/vd/r.fossil
103
+ local-root: /tmp/vd/
104
+ config-db: /home/stellar/.fossil
105
+ checkout: eed3d7e723ee595d62ce60cc2f8ed539feed8f03 2026-11-17 00:21:35 UTC
106
+ parent: f3b4b5026147f144c8b69273a731a1404a26132d 2026-11-17 00:21:35 UTC
107
+ tags: trunk
108
+ comment: first (user: stellar)
109
+
110
+ --- UNTRACKED (EXTRA) ---
111
+ (no output)
112
+ ```
113
+
114
+ 注意:`fossil status` 本身不列未跟蹤檔案,未跟蹤檔案在 `--- UNTRACKED (EXTRA) ---` 段,兩段來自兩條命令。
115
+
116
+ ### 3.2 `fossil_diff`
117
+
118
+ ```bash
119
+ fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
120
+ [-c N] [-y] [-v] [--undo] [-w] [files...]
121
+ ```
122
+
123
+ | 參數 | 類型 | 必填/預設 | 說明 |
124
+ | --- | --- | --- | --- |
125
+ | `from_version` | string | — | `--from` 起始版本 |
126
+ | `to_version` | string | — | `--to` 結束版本 |
127
+ | `branch` | string | — | `--branch` 跨分支比較 |
128
+ | `checkin` | string | — | `-ci` 只比較該 check-in 帶來的改動 |
129
+ | `files` | string[] | — | 只 diff 這些檔案 |
130
+ | `brief` | boolean | `false` | `--brief` 只列檔名 |
131
+ | `stat` | boolean | `false` | `--numstat` 只印新增/刪除行數 |
132
+ | `context` | number | — | `-c` 每個改動的上下文行數(0..100) |
133
+ | `side_by_side` | boolean | `false` | `-y` 並排顯示 |
134
+ | `verbose` | boolean | `false` | `-v` 完整印出新增或刪除的檔案內容 |
135
+ | `undo` | boolean | `false` | `--undo` 與 undo 緩衝區比較 |
136
+ | `ignore_whitespace` | boolean | `false` | `-w` |
137
+ | `workspace` | string | 見 admin §2.1 | — |
138
+
139
+ 不給版本時是“工作區 vs 最近一次 check-in”。版本名寫錯時 fossil 報
140
+ `cannot resolve name: tip-1`(`tip-1` 不是合法表示式,用雜湊前綴或 `tip`)。空輸出 → `No differences found.`
141
+
142
+ ### 3.3 `fossil_cat`
143
+
144
+ ```bash
145
+ fossil cat <file> [-r REV]
146
+ ```
147
+
148
+ 列印檔案內容。`revision` 省略時讀當前 check-out 的版本。
149
+
150
+ | 參數 | 類型 | 必填/預設 | 說明 |
151
+ | --- | --- | --- | --- |
152
+ | `file` | string | **必填** | 要列印的檔案 |
153
+ | `revision` | string | — | 指定 check-in 或版本(`-r`) |
154
+ | `workspace` | string | 見 admin §2.1 | — |
155
+
156
+ ### 3.4 `fossil_finfo`
157
+
158
+ ```bash
159
+ fossil finfo [-l|-i|-s|-p] [-b] [-n N] [--offset P] [-r REV] [-v] <file>
160
+ ```
161
+
162
+ | 參數 | 類型 | 必填/預設 | 說明 |
163
+ | --- | --- | --- | --- |
164
+ | `file` | string | **必填** | 要查的檔案 |
165
+ | `mode` | `log` / `id` / `status` / `print` | `log` | `log` 變更歷史、`id` 工件事實、`status` 單行狀態、`print` 檔案內容 |
166
+ | `brief` | boolean | `false` | 每筆變更一行(`-b`,僅 `log`) |
167
+ | `limit` | number | `20` | 顯示筆數(`-n`,1..1000,僅 `log`) |
168
+ | `offset` | number | — | 跳過的筆數(`--offset`,僅 `log`) |
169
+ | `revision` | string | — | `id` / `print` 描述的版本(`-r`) |
170
+ | `verbose` | boolean | `false` | `id` 模式列出所有使用該檔案的 check-in(`-v`) |
171
+ | `workspace` | string | 見 admin §2.1 | — |
172
+
173
+ 真實輸出:
174
+
175
+ ```
176
+ $ fossil finfo annotate-me.txt
177
+ History for annotate-me.txt
178
+ 2026-11-17 [eed3d7e723] first (user: stellar, artifact: [331099e57f], branch: trunk)
179
+
180
+ $ fossil finfo -i a.txt
181
+ artifact: 17995fe087b0f2ff8b60d47f4005eb1fbab7aa3bc9e3061b09f4a446a5f5dcb8
182
+ size: 8 bytes
183
+ mtime: 2026-11-17 02:24:18
184
+ file: a.txt
185
+ part of [5f3e19ce7a] by stellar on 2026-11-17 02:24:18
186
+ second
187
+
188
+ $ fossil finfo -s a.txt
189
+ unchanged 5f3e19ce7a
190
+ ```
191
+
192
+ `-n` / `--offset` / `-b` 只在 `log` 模式送出;fossil 對 `finfo -i -n 20` 會回
193
+ `unrecognized command-line option or missing argument: -n`。
194
+
195
+ ### 3.5 `fossil_extras`
196
+
197
+ ```bash
198
+ fossil extras [--dotfiles] [--ignore GLOBS] [--abs-paths|--rel-paths] [--header] [--case-sensitive 1|0]
199
+ ```
200
+
201
+ | 參數 | 類型 | 必填/預設 | 說明 |
202
+ | --- | --- | --- | --- |
203
+ | `dotfiles` | boolean | `false` | 一併列出 `.` 開頭的檔案(`--dotfiles`) |
204
+ | `ignore` | string | — | 忽略符合這些 glob 的檔案(`--ignore`) |
205
+ | `abs_paths` | boolean | `false` | 印絕對路徑(`--abs-paths`) |
206
+ | `rel_paths` | boolean | `false` | 印相對於**命令執行目錄**的路徑(`--rel-paths`) |
207
+ | `header` | boolean | `false` | 清單前面加一行倉庫名(`--header`) |
208
+ | `case_sensitive` | boolean | 依設定 | 覆寫大小寫敏感設定(`--case-sensitive 1\|0`) |
209
+ | `workspace` | string | 見 admin §2.1 | — |
210
+
211
+ 空輸出 → `No untracked files.`。Node 專案建議提交 `.fossil-settings/ignore-glob`(見 admin §6.3)。
212
+
213
+ ### 3.6 `fossil_timeline`
214
+
215
+ ```bash
216
+ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [-F FORMAT] [-v]
217
+ ```
218
+
219
+ | 參數 | 類型 | 必填/預設 | 說明 |
220
+ | --- | --- | --- | --- |
221
+ | `limit` | number | `20` | 條目數(`-n`,1..2000) |
222
+ | `path` | string | — | 只看動到這個檔案/目錄的事件(`-p`) |
223
+ | `type_filter` | string | — | 事件類型(`-t`):`ci` 提交、`t` 工單、`w` wiki、`f` 論壇、`e` 技術註記 |
224
+ | `branch` | string | — | 只看這個分支(`-b`) |
225
+ | `current_branch` | boolean | `false` | 只看當前分支(`-c`) |
226
+ | `when` | enum | — | `before` / `after` / `descendants` / `children` / `ancestors` / `parents`,配合 `checkin` |
227
+ | `checkin` | string | — | `when` 相對的 check-in 雜湊或日期 |
228
+ | `format` | string | — | 條目格式(`-F`):`oneline` / `medium` / `full` 或 `%h %d %c` 這類樣板 |
229
+ | `verbose` | boolean | `false` | 每個 check-in 後面列出變更的檔案(`-v`) |
230
+ | `workspace` | string | 見 admin §2.1 | — |
231
+
232
+ 真實輸出(`limit: 3`):
233
+
234
+ ```
235
+ === 2026-11-17 ===
236
+ 00:21:35 [39cc6204fa] *CURRENT* second (user: stellar tags: trunk)
237
+ 00:21:35 [eed3d7e723] first (user: stellar tags: trunk)
238
+ 00:21:35 [f3b4b50261] initial empty check-in (user: stellar tags: trunk)
239
+ +++ no more data (3) +++
240
+ ```
241
+
242
+ ### 3.7 `fossil_info`
243
+
244
+ ```bash
245
+ fossil info [target]
246
+ ```
247
+
248
+ `target` 可以是檔名、check-in 雜湊、分支名;省略時給倉庫/check-out 元資訊(真實輸出見 §3.1 的 STATUS 段同源)。
249
+ 空字串會被當作未提供(`clean()` 處理)。
250
+
251
+ | 參數 | 類型 | 必填/預設 | 說明 |
252
+ | --- | --- | --- | --- |
253
+ | `target` | string | — | 檔名、check-in 雜湊或分支名 |
254
+ | `workspace` | string | 見 admin §2.1 | — |
255
+
256
+ ---
257
+ ### 3.8 `fossil_changes`
258
+
259
+ ```bash
260
+ fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta]
261
+ [--classify] [--no-merge] [--dotfiles] [--abs-paths] [files...]
262
+ ```
263
+
264
+ 純工作區的變更清單(不讀 `extras`,所以未跟蹤檔案不會出現)。
265
+
266
+ | 參數 | 類型 | 必填/預設 | 說明 |
267
+ | --- | --- | --- | --- |
268
+ | `files` | string[] | — | 只報告這些路徑 |
269
+ | `edited` / `updated` / `added` / `deleted` / `renamed` / `conflict` / `meta` | boolean | `false` | 變更類型過濾,可疊加 |
270
+ | `classify` | boolean | `false` | 每行前面加變更類型 |
271
+ | `no_merge` | boolean | `false` | 隱藏 merge 貢獻者 |
272
+ | `dotfiles` | boolean | `false` | 包含以 `.` 開頭的未管理檔案 |
273
+ | `absolute_paths` | boolean | `false` | 輸出絕對路徑 |
274
+ | `workspace` | string | 見 admin §2.1 | — |
275
+
276
+ 真實輸出(`classify: true`):
277
+
278
+ ```
279
+ EDITED src/core/fossil.ts
280
+ ADDED src/tools/notes.ts
281
+ ```
282
+
283
+ 空輸出 → `No changes.`
284
+
285
+ 變更偵測靠 mtime + 大小,改動若落在上一次 commit 的同一秒內,`changes` / `status` / `diff` 都還看不到,
286
+ `touch` 檔案後才出現。
287
+
288
+ ### 3.9 `fossil_annotate`
289
+
290
+ ```bash
291
+ fossil blame|annotate|praise <file> [-r REV] [-o ORIGIN] [-n LIMIT] [--filevers] [-l] [-w] [-Z]
292
+ ```
293
+
294
+ | 參數 | 類型 | 必填/預設 | 說明 |
295
+ | --- | --- | --- | --- |
296
+ | `file` | string | 必填 | 相對 check-out 的路徑 |
297
+ | `command` | `blame` \| `annotate` \| `praise` | `blame` | blame/praise 印作者,annotate 印行號 |
298
+ | `revision` | string | — | `-r` 要標註的檔案版本所在的 check-in |
299
+ | `origin` | string | — | `-o` 往哪個版本方向追(如 `trunk`) |
300
+ | `limit` | string | — | `-n` 版本上限:數量、`2s` 這種時長,或 `none` |
301
+ | `filevers` | boolean | `false` | `--filevers` 用檔案版本而非 check-in 版本 |
302
+ | `log` | boolean | `false` | `-l` 列出分析過的每個版本 |
303
+ | `ignore_all_space` / `ignore_trailing_space` | boolean | `false` | `-w` / `-Z` |
304
+ | `workspace` | string | 見 admin §2.1 | — |
305
+
306
+ 真實輸出:
307
+
308
+ ```
309
+ 87b30e7c6a 2026-11-17 1: alpha # blame / praise
310
+ 87b30e7c6a 2026-11-17 1: alpha # annotate 在行號後多一個冒號
311
+ ```
312
+
313
+ `fossil blame` 的行是 `<hash> <date> <line>: <text>`,praise/blame 的 `<text>` 是 `作者: 內容`。
314
+
315
+ ### 3.10 `fossil_grep`
316
+
317
+ ```bash
318
+ fossil grep [-i] [-c] [-l] [--once] [-v] [-s] [--verbose] <pattern> <files...>
319
+ ```
320
+
321
+ 在檔案的**歷史版本**裡搜尋(由新到舊),不是工作區。
322
+
323
+ | 參數 | 類型 | 必填/預設 | 說明 |
324
+ | --- | --- | --- | --- |
325
+ | `pattern` | string | 必填 | POSIX 延伸正規表示式 |
326
+ | `files` | string[] | 必填,至少 1 | 要搜的檔案 |
327
+ | `ignore_case` | boolean | `false` | `-i` |
328
+ | `count` | boolean | `false` | `-c` 只印匹配檔案數 |
329
+ | `files_with_matches` | boolean | `false` | `-l` 每個匹配檔案印一個 artifact |
330
+ | `once` | boolean | `false` | `--once` 第一次命中就停 |
331
+ | `invert_match` | boolean | `false` | `-v` 只列沒有命中的檔案 |
332
+ | `no_messages` | boolean | `false` | `-s` 靜音讀檔訊息 |
333
+ | `verbose` | boolean | `false` | `--verbose` 邊分析邊回報 |
334
+ | `workspace` | string | 見 admin §2.1 | — |
335
+
336
+ 真實輸出(`fossil grep alpha a.txt`):
337
+
338
+ ```
339
+ == 2026-11-17 02:06 a.txt f3a27a552e checkin 86454b6394
340
+ 1:alpha
341
+ ```
342
+
343
+ 空輸出 → `No matches.`
344
+
345
+ ### 3.11 `fossil_whatis`
346
+
347
+ ```bash
348
+ fossil whatis [-f] [--type ci|t|w|g|e] [-v] <name>
349
+ ```
350
+
351
+ 把名字(標籤、分支、雜湊前綴、檔名)解析成 artifact。
352
+
353
+ | 參數 | 類型 | 必填/預設 | 說明 |
354
+ | --- | --- | --- | --- |
355
+ | `name` | string | 必填 | 要解析的名字 |
356
+ | `file` | boolean | `false` | `-f` 把 `name` 當檔名,查內容雜湊 |
357
+ | `type` | `ci` \| `t` \| `w` \| `g` \| `e` | — | `--type` 只匹配該 artifact 類型 |
358
+ | `verbose` | boolean | `false` | `-v` 附內部 record id |
359
+ | `workspace` | string | 見 admin §2.1 | — |
360
+
361
+ 真實輸出(`name: 'tip'`):
362
+
363
+ ```
364
+ name: tip
365
+ artifact: 86454b6394a3b2d2e2c0e2c7a6ee2f4e0b3b5a1a5f2e0d6a0e0f0a1b2c3d4e5f
366
+ size: 340 bytes
367
+ tags: trunk
368
+ type: Check-in by stellar on 2026-11-17 02:06:59
369
+ comment: second commit
370
+ ```
371
+
372
+ ### 3.12 `fossil_merge_base`
373
+
374
+ ```bash
375
+ fossil merge-base [--ignore-merges] <v1> <v2> [...]
376
+ ```
377
+
378
+ | 參數 | 類型 | 必填/預設 | 說明 |
379
+ | --- | --- | --- | --- |
380
+ | `versions` | string[] | 必填,至少 2 | 第一個是主版本 |
381
+ | `ignore_merges` | boolean | `false` | `--ignore-merges` 找名稱 pivot 時忽略 merge arc |
382
+ | `workspace` | string | 見 admin §2.1 | — |
383
+
384
+ 真實輸出:`pivot=86454b6394a3b2d2e2c0e2c7a6ee2f4e0b3b5a1a5f2e0d6a0e0f0a1b2c3d4e5f`
385
+ (無共同祖先時 fossil 回 `merge-base: no common ancestor` 並以非零結束)。
386
+
387
+ ### 3.13 `fossil_leaves`
388
+
389
+ ```bash
390
+ fossil leaves [-a] [-c] [-m] [--bybranch] [-W WIDTH]
391
+ ```
392
+
393
+ | 參數 | 類型 | 必填/預設 | 說明 |
394
+ | --- | --- | --- | --- |
395
+ | `all` | boolean | `false` | `-a` 連已關閉的 leaf 一起列 |
396
+ | `closed` | boolean | `false` | `-c` 只列已關閉的 leaf |
397
+ | `multiple` | boolean | `false` | `-m` 只列有多個 leaf 的分支 |
398
+ | `by_branch` | boolean | `false` | `--bybranch` 按分支名排序 |
399
+ | `width` | number | — | `-W` 輸出寬度,`0` 表示一行一筆 |
400
+ | `workspace` | string | 見 admin §2.1 | — |
401
+
402
+ 真實輸出:
403
+
404
+ ```
405
+ (1) 2026-11-17 02:06:59 [86454b6394] second commit (user: stellar tags: trunk)
406
+ ```
407
+
408
+ ### 3.14 `fossil_descendants`
409
+
410
+ ```bash
411
+ fossil descendants [<checkin>] [-W WIDTH]
412
+ ```
413
+
414
+ 列出某個 check-in 的所有 leaf 後代;`checkin` 省略時用當前 check-out 的版本。
415
+
416
+ | 參數 | 類型 | 必填/預設 | 說明 |
417
+ | --- | --- | --- | --- |
418
+ | `checkin` | string | — | 起始 check-in;省略時用當前 check-out 的版本 |
419
+ | `width` | number | — | 輸出寬度(`-W`);`0` 表示一行一筆 |
420
+ | `workspace` | string | 見 admin §2.1 | — |
421
+
422
+ 真實輸出:
423
+
424
+ ```
425
+ === 2026-11-17 ===
426
+ 02:06:59 [86454b6394] *CURRENT* second commit (user: stellar tags: trunk)
427
+ +++ end of timeline (1) +++
428
+ ```
429
+
430
+ ### 3.15 `fossil_unpublished`
431
+
432
+ ```bash
433
+ fossil unpublished [--all]
434
+ ```
435
+
436
+ | 參數 | 類型 | 必填/預設 | 說明 |
437
+ | --- | --- | --- | --- |
438
+ | `all` | boolean | `false` | `--all` 連非 check-in 的私有 artifact 一起列 |
439
+ | `workspace` | string | 見 admin §2.1 | — |
440
+
441
+ 從未 push 過的 check-in 才有輸出,否則 → `No unpublished artifacts.`
442
+
443
+ ---
444
+
445
+ ### 3.16 `fossil_ignore_from_gitignore`
446
+
447
+ 把 `.gitignore` 的規則翻成 `ignore-glob` 認得的 glob 清單,可選擇寫成 `.fossil-settings/ignore-glob`。
448
+
449
+ | 參數 | 類型 | 必填/預設 | 說明 |
450
+ | --- | --- | --- | --- |
451
+ | `source` | string | `.gitignore` | 要轉換的檔案,相對 workspace |
452
+ | `write` | boolean | `false` | 寫入 `.fossil-settings/ignore-glob` |
453
+ | `overwrite` | boolean | `false` | 覆蓋已存在的 `.fossil-settings/ignore-glob` |
454
+ | `workspace` | string | 見 admin §2.1 | — |
455
+
456
+ | `.gitignore` 寫法 | 產出的 glob | 原因 |
457
+ | --- | --- | --- |
458
+ | `# 註解`、空行 | 丟棄 | `ignore-glob` 只有樣式 |
459
+ | `!name` | 略過,並在 `NOTE:` 列出 | `ignore-glob` 沒有否定 |
460
+ | `name` | `name`、`*/name` | 沒有斜線的規則在 git 是任意深度,fossil 比對完整路徑 |
461
+ | `*.log` | `*.log` | 開頭就是萬用字元,fossil 的 `*` 已跨目錄 |
462
+ | `dir/` | `dir` | fossil 命中目錄即略過整個子樹 |
463
+ | `/name` | `name` | 錨定在該 `.gitignore` 所在目錄,前綴沿用目錄名 |
464
+ | `a/**/b` | `a/b`、`a/*/b` | `**` 展開成零層與多層兩條 |
465
+ | 含逗號、空白、引號 | 用 `'…'` 或 `"…"` 包住 | fossil 的清單以空白與逗號分隔 |
466
+
467
+ 真實輸出:
468
+
469
+ ```
470
+ Converted 5 rules from .gitignore into 7 ignore-glob patterns.
471
+
472
+ node_modules
473
+ */node_modules
474
+ *.log
475
+ doc/gen
476
+ doc/*/gen
477
+ dist
478
+ */dist
479
+
480
+ NOTE: `**` in doc/**/gen expanded to 2 patterns.
481
+ NOTE: negation !keep.log skipped: ignore-glob has no negation, so the path stays visible.
482
+ ```
483
+
484
+ `write: true` 時第 2 行是 `Wrote .fossil-settings/ignore-glob.`;檔案落地後立刻生效,`fossil_extras` 不再列出被忽略的路徑。
485
+
486
+ ---
487
+
488
+ ### 3.17 `fossil_ls`
489
+
490
+ ```bash
491
+ fossil ls ?PATHS ...? [-r REV] [--age] [-v] [-t] [--hash]
492
+ ```
493
+
494
+ | 參數 | 類型 | 必填/預設 | 說明 |
495
+ | --- | --- | --- | --- |
496
+ | `paths` | string[] | — | 只列出這些路徑(目錄會展開成子項) |
497
+ | `revision` | string | — | 列出指定 check-in 的檔案(`-r`) |
498
+ | `age` | boolean | `false` | 顯示提交時間(`--age`) |
499
+ | `verbose` | boolean | `false` | 額外資訊:無 `-r` 時是變更狀態,有 `-r` 時是提交時間與大小(`-v`) |
500
+ | `time_order` | boolean | `false` | 按時間排序(`-t`);搭配 `--age` 或 `-r` 時按提交時間 |
501
+ | `hash` | boolean | `false` | 用雜湊(而非大小+mtime)判斷檔案狀態(`--hash`) |
502
+ | `workspace` | string | 見 admin §2.1 | — |
503
+
504
+ 真實輸出:
505
+
506
+ ```
507
+ $ fossil ls --age
508
+ 2026-11-17 02:24:18 a.txt
509
+
510
+ $ fossil ls -r tip
511
+ a.txt
512
+ ```
513
+
514
+ ### 3.18 `fossil_search`
515
+
516
+ ```bash
517
+ fossil search [-a] [-n N] [-W WIDTH] pattern
518
+ ```
519
+
520
+ | 參數 | 類型 | 必填/預設 | 說明 |
521
+ | --- | --- | --- | --- |
522
+ | `pattern` | string | — | 要搜尋的字詞;全部都要命中 |
523
+ | `all` | boolean | `false` | 輸出全部命中,而不是只給高分者(`--all`) |
524
+ | `limit` | number | — | 最多輸出幾筆(`-n`) |
525
+ | `width` | number | — | 輸出寬度,`0` 表示不折行(`-W`) |
526
+ | `workspace` | string | 見 admin §2.1 | — |
527
+
528
+ 真實輸出:
529
+
530
+ ```
531
+ $ fossil search second
532
+ === 2026-11-17 ===
533
+ 02:24:18 [5f3e19ce7a] *CURRENT* second
534
+ +++ no more data (1) +++
535
+ ```
536
+
537
+ 沒有命中時 fossil 只印 `+++ no more data (0) +++` 並以 0 結束,工具改寫成 `No matches.`。
538
+ 搜尋範圍是 timeline / event 的註解,不含檔案內容、文件或論壇文章。
539
+
540
+ ### 3.19 `fossil_artifact`
541
+
542
+ ```bash
543
+ fossil artifact <ARTIFACT-ID>
544
+ ```
545
+
546
+ | 參數 | 類型 | 必填/預設 | 說明 |
547
+ | --- | --- | --- | --- |
548
+ | `artifact` | string | — | 工件雜湊,可用唯一前綴 |
549
+ | `workspace` | string | 見 admin §2.1 | — |
550
+
551
+ 真實輸出(檔案版本工件):
552
+
553
+ ```
554
+ $ fossil artifact 17995fe087b0f2ff8b60d47f4005eb1fbab7aa3bc9e3061b09f4a446a5f5dcb8
555
+ hi
556
+ more
557
+ ```
558
+
559
+ 對 check-in 的雜湊則會印出 manifest 原文(`D`/`F`/`P`/`U` 等卡片行)。
560
+ 雜湊可由 `fossil_finfo { mode: "id" }`、`fossil_whatis` 或 `fossil_leaves` 取得。
561
+
562
+ ### 3.20 `fossil_describe`
563
+
564
+ ```bash
565
+ fossil describe ?VERSION? [--digits N] [--dirty] [--long] [--match GLOB]
566
+ ```
567
+
568
+ | 參數 | 類型 | 必填/預設 | 說明 |
569
+ | --- | --- | --- | --- |
570
+ | `version` | string | — | 要描述的版本;省略時為當前 check-out |
571
+ | `digits` | number | — | 雜湊位數(`--digits`,4..40) |
572
+ | `dirty` | boolean | `false` | 一併顯示是否有未提交改動(`--dirty`) |
573
+ | `long` | boolean | `false` | 即使三者可折疊也全部顯示(`--long`) |
574
+ | `match` | string | — | 只考慮符合此 glob 的非傳播標籤(`--match`) |
575
+ | `workspace` | string | 見 admin §2.1 | — |
576
+
577
+ 真實輸出:
578
+
579
+ ```
580
+ $ fossil describe # 沒有標籤的 check-in
581
+ 5f3e19ce7a
582
+ $ fossil describe 3c24269ef1 # 標籤就打在這個 check-in 上
583
+ smoke-tag
584
+ $ fossil describe 3c24269ef1 --long
585
+ smoke-tag-0-3c24269ef1 # <標籤>-<其後提交數>-<短雜湊>
586
+ ```
587
+
588
+ 標籤打在祖先 check-in 上時同樣是 `<標籤>-<N>-<短雜湊>`;`match` 限制參與計算的標籤 glob
589
+ (`match: '*'` 會把 `trunk` 這類傳播標籤也算進來)。
590
+
591
+ ### 3.21 `fossil_archive`
592
+
593
+ ```bash
594
+ fossil tarball <version> <outfile> [-l] [--name DIR] [-X GLOBLIST] [--include GLOBLIST]
595
+ fossil zip <version> <outfile> [-l] [--name DIR] [-X GLOBLIST] [--include GLOBLIST]
596
+ ```
597
+
598
+ | 參數 | 類型 | 必填/預設 | 說明 |
599
+ | --- | --- | --- | --- |
600
+ | `format` | `tarball` / `zip` | `tarball` | 產出的封存格式 |
601
+ | `version` | string | `tip` | 要封存的 check-in |
602
+ | `output` | string | — | 封存檔路徑(相對 `workspace`);省略時只列出檔案清單 |
603
+ | `name` | string | — | 封存檔內的頂層目錄名(`--name`) |
604
+ | `exclude` | string[] | — | 要排除的 glob(`-X`,以逗號串接) |
605
+ | `include` | string[] | — | 要保留的 glob(`--include`,以逗號串接) |
606
+ | `workspace` | string | 見 admin §2.1 | — |
607
+
608
+ 省略 `output` 時工具送出 `/dev/null -l`,只印出「如果產生封存檔會包含哪些檔案」;有 `output` 時輸出被改寫成
609
+ `Wrote <output> from <version>.`。
610
+
611
+ 真實輸出:
612
+
613
+ ```
614
+ $ fossil tarball tip /dev/null -l
615
+ probe_2026-11-17_022418_5f3e19ce7a/a.txt
616
+ ```
617
+
618
+ ```
619
+ $ fossil_archive { format: "zip", version: "tip", output: "snap.zip" }
620
+ Wrote snap.zip from tip.
621
+ ```
622
+
623
+ `--name` 省略時頂層目錄名由專案名、check-in 時間與 artifact id 組成;`--include` 與 `-X` 同時命中時以排除為準。
624
+
625
+ ### 3.22 `fossil_unversioned`
626
+
627
+ ```bash
628
+ fossil unversioned list [--glob PATTERN] [--like PATTERN]
629
+ fossil unversioned cat|add|remove|touch FILE ...
630
+ ```
631
+
632
+ | 參數 | 類型 | 必填/預設 | 說明 |
633
+ | --- | --- | --- | --- |
634
+ | `action` | `list` / `cat` / `add` / `remove` / `touch` | `list` | `list` 列出、`cat` 印內容、`add`/`remove` 改集合、`touch` 更新時間戳 |
635
+ | `files` | string[] | — | 動作套用的檔案 |
636
+ | `glob` | string | — | 只比對符合此 glob 的名字(`--glob`) |
637
+ | `like` | string | — | 只比對符合此模式的名字(`--like`) |
638
+ | `workspace` | string | 見 admin §2.1 | — |
639
+
640
+ unversioned file(UV-file)只保留最新版本、不保存歷史,變更不可撤銷。`action` 不是 `list` 時,
641
+ `files`、`glob`、`like` 至少要給一個,否則工具直接返回
642
+ `ERROR: action 'cat' needs \`files\`, \`glob\` or \`like\`.`(不 spawn fossil)。
643
+
644
+ 真實輸出:
645
+
646
+ ```
647
+ $ fossil_unversioned {}
648
+ No unversioned files.
649
+
650
+ $ fossil unversioned list
651
+ uv-note.txt 2026-11-17 10:41:02 12 bytes
652
+
653
+ $ fossil unversioned cat uv-note.txt
654
+ unversioned body
655
+ ```
656
+
657
+ ### 3.23 `fossil_touch`
658
+
659
+ ```bash
660
+ fossil touch [--now|-c|--checkin|-C|--checkout] [FILES...]
661
+ ```
662
+
663
+ | 參數 | 類型 | 必填/預設 | 說明 |
664
+ | --- | --- | --- | --- |
665
+ | `files` | string[] | — | 檔案或 glob;省略時套用所有受管理檔案 |
666
+ | `mode` | `now` / `checkin` / `checkout` | `now` | `--now` 目前時間、`-c` 該檔最後一次 check-in 的時間、`-C` 當前 check-out 的時間 |
667
+ | `workspace` | string | 見 admin §2.1 | — |
668
+
669
+ Fossil 用檔案大小與 mtime 判斷是否變更,所以在同一個時間戳內改檔案可能被忽略;`fossil_touch { mode: "now" }`
670
+ 強制重新掃描。指令本身沒有輸出。
671
+
672
+ ### 3.24 `fossil_amend`
673
+
674
+ ```bash
675
+ fossil amend <check-in> [-n] [-m COMMENT] [--author USER] [--date WHEN] [--tag TAG] [--cancel TAG]
676
+ [--branch NAME] [--hide] [--close]
677
+ ```
678
+
679
+ | 參數 | 類型 | 必填/預設 | 說明 |
680
+ | --- | --- | --- | --- |
681
+ | `checkin` | string | — | 要改的 check-in(`tip` 或雜湊) |
682
+ | `comment` | string | — | 換掉註解(`-m`) |
683
+ | `author` | string | — | 換掉作者(`--author`) |
684
+ | `date` | string | — | 換掉 check-in 時間,或 `now`(`--date`) |
685
+ | `tag` | string[] | — | 加上標籤(`--tag`,可重複) |
686
+ | `cancel` | string[] | — | 移除標籤(`--cancel`,可重複) |
687
+ | `branch` | string | — | 以此 check-in 開新分支(`--branch`) |
688
+ | `hide` | boolean | `false` | 從此 check-in 起隱藏分支(`--hide`) |
689
+ | `close` | boolean | `false` | 把這個 leaf 標為關閉(`--close`) |
690
+ | `dry_run` | boolean | `false` | 只印出 control artifact,不改倉庫(`-n`) |
691
+ | `workspace` | string | 見 admin §2.1 | — |
692
+
693
+ `comment`/`author`/`date`/`tag`/`cancel`/`branch`/`hide`/`close` 至少要給一個,否則工具直接返回
694
+ `ERROR: pass at least one of \`comment\`, \`author\`, …`(不 spawn fossil)。
695
+
696
+ 真實輸出(`dry_run: true`):
697
+
698
+ ```
699
+ $ fossil amend tip -n --tag smoke-tag
700
+ D 2026-11-17T02:42:01.051
701
+ T +sym-smoke-tag ead8e69115b0d294ee8168d741d226ccd54fdc5eb22ff535b6a14018c66f1a0b
702
+ U stellar
703
+ ```
704
+
705
+ ### 3.25 `fossil_patch`
706
+
707
+ ```bash
708
+ fossil patch create|diff|apply [-f] [-n] [-v] <file>
709
+ ```
710
+
711
+ | 參數 | 類型 | 必填/預設 | 說明 |
712
+ | --- | --- | --- | --- |
713
+ | `action` | `create` / `diff` / `apply` | `create` | 產生、顯示或套用 binary patch |
714
+ | `file` | string | **必填** | patch 檔案路徑(相對路徑以 `workspace` 為基準) |
715
+ | `force` | boolean | `false` | 覆寫既有 patch,或在有未提交改動時套用(`-f`) |
716
+ | `dry_run` | boolean | `false` | 只印出會做什麼(`-n`) |
717
+ | `verbose` | boolean | `false` | 額外說明(`-v`) |
718
+ | `workspace` | string | 見 admin §2.1 | — |
719
+
720
+ 真實輸出:
721
+
722
+ ```
723
+ $ fossil patch create smoke.patch # 無輸出,檔案產生
724
+ $ fossil patch diff smoke.patch
725
+ --- hello.txt
726
+ +++ hello.txt
727
+ @@ -1,1 +1,2 @@
728
+ hello
729
+ +patched line
730
+ ```
731
+
732
+ check-out 有未提交改動時 `fossil patch apply` 會以 `there are unsaved changes in the current check-out` 失敗,
733
+ 要先 `fossil_revert` 或傳 `force: true`。
734
+
735
+ ### 3.26 `fossil_bisect`
736
+
737
+ ```bash
738
+ fossil bisect good|bad|skip [<version>]
739
+ fossil bisect next | log | chart | reset
740
+ fossil bisect options [<name> [<value>]]
741
+ fossil bisect run [-i] <command>
742
+ ```
743
+
744
+ | 參數 | 類型 | 必填/預設 | 說明 |
745
+ | --- | --- | --- | --- |
746
+ | `action` | enum | **必填** | `good` / `bad` / `skip` / `next` / `log` / `chart` / `options` / `reset` / `run` |
747
+ | `version` | string | 目前 check-out | 要標記的版本;`next` / `log` / `chart` / `reset` 不用 |
748
+ | `command` | string | — | `run` 專用:exit 0 = good、125 = skip、其他 = bad |
749
+ | `interactive` | boolean | `false` | `run` 的 `-i`:每一步改用人工判斷 |
750
+ | `option` / `value` | string | — | `options` 專用:讀取或設定 bisect 選項 |
751
+ | `workspace` | string | 見 admin §2.1 | — |
752
+
753
+ `run` 會重複執行傳入的指令,屬於會執行動作的行為;先取得使用者同意再呼叫。
754
+
755
+ 真實輸出:
756
+
757
+ ```
758
+ $ fossil bisect good
759
+ $ fossil bisect bad tip
760
+ $ fossil bisect log
761
+ 1 GOOD 2026-11-17 02:06:59 86454b6394812c89
762
+ 2 BAD 2026-11-17 02:24:18 5f3e19ce7a0b1cb8 CURRENT
763
+ $ fossil bisect chart
764
+ 1 CURRENT 2026-11-17 02:06:59 86454b6394812c89
765
+ ```
766
+
767
+ `reset` 清掉整段 bisect 記錄,之後 `next` 才會重新從兩端算起點。
768
+
769
+ ### 3.27 `fossil_sql`
770
+
771
+ ```bash
772
+ fossil sql --readonly -json "<query>"
773
+ ```
774
+
775
+ | 參數 | 類型 | 必填/預設 | 說明 |
776
+ | --- | --- | --- | --- |
777
+ | `query` | string | **必填** | 以 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句;`LIMIT` 寫在 SQL 裡 |
778
+ | `repository` | string | check-out 的倉庫 | 直接指定倉庫檔(`-R`),可在沒有 check-out 的目錄查詢 |
779
+ | `workspace` | string | 見 admin §2.1 | — |
780
+
781
+ 輸出是製表符分隔的表格,最後一行是 `N row(s).`;空結果印 `No rows.`。查詢以 `--readonly` 開啟,
782
+ `fossil sql` 的錯誤(例如 `no such column: name`)由工具轉成 `isError`。
783
+
784
+ 真實輸出:
785
+
786
+ ```
787
+ $ fossil sql --readonly -json "SELECT count(*) AS n FROM event"
788
+ n
789
+ 2
790
+
791
+ 1 row(s).
792
+ ```
793
+
794
+ 以 `DELETE` / `UPDATE` 開頭的語句在交給 fossil 前就被拒絕:
795
+
796
+ ```
797
+ ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.
798
+ ```
799
+
800
+ ## 4. 暫存與提交
801
+
802
+ ### 4.1 `fossil_add`
803
+
804
+ ```bash
805
+ fossil add [--dotfiles] [-f] [--ignore GLOBS] <files...>
806
+ fossil add --reset [-v] # reset: true,不需要 files
807
+ ```
808
+
809
+ | 參數 | 類型 | 必填/預設 | 說明 |
810
+ | --- | --- | --- | --- |
811
+ | `files` | string[] | — | 要加入的檔案或目錄;`reset: true` 時可省略 |
812
+ | `force` | boolean | `true` | 預設加 `-f`,否則命中 `ignore-glob` 的檔案會讓 fossil 互動式詢問,服務端會卡住 |
813
+ | `dotfiles` | boolean | `false` | `--dotfiles` 遞迴點檔案 |
814
+ | `ignore` | string | — | `--ignore` 的 CSG,用於略過未管理檔案 |
815
+ | `reset` | boolean | `false` | `--reset` 清掉 ADDED 狀態,只回報不新增 |
816
+ | `verbose` | boolean | `false` | `-v` 逐檔回報;只在 `reset: true` 時送出 |
817
+ | `workspace` | string | 見 admin §2.1 | — |
818
+
819
+ `reset: true` 時工具只送 `fossil add --reset [-v]`,其餘參數忽略;fossil 對 `add -v` / `add -n`
820
+ (無 `--reset`)回 `unrecognized command-line option`。`files` 與 `reset` 都缺時工具回
821
+ ``ERROR: `files` is required unless `reset` is true.``
822
+
823
+ ### 4.2 `fossil_rm`
824
+
825
+ ```bash
826
+ fossil rm [--hard] [--soft] [-n] <files...>
827
+ fossil rm --reset [--verbose] <files...>
828
+ ```
829
+
830
+ | 參數 | 類型 | 必填/預設 | 說明 |
831
+ | --- | --- | --- | --- |
832
+ | `files` | string[] | **必填** | 要移除的檔案或目錄 |
833
+ | `force` | boolean | `false` | `--hard` 同時刪掉磁碟檔案 |
834
+ | `keep` | boolean | `false` | `--soft` 只記錄、保留磁碟檔案 |
835
+ | `dry_run` | boolean | `false` | `-n` 只列出會移除什麼 |
836
+ | `reset` | boolean | `false` | `--reset` 清掉 DELETED 狀態 |
837
+ | `verbose` | boolean | `false` | `--verbose` 逐檔回報(配合 `reset`) |
838
+ | `workspace` | string | 見 admin §2.1 | — |
839
+
840
+ 兩個都給時參數是 `fossil rm --hard --soft <files>`——fossil 不報錯,實測後一個 flag 生效(檔案仍在磁碟上),
841
+ 所以 `keep` 覆蓋 `force`。
842
+
843
+ ### 4.3 `fossil_mv`
844
+
845
+ ```bash
846
+ fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
847
+ ```
848
+
849
+ | 參數 | 類型 | 必填/預設 | 說明 |
850
+ | --- | --- | --- | --- |
851
+ | `old_name` | string | **必填** | 來源路徑 |
852
+ | `new_name` | string | **必填** | 目標路徑 |
853
+ | `hard` | boolean | `true` | `--hard` 同步改磁碟;`false` 時用 `--soft` 只記錄 RENAME 事件 |
854
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
855
+ | `workspace` | string | 見 admin §2.1 | — |
856
+
857
+ `hard` 預設 `true`:既記錄 RENAME 事件也在磁碟改名;`hard: false` 只記錄。
858
+
859
+ ### 4.4 `fossil_addremove`
860
+
861
+ ```bash
862
+ fossil addremove [--dotfiles] [--ignore GLOBS] [--clean GLOBS] [-n]
863
+ fossil addremove --reset [-n] # reset: true
864
+ ```
865
+
866
+ | 參數 | 類型 | 必填/預設 | 說明 |
867
+ | --- | --- | --- | --- |
868
+ | `dotfiles` | boolean | `false` | `--dotfiles` 一併處理 `.` 開頭的檔案 |
869
+ | `ignore` | string | — | `--ignore` 覆蓋 `ignore-glob` |
870
+ | `clean` | string | — | `--clean` 追加忽略的 glob |
871
+ | `reset` | boolean | `false` | `--reset` 清掉 ADDED/DELETED 狀態,其餘參數被忽略 |
872
+ | `dry_run` | boolean | `false` | `-n` 只列出將要 add / rm 的檔案,工作區不變 |
873
+ | `workspace` | string | 見 admin §2.1 | — |
874
+
875
+ `dry_run: true` 與 `reset: true` 可疊加:`fossil addremove --reset -n` 預覽狀態重置的結果。
876
+
877
+ ### 4.5 `fossil_commit`
878
+
879
+ ```bash
880
+ fossil commit -m <message> [--branch B] [--no-warnings] [--allow-empty] [--close]
881
+ [--bgcolor COLOR] [--mtime DATE] [--tag TAG ...] [--user-override U] [files...]
882
+ # stdin = "a\n"
883
+ ```
884
+
885
+ | 參數 | 類型 | 必填/預設 | 說明 |
886
+ | --- | --- | --- | --- |
887
+ | `message` | string | **必填** | `-m` |
888
+ | `files` | string[] | — | 省略則提交全部改動 |
889
+ | `branch` | string | — | `--branch` 把新 check-in 放到指定分支 |
890
+ | `no_warnings` | boolean | `false` | `--no-warnings` |
891
+ | `allow_empty` | boolean | `false` | `--allow-empty`(無檔案變更也能提交) |
892
+ | `close` | boolean | `false` | `--close` 提交後關閉所在分支 |
893
+ | `bgcolor` | string | — | `--bgcolor` 只套用在這一個 check-in 的背景色 |
894
+ | `mtime` | string | — | `--mtime` 指定提交時間(如 `2026-11-17 12:00:00`) |
895
+ | `tags` | string[] | — | 每個元素一個 `--tag`,把標籤打在這個 check-in 上 |
896
+ | `user_override` | string | — | `--user-override` |
897
+ | `workspace` | string | 見 admin §2.1 | — |
898
+
899
+ **關鍵點**:工具固定向 stdin 寫 `a\n`,因為提交二進位制檔案時 fossil 會問
900
+ `commit anyhow (a=all/y/N)?`,沒有 stdin 就會永久阻塞。副作用是該提示被自動回答為“全部”。
901
+
902
+ ### 4.6 `fossil_revert`
903
+
904
+ ```bash
905
+ fossil revert [-r REV] [files...]
906
+ ```
907
+
908
+ 不給 `files` 時回退整個 check-out。破壞性:未提交的改動直接丟失(`stash save` 可先儲存)。
909
+
910
+ | 參數 | 類型 | 必填/預設 | 說明 |
911
+ | --- | --- | --- | --- |
912
+ | `files` | string[] | — | 要回退的檔案;省略時回退整個 check-out |
913
+ | `revision` | string | — | 回退到的版本(`-r`) |
914
+ | `workspace` | string | 見 admin §2.1 | — |
915
+
916
+ ### 4.7 `fossil_clean`
917
+
918
+ ```bash
919
+ fossil clean -n # dry_run: true
920
+ fossil clean -f # all_files: true
921
+ fossil clean --no-prompt # 都不給(預設)
922
+ ```
923
+
924
+ | 參數 | 類型 | 必填/預設 | 說明 |
925
+ | --- | --- | --- | --- |
926
+ | `dry_run` | boolean | `false` | 只列出會刪除的檔案(`-n`) |
927
+ | `all_files` | boolean | `false` | 不確認直接刪除(`-f`) |
928
+ | `workspace` | string | 見 admin §2.1 | — |
929
+
930
+ 三態互斥,優先順序 `dry_run` > `all_files` > `--no-prompt`。預設 `--no-prompt` 是為了不阻塞;
931
+ 它等於“刪除所有未跟蹤檔案且不再確認”,所以**先 `dry_run: true` 預覽**。空輸出 → `Nothing to clean.`
932
+
933
+ ### 4.8 `fossil_stash`
934
+
935
+ ```bash
936
+ fossil stash save|snapshot [-m COMMENT]
937
+ fossil stash ls|pop|apply|drop|diff [STASH_ID]
938
+ ```
939
+
940
+ | 參數 | 類型 | 必填/預設 | 說明 |
941
+ | --- | --- | --- | --- |
942
+ | `action` | `save` / `snapshot` / `ls` / `pop` / `apply` / `drop` / `diff` | `ls` | stash 動作 |
943
+ | `comment` | string | — | `save` / `snapshot` 的註解(`-m`) |
944
+ | `stash_id` | string | — | `pop` / `apply` / `drop` / `diff` 的 stash id |
945
+ | `workspace` | string | 見 admin §2.1 | — |
946
+
947
+ `comment` 只對 `save`/`snapshot` 生效;其它動作傳 `comment` 會被忽略。空輸出 → `No stashed changes.`
948
+
949
+ ---
950
+
951
+ ## 5. 歷史、分支與合併
952
+
953
+ ### 5.1 `fossil_tag`
954
+
955
+ ```bash
956
+ fossil tag ls
957
+ fossil tag add <tag> <checkin>
958
+ fossil tag cancel <tag> [<checkin>] # checkin 預設 'tip'
959
+ ```
960
+
961
+ | 參數 | 類型 | 必填/預設 | 說明 |
962
+ | --- | --- | --- | --- |
963
+ | `action` | `ls` / `add` / `cancel` | `ls` | 要執行的 tag 動作 |
964
+ | `tag_name` | string | `add` / `cancel` 時必填 | 標籤名 |
965
+ | `checkin` | string | `add` 時必填;`cancel` 預設 `tip` | 要標記或取消的 check-in |
966
+ | `workspace` | string | 見 admin §2.1 | — |
967
+
968
+ `fossil tag cancel` 必須有 artifact id,所以工具補 `tip`;空輸出 → `No tags.`(實測 `fossil tag ls` 輸出 `trunk`)。
969
+
970
+ ### 5.2 `fossil_branch`
971
+
972
+ ```bash
973
+ fossil branch ls
974
+ fossil branch new <name> [<basis>] # basis 預設 'current'
975
+ ```
976
+
977
+ `branch_name` 在 `action: 'new'` 時必填,否則工具直接返回 `ERROR: 'branch_name' is required for action 'new'.`。
978
+ `basis` 省略時補 `current`(fossil 要求顯式 basis)。實測 `fossil branch ls` → `* trunk`。
979
+
980
+ | 參數 | 類型 | 必填/預設 | 說明 |
981
+ | --- | --- | --- | --- |
982
+ | `action` | `ls` / `new` | `ls` | 列出分支或建立新分支 |
983
+ | `branch_name` | string | `new` 時必填 | 新分支名 |
984
+ | `basis` | string | `current` | 新分支的起點(check-in 或分支) |
985
+ | `workspace` | string | 見 admin §2.1 | — |
986
+
987
+ ### 5.3 `fossil_merge`
988
+
989
+ ```bash
990
+ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binary G] [-f] [-K] [-v]
991
+ <branch_or_version>
992
+ ```
993
+
994
+ | 參數 | 類型 | 必填/預設 | 說明 |
995
+ | --- | --- | --- | --- |
996
+ | `branch_or_version` | string | **必填** | 要合併的分支名或 check-in |
997
+ | `integrate` | boolean | `false` | 合併後關閉源分支(`--integrate`) |
998
+ | `cherrypick` | boolean | `false` | 只合併這一個 check-in 的變更(`--cherrypick`) |
999
+ | `backout` | boolean | `false` | 反向套用這一個 check-in 的變更(`--backout`) |
1000
+ | `dry_run` | boolean | `false` | 只模擬(`-n`) |
1001
+ | `baseline` | string | — | 用這個版本當 pivot(`--baseline`) |
1002
+ | `binary` | string | — | 符合此 glob 的檔案不做平行合併(`--binary`) |
1003
+ | `force` | boolean | `false` | 即使合併無效也照做(`-f`) |
1004
+ | `keep_merge_files` | boolean | `false` | 衝突時保留暫存檔(`-K`) |
1005
+ | `verbose` | boolean | `false` | 逐檔報告合併結果(`-v`) |
1006
+ | `workspace` | string | 見 admin §2.1 | — |
1007
+
1008
+ `cherrypick` 與 `backout` 都由 fossil 的 `merge` 命令提供,兩者互斥;衝突時工具照常把 fossil 的錯誤輸出回傳。
1009
+
1010
+ ### 5.4 `fossil_update`
1011
+
1012
+ ```bash
1013
+ fossil update [--latest] [--nosync] [--setmtime] [-K] [-v] [target]
1014
+ fossil update -n [target] # dry_run: true
1015
+ ```
1016
+
1017
+ | 參數 | 類型 | 必填/預設 | 說明 |
1018
+ | --- | --- | --- | --- |
1019
+ | `target` | string | 當前分支 | 要切換到的版本或分支名 |
1020
+ | `latest` | boolean | `false` | `--latest` 更新到最新版本 |
1021
+ | `dry_run` | boolean | `false` | `-n` 只顯示會做什麼 |
1022
+ | `no_sync` | boolean | `false` | `--nosync` 跳過更新前自動 sync |
1023
+ | `set_mtime` | boolean | `false` | `--setmtime` 把檔案時間戳設成最後一次相關提交的時間 |
1024
+ | `keep_merge_files` | boolean | `false` | `-K` 衝突時保留 `*-baseline` / `*-original` / `*-merge` |
1025
+ | `verbose` | boolean | `false` | `-v` 列出每個檔案的處理結果 |
1026
+
1027
+ **破壞性**:會覆蓋工作區本地改動。`target` 省略時更新當前分支。
1028
+
1029
+ ### 5.5 `fossil_undo`
1030
+
1031
+ ```bash
1032
+ fossil undo [-n]
1033
+ ```
1034
+
1035
+ 撤銷上一次 update/revert/merge;`dry_run: true` 先看會撤銷什麼。fossil 的 undo 棧是程序外的本地狀態,
1036
+ 在 check-out 裡連續呼叫才有意義。
1037
+
1038
+ | 參數 | 類型 | 必填/預設 | 說明 |
1039
+ | --- | --- | --- | --- |
1040
+ | `dry_run` | boolean | `false` | 只顯示會撤銷什麼(`-n`) |
1041
+ | `workspace` | string | 見 admin §2.1 | — |
1042
+
1043
+ ---
1044
+
1045
+ ## 6. 典型流程
1046
+
1047
+ ```
1048
+ fossil_status # 看現狀 + 未跟蹤檔案
1049
+ fossil_addremove { dotfiles: true } # 批次暫存新增/刪除
1050
+ fossil_diff # 複核
1051
+ fossil_commit { message: "feat: x" }
1052
+ fossil_timeline { limit: 5 }
1053
+ ```
1054
+
1055
+ 改錯時的安全路徑:`fossil_stash { action: 'save' }` → `fossil_update` / `fossil_revert` → 必要時
1056
+ `fossil_stash { action: 'pop' }`。
1057
+
1058
+ 分支:`fossil_branch { action: 'new', branch_name: 'dev' }` → `fossil_update { target: 'dev' }` →
1059
+ 改動提交 → `fossil_merge { branch_or_version: 'dev', integrate: true }`。
1060
+
1061
+ ---
1062
+
1063
+ ## 7. 已知邊界
1064
+
1065
+ 1. **`fossil_status` 的未跟蹤檔案來自第二條命令**(`fossil extra`),兩者併發執行。單條失敗時該段渲染成
1066
+ `--- STATUS ---` + `ERROR: …`,但 `isError` 只為 `true` 當**兩段都失敗**(`renderSections` 的規則)。
1067
+ 2. **`commit` 自動回答互動提示為 `a`(all)**:二進位制檔案與忽略規則的衝突一律照交。
1068
+ 3. **`add` 預設 `-f`**:`force: false` 時命中 `ignore-glob` 的檔案會讓 fossil 互動詢問 → 服務端可能掛住,
1069
+ 不要在沒有 stdin 支援的情況下傳 `force: false`。
1070
+ 4. **`clean` 無參數即 `--no-prompt`**(直接刪),不是“只預覽”。先用 `dry_run`。
1071
+ 5. **`tag cancel` / `branch new` 的預設值**(`tip` / `current`)是工具補的,不是 fossil 原生預設。
1072
+ 6. **版本表示式**只支援 fossil 自身語法(`tip`、雜湊前綴、`branch:name` 等);`tip-1` 這類寫法會失敗。
1073
+ 7. **路徑沒有 `--` 屏障**:以 `-` 開頭的檔名需要 `./` 前綴。
1074
+ 8. **除 `fossil_sql` 可用 `repository` 直接查詢外,工具都要求已 open 的 check-out**;只有倉庫檔案(.fossil)時用 admin 的 `fossil_open`。
1075
+ 9. **`fossil_ignore_from_gitignore` 沿用 fossil 的深度語意**:git 的 `*` 不跨 `/`,fossil 的跨,所以含斜線的樣式
1076
+ (`src/*.o`)在 fossil 會連更深的路徑一起匹配。
1077
+ 10. **`ignore-glob` 沒有否定**:`!` 開頭的行只能略過並在 `NOTE:` 說明,被 git 重新納入的檔案在 fossil 仍被忽略。
1078
+
1079
+ ---
1080
+
1081
+ ## 8. 原始碼位置
1082
+
1083
+ | 檔案 | 內容 |
1084
+ | --- | --- |
1085
+ | `src/tools/version-control.ts` | 40 個工具的註冊、參數 schema、argv 拼裝、`renderSections` 分節輸出 |
1086
+ | `src/tools/common.ts` | `workspaceParam`、`flag()`、`clean()`、`pushOption()` 等共享片段 |
1087
+ | `src/core/fossil.ts` | `runFossil`(spawn + 超時 + 輸出截斷)、`renderOutcome`、`formatFailure` |
1088
+ | `src/config.ts` | `FOSSIL_BIN`、`FOSSIL_TIMEOUT_MS`、`FOSSIL_MAX_CAPTURE_BYTES` 等 |
1089
+ | `src/capabilities.ts` | 能力註冊表(`v` → 本檔案 40 個工具) |