@stellar_ai/mcp_fossil_scm 0.1.2 → 0.2.0

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