@stellar_ai/mcp_fossil_scm 0.1.3 → 0.2.1

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # VCS 能力(`-c v`)工具說明
2
2
 
3
- 適用於 `@stellar_ai/mcp_fossil_scm@0.1.3` 及之後。所有行為都在 fossil 2.21 上實測。
3
+ 適用於 `@stellar_ai/mcp_fossil_scm@0.2.1` 及之後。所有行為都在 fossil 2.21 上實測。
4
4
 
5
5
  `-c v` 註冊 40 個工具;要連 admin 一起用 `-c av`。
6
6
 
@@ -14,7 +14,7 @@
14
14
  | `fossil_diff` | `fossil diff` |
15
15
  | `fossil_cat` | `fossil cat <file> [-r REV]` |
16
16
  | `fossil_finfo` | `fossil finfo [-i\|-s\|-p\|-l] <file>` |
17
- | `fossil_ls` | `fossil ls [-r REV] [--age] [-v] [-t] [--hash]` |
17
+ | `fossil_ls` | `fossil ls [-R FILE] [-r REV] [--age] [-v] [-t] [--hash]` |
18
18
  | `fossil_extras` | `fossil extras` |
19
19
  | `fossil_timeline` | `fossil timeline -n N` |
20
20
  | `fossil_info` | `fossil info [target]` |
@@ -52,15 +52,15 @@
52
52
  | `fossil_ignore_from_gitignore` | 讀 `.gitignore`,寫 `.fossil-settings/ignore-glob` |
53
53
 
54
54
  標了 `destructiveHint: true` 的是 `fossil_rm` / `fossil_revert` / `fossil_clean` / `fossil_update` / `fossil_undo`:
55
- 它們會覆蓋工作區內容,呼叫方應先確認,或先跑 `dry_run` / `-n` 預覽。除了 `fossil_sql` 可用 `repository` 直接查詢,其餘工具都需要 check-out(見 §2)。
55
+ 它們會覆蓋工作區內容,呼叫方應先確認,或先跑 `dry_run` / `-n` 預覽。`fossil_cat`/`fossil_info`/`fossil_descendants`/`fossil_ls`/`fossil_artifact`/`fossil_timeline` 與 `fossil_sql` 可用 `repository` 直接讀倉庫檔,其餘工具都需要 check-out(見 §2)。
56
56
 
57
57
  ---
58
58
 
59
59
  ## 2. 通用約定
60
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`,
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
64
  包裝為 `isError: true`。
65
65
  - **失敗格式** 與 admin 一致:
66
66
 
@@ -73,7 +73,7 @@ WORKSPACE: /tmp/vd
73
73
 
74
74
  - **空輸出**:不同工具給不同的提示(`No differences found.` / `No untracked files.` / `No events.` 等),
75
75
  見各工具小節。
76
- - **路徑參數不插入 `--`**:以 `-` 開頭的檔名會被 fossil 當成選項,需要呼叫方自行加 `./` 前綴。
76
+ - **路徑參數原樣傳給 fossil**:以 `-` 開頭的檔名會被當成選項,呼叫方需自己加 `./` 前綴。
77
77
 
78
78
  ---
79
79
 
@@ -84,17 +84,28 @@ WORKSPACE: /tmp/vd
84
84
  一次呼叫併發執行兩條命令,輸出分兩段:
85
85
 
86
86
  ```bash
87
- fossil status [-b]
88
- fossil extra [--dotfiles] [--ignore GLOBS] # cwd = workspace,兩條並行
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 時並行
89
91
  ```
90
92
 
91
93
  | 參數 | 類型 | 必填/預設 | 說明 |
92
94
  | --- | --- | --- | --- |
93
- | `brief` | boolean | `false` | `-b`:只輸出狀態關鍵字 |
94
- | `dotfiles` | boolean | `false` | `extra` 時包含點檔案 |
95
+ | `brief` | boolean | `false` | 只列出變更檔案清單(`fossil changes`) |
96
+ | `dotfiles` | boolean | `false` | 包含點檔案(`--dotfiles`) |
95
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`) |
96
105
  | `workspace` | string | 見 admin §2.1 | — |
97
106
 
107
+ 指定 `select` 且含 `extra` 或 `differ` 時,未跟蹤檔案已在同一段輸出裡,工具只跑一條命令。
108
+
98
109
  真實輸出(乾淨 check-out):
99
110
 
100
111
  ```
@@ -117,7 +128,8 @@ comment: first (user: stellar)
117
128
 
118
129
  ```bash
119
130
  fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
120
- [-c N] [-y] [-v] [--undo] [-w] [files...]
131
+ [-c N] [-y] [-v] [--undo] [-w] [-Z] [--strip-trailing-cr] [-N] [-i] [--unified] [-h] [--json] [-W N]
132
+ [files...]
121
133
  ```
122
134
 
123
135
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -133,7 +145,15 @@ fossil diff [--from X] [--to Y] [--branch B] [-ci C] [--brief] [--numstat]
133
145
  | `side_by_side` | boolean | `false` | `-y` 並排顯示 |
134
146
  | `verbose` | boolean | `false` | `-v` 完整印出新增或刪除的檔案內容 |
135
147
  | `undo` | boolean | `false` | `--undo` 與 undo 緩衝區比較 |
136
- | `ignore_whitespace` | boolean | `false` | `-w` |
148
+ | `ignore_whitespace` | boolean | `false` | `-w` 忽略空白差異 |
149
+ | `ignore_trailing_space` | boolean | `false` | `-Z` 忽略行尾空白差異 |
150
+ | `strip_trailing_cr` | boolean | `false` | `--strip-trailing-cr` 忽略每行結尾的 CR |
151
+ | `new_file` | boolean | `false` | `-N` 把新增檔案視為本來就是空內容 |
152
+ | `internal` | boolean | `false` | `-i` 用內建 diff |
153
+ | `unified` | boolean | `false` | `--unified` 輸出 unified patch |
154
+ | `versions_header` | boolean | `false` | `-h` 在標頭列出比較的版本 |
155
+ | `json` | boolean | `false` | `--json` 以 JSON 輸出 |
156
+ | `width` | number | — | `-W` 並排顯示的行寬(≥20) |
137
157
  | `workspace` | string | 見 admin §2.1 | — |
138
158
 
139
159
  不給版本時是“工作區 vs 最近一次 check-in”。版本名寫錯時 fossil 報
@@ -151,6 +171,7 @@ fossil cat <file> [-r REV]
151
171
  | --- | --- | --- | --- |
152
172
  | `file` | string | **必填** | 要列印的檔案 |
153
173
  | `revision` | string | — | 指定 check-in 或版本(`-r`) |
174
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
154
175
  | `workspace` | string | 見 admin §2.1 | — |
155
176
 
156
177
  ### 3.4 `fossil_finfo`
@@ -189,8 +210,8 @@ $ fossil finfo -s a.txt
189
210
  unchanged 5f3e19ce7a
190
211
  ```
191
212
 
192
- `-n` / `--offset` / `-b` 只在 `log` 模式送出;fossil 對 `finfo -i -n 20` 會回
193
- `unrecognized command-line option or missing argument: -n`。
213
+ `-b` / `-n` / `--offset` 只在 `log` 模式送出,`-r` 只在 `id` 與 `print` 模式送出,`-v` 只在 `id` 模式送出;
214
+ 其餘組合 fossil 會回 `unrecognized command-line option or missing argument`。
194
215
 
195
216
  ### 3.5 `fossil_extras`
196
217
 
@@ -213,7 +234,8 @@ fossil extras [--dotfiles] [--ignore GLOBS] [--abs-paths|--rel-paths] [--header]
213
234
  ### 3.6 `fossil_timeline`
214
235
 
215
236
  ```bash
216
- fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [-F FORMAT] [-v]
237
+ fossil timeline -n <limit> [-R FILE] [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [-F FORMAT] [-v]
238
+ [--offset N] [-W N]
217
239
  ```
218
240
 
219
241
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -227,6 +249,9 @@ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [
227
249
  | `checkin` | string | — | `when` 相對的 check-in 雜湊或日期 |
228
250
  | `format` | string | — | 條目格式(`-F`):`oneline` / `medium` / `full` 或 `%h %d %c` 這類樣板 |
229
251
  | `verbose` | boolean | `false` | 每個 check-in 後面列出變更的檔案(`-v`) |
252
+ | `offset` | number | — | 跳過前 N 條(`--offset`) |
253
+ | `width` | number | — | 輸出寬度(`-W`,≥20) |
254
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
230
255
  | `workspace` | string | 見 admin §2.1 | — |
231
256
 
232
257
  真實輸出(`limit: 3`):
@@ -242,7 +267,7 @@ fossil timeline -n <limit> [-p PATH] [-t TYPE] [-b BRANCH] [-c] [WHEN CHECKIN] [
242
267
  ### 3.7 `fossil_info`
243
268
 
244
269
  ```bash
245
- fossil info [target]
270
+ fossil info [target] [-R FILE] [-v]
246
271
  ```
247
272
 
248
273
  `target` 可以是檔名、check-in 雜湊、分支名;省略時給倉庫/check-out 元資訊(真實輸出見 §3.1 的 STATUS 段同源)。
@@ -251,6 +276,8 @@ fossil info [target]
251
276
  | 參數 | 類型 | 必填/預設 | 說明 |
252
277
  | --- | --- | --- | --- |
253
278
  | `target` | string | — | 檔名、check-in 雜湊或分支名 |
279
+ | `verbose` | boolean | `false` | 額外資訊,如 SQLite 版本與倉庫大小(`-v`) |
280
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
254
281
  | `workspace` | string | 見 admin §2.1 | — |
255
282
 
256
283
  ---
@@ -258,7 +285,9 @@ fossil info [target]
258
285
 
259
286
  ```bash
260
287
  fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta]
261
- [--classify] [--no-merge] [--dotfiles] [--abs-paths] [files...]
288
+ [--changed|--missing|--unchanged|--extra|--differ|--all]
289
+ [--classify] [--no-classify] [--no-merge] [--merge] [--ignore GLOBS] [--hash] [--header] [-v]
290
+ [--dotfiles] [--abs-paths|--rel-paths] [files...]
262
291
  ```
263
292
 
264
293
  純工作區的變更清單(不讀 `extras`,所以未跟蹤檔案不會出現)。
@@ -267,10 +296,18 @@ fossil changes [--edited|--updated|--added|--deleted|--renamed|--conflict|--meta
267
296
  | --- | --- | --- | --- |
268
297
  | `files` | string[] | — | 只報告這些路徑 |
269
298
  | `edited` / `updated` / `added` / `deleted` / `renamed` / `conflict` / `meta` | boolean | `false` | 變更類型過濾,可疊加 |
299
+ | `changed` / `missing` / `unchanged` / `extra` / `differ` / `all` | boolean | `false` | 其餘變更類型過濾,可疊加 |
270
300
  | `classify` | boolean | `false` | 每行前面加變更類型 |
271
301
  | `no_merge` | boolean | `false` | 隱藏 merge 貢獻者 |
302
+ | `merge` | boolean | `false` | 只列帶合併衝突標記的檔案(`--merge`) |
303
+ | `no_classify` | boolean | `false` | 不加每行的變更類型(`--no-classify`) |
304
+ | `ignore` | string | — | `--ignore` 的 CSG,符合的檔案不列入 |
305
+ | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷狀態(`--hash`) |
306
+ | `header` | boolean | `false` | 非空報告前印倉庫名(`--header`) |
307
+ | `verbose` | boolean | `false` | 空報告時印 `(none)`(`-v`) |
272
308
  | `dotfiles` | boolean | `false` | 包含以 `.` 開頭的未管理檔案 |
273
309
  | `absolute_paths` | boolean | `false` | 輸出絕對路徑 |
310
+ | `relative_paths` | boolean | `false` | 輸出相對於目前目錄的路徑 |
274
311
  | `workspace` | string | 見 admin §2.1 | — |
275
312
 
276
313
  真實輸出(`classify: true`):
@@ -387,7 +424,7 @@ fossil merge-base [--ignore-merges] <v1> <v2> [...]
387
424
  ### 3.13 `fossil_leaves`
388
425
 
389
426
  ```bash
390
- fossil leaves [-a] [-c] [-m] [--bybranch] [-W WIDTH]
427
+ fossil leaves [-a] [-c] [-m] [--recompute] [--bybranch] [-W WIDTH]
391
428
  ```
392
429
 
393
430
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -395,6 +432,7 @@ fossil leaves [-a] [-c] [-m] [--bybranch] [-W WIDTH]
395
432
  | `all` | boolean | `false` | `-a` 連已關閉的 leaf 一起列 |
396
433
  | `closed` | boolean | `false` | `-c` 只列已關閉的 leaf |
397
434
  | `multiple` | boolean | `false` | `-m` 只列有多個 leaf 的分支 |
435
+ | `recompute` | boolean | `false` | `--recompute` 重算 leaf,不讀快取 |
398
436
  | `by_branch` | boolean | `false` | `--bybranch` 按分支名排序 |
399
437
  | `width` | number | — | `-W` 輸出寬度,`0` 表示一行一筆 |
400
438
  | `workspace` | string | 見 admin §2.1 | — |
@@ -417,6 +455,7 @@ fossil descendants [<checkin>] [-W WIDTH]
417
455
  | --- | --- | --- | --- |
418
456
  | `checkin` | string | — | 起始 check-in;省略時用當前 check-out 的版本 |
419
457
  | `width` | number | — | 輸出寬度(`-W`);`0` 表示一行一筆 |
458
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
420
459
  | `workspace` | string | 見 admin §2.1 | — |
421
460
 
422
461
  真實輸出:
@@ -498,7 +537,8 @@ fossil ls ?PATHS ...? [-r REV] [--age] [-v] [-t] [--hash]
498
537
  | `age` | boolean | `false` | 顯示提交時間(`--age`) |
499
538
  | `verbose` | boolean | `false` | 額外資訊:無 `-r` 時是變更狀態,有 `-r` 時是提交時間與大小(`-v`) |
500
539
  | `time_order` | boolean | `false` | 按時間排序(`-t`);搭配 `--age` 或 `-r` 時按提交時間 |
501
- | `hash` | boolean | `false` | 用雜湊(而非大小+mtime)判斷檔案狀態(`--hash`) |
540
+ | `hash` | boolean | `false` | 用雜湊而非大小+mtime 判斷檔案狀態(`--hash`),自動加上 `--verbose` |
541
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
502
542
  | `workspace` | string | 見 admin §2.1 | — |
503
543
 
504
544
  真實輸出:
@@ -519,7 +559,7 @@ fossil search [-a] [-n N] [-W WIDTH] pattern
519
559
 
520
560
  | 參數 | 類型 | 必填/預設 | 說明 |
521
561
  | --- | --- | --- | --- |
522
- | `pattern` | string | — | 要搜尋的字詞;全部都要命中 |
562
+ | `pattern` | string | **必填** | 要搜尋的字詞;全部都要命中 |
523
563
  | `all` | boolean | `false` | 輸出全部命中,而不是只給高分者(`--all`) |
524
564
  | `limit` | number | — | 最多輸出幾筆(`-n`) |
525
565
  | `width` | number | — | 輸出寬度,`0` 表示不折行(`-W`) |
@@ -540,12 +580,13 @@ $ fossil search second
540
580
  ### 3.19 `fossil_artifact`
541
581
 
542
582
  ```bash
543
- fossil artifact <ARTIFACT-ID>
583
+ fossil artifact <ARTIFACT-ID> [-R FILE]
544
584
  ```
545
585
 
546
586
  | 參數 | 類型 | 必填/預設 | 說明 |
547
587
  | --- | --- | --- | --- |
548
- | `artifact` | string | — | 工件雜湊,可用唯一前綴 |
588
+ | `artifact` | string | **必填** | 工件雜湊,可用唯一前綴 |
589
+ | `repository` | string | — | `-R` 直接讀這個倉庫檔案,不需要 check-out |
549
590
  | `workspace` | string | 見 admin §2.1 | — |
550
591
 
551
592
  真實輸出(檔案版本工件):
@@ -569,7 +610,7 @@ fossil describe ?VERSION? [--digits N] [--dirty] [--long] [--match GLOB]
569
610
  | --- | --- | --- | --- |
570
611
  | `version` | string | — | 要描述的版本;省略時為當前 check-out |
571
612
  | `digits` | number | — | 雜湊位數(`--digits`,4..40) |
572
- | `dirty` | boolean | `false` | 一併顯示是否有未提交改動(`--dirty`) |
613
+ | `dirty` | boolean | `false` | 一併顯示是否有未提交改動(`--dirty`);只適用當前 check-out |
573
614
  | `long` | boolean | `false` | 即使三者可折疊也全部顯示(`--long`) |
574
615
  | `match` | string | — | 只考慮符合此 glob 的非傳播標籤(`--match`) |
575
616
  | `workspace` | string | 見 admin §2.1 | — |
@@ -625,21 +666,25 @@ Wrote snap.zip from tip.
625
666
  ### 3.22 `fossil_unversioned`
626
667
 
627
668
  ```bash
628
- fossil unversioned list [--glob PATTERN] [--like PATTERN]
629
- fossil unversioned cat|add|remove|touch FILE ...
669
+ fossil unversioned list|remove [--glob PATTERN] [--like PATTERN]
670
+ fossil unversioned cat|add|remove|touch FILE ... [--mtime TIMESTAMP]
671
+ fossil unversioned sync|revert [URL] [-v] [-n]
630
672
  ```
631
673
 
632
674
  | 參數 | 類型 | 必填/預設 | 說明 |
633
675
  | --- | --- | --- | --- |
634
- | `action` | `list` / `cat` / `add` / `remove` / `touch` | `list` | `list` 列出、`cat` 印內容、`add`/`remove` 改集合、`touch` 更新時間戳 |
676
+ | `action` | `list` / `cat` / `add` / `remove` / `touch` / `sync` / `revert` | `list` | `list` 列出、`cat` 印內容、`add`/`remove` 改集合、`touch` 更新時間戳、`sync`/`revert` 與遠端交換 |
635
677
  | `files` | string[] | — | 動作套用的檔案 |
636
- | `glob` | string | — | 只比對符合此 glob 的名字(`--glob`) |
637
- | `like` | string | — | 只比對符合此模式的名字(`--like`) |
678
+ | `glob` | string | — | 只比對符合此 glob 的名字(`--glob`),用於 `list`/`remove` |
679
+ | `like` | string | — | 只比對符合此模式的名字(`--like`),用於 `list`/`remove` |
680
+ | `url` | string | 預設遠端 | `sync`/`revert` 的遠端 URL |
681
+ | `mtime` | string | — | 取代 `now` 的時間戳,用於 `add`/`remove`/`touch`(`--mtime`) |
682
+ | `verbose` | boolean | `false` | 額外診斷輸出,用於 `sync`/`revert`(`-v`) |
683
+ | `dry_run` | boolean | `false` | 只顯示會做什麼,用於 `sync`/`revert`(`-n`) |
638
684
  | `workspace` | string | 見 admin §2.1 | — |
639
685
 
640
- unversioned file(UV-file)只保留最新版本、不保存歷史,變更不可撤銷。`action` 不是 `list` 時,
641
- `files`、`glob`、`like` 至少要給一個,否則工具直接返回
642
- `ERROR: action 'cat' needs \`files\`, \`glob\` or \`like\`.`(不 spawn fossil)。
686
+ unversioned file(UV-file)只保留最新版本、不保存歷史,變更不可撤銷。`cat`/`add`/`touch` 必須給 `files`,
687
+ 否則工具直接返回 ``ERROR: action 'cat' needs `files`.``
643
688
 
644
689
  真實輸出:
645
690
 
@@ -657,13 +702,18 @@ unversioned body
657
702
  ### 3.23 `fossil_touch`
658
703
 
659
704
  ```bash
660
- fossil touch [--now|-c|--checkin|-C|--checkout] [FILES...]
705
+ fossil touch [--now|-c|--checkin|-C|--checkout] [-g GLOBS] [-G] [-v] [-n] [-q] [FILES...]
661
706
  ```
662
707
 
663
708
  | 參數 | 類型 | 必填/預設 | 說明 |
664
709
  | --- | --- | --- | --- |
665
710
  | `files` | string[] | — | 檔案或 glob;省略時套用所有受管理檔案 |
666
711
  | `mode` | `now` / `checkin` / `checkout` | `now` | `--now` 目前時間、`-c` 該檔最後一次 check-in 的時間、`-C` 當前 check-out 的時間 |
712
+ | `glob` | string | — | 逗號分隔的 glob,從原始碼樹頂端計算(`-g`) |
713
+ | `glob_file` | string | — | 讀取 fossil glob 清單檔(`-G`) |
714
+ | `verbose` | boolean | `false` | 印出 glob 與每個碰到的檔案(`-v`) |
715
+ | `dry_run` | boolean | `false` | 只列出需要更新的檔案(`-n`) |
716
+ | `quiet` | boolean | `false` | 略過未管理或樹外檔案的警告(`-q`) |
667
717
  | `workspace` | string | 見 admin §2.1 | — |
668
718
 
669
719
  Fossil 用檔案大小與 mtime 判斷是否變更,所以在同一個時間戳內改檔案可能被忽略;`fossil_touch { mode: "now" }`
@@ -672,16 +722,22 @@ Fossil 用檔案大小與 mtime 判斷是否變更,所以在同一個時間戳
672
722
  ### 3.24 `fossil_amend`
673
723
 
674
724
  ```bash
675
- fossil amend <check-in> [-n] [-m COMMENT] [--author USER] [--date WHEN] [--tag TAG] [--cancel TAG]
676
- [--branch NAME] [--hide] [--close]
725
+ fossil amend <check-in> [-n] [-m COMMENT|-M FILE] [--author USER] [--date WHEN]
726
+ [--bgcolor COLOR] [--branchcolor] [--date-override WHEN] [--user-override USER]
727
+ [--tag TAG] [--cancel TAG] [--branch NAME] [--hide] [--close]
677
728
  ```
678
729
 
679
730
  | 參數 | 類型 | 必填/預設 | 說明 |
680
731
  | --- | --- | --- | --- |
681
- | `checkin` | string | — | 要改的 check-in(`tip` 或雜湊) |
732
+ | `checkin` | string | **必填** | 要改的 check-in(`tip` 或雜湊) |
682
733
  | `comment` | string | — | 換掉註解(`-m`) |
734
+ | `message_file` | string | — | 從工作區的檔案讀取新註解(`-M`) |
683
735
  | `author` | string | — | 換掉作者(`--author`) |
684
736
  | `date` | string | — | 換掉 check-in 時間,或 `now`(`--date`) |
737
+ | `bgcolor` | string | — | 這個 check-in 的背景色(`--bgcolor`) |
738
+ | `branchcolor` | boolean | `false` | 把 `bgcolor` 套用到整個分支(`--branchcolor`) |
739
+ | `date_override` | string | — | control artifact 的變更時間(`--date-override`) |
740
+ | `user_override` | string | — | control artifact 上的使用者名(`--user-override`) |
685
741
  | `tag` | string[] | — | 加上標籤(`--tag`,可重複) |
686
742
  | `cancel` | string[] | — | 移除標籤(`--cancel`,可重複) |
687
743
  | `branch` | string | — | 以此 check-in 開新分支(`--branch`) |
@@ -690,8 +746,8 @@ fossil amend <check-in> [-n] [-m COMMENT] [--author USER] [--date WHEN] [--tag T
690
746
  | `dry_run` | boolean | `false` | 只印出 control artifact,不改倉庫(`-n`) |
691
747
  | `workspace` | string | 見 admin §2.1 | — |
692
748
 
693
- `comment`/`author`/`date`/`tag`/`cancel`/`branch`/`hide`/`close` 至少要給一個,否則工具直接返回
694
- `ERROR: pass at least one of \`comment\`, \`author\`, …`(不 spawn fossil)。
749
+ `comment`/`message_file`/`author`/`date`/`bgcolor`/`date_override`/`user_override`/`tag`/`cancel`/`branch`/`hide`/`close`
750
+ 至少要給一個,否則工具直接返回 `ERROR: pass at least one of \`comment\`, \`message_file\`, …`(不 spawn fossil)。
695
751
 
696
752
  真實輸出(`dry_run: true`):
697
753
 
@@ -705,7 +761,9 @@ U stellar
705
761
  ### 3.25 `fossil_patch`
706
762
 
707
763
  ```bash
708
- fossil patch create|diff|apply [-f] [-n] [-v] <file>
764
+ fossil patch create [-f] <file>
765
+ fossil patch diff [-f] <file>
766
+ fossil patch apply [-f] [-n] [-v] <file>
709
767
  ```
710
768
 
711
769
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -713,8 +771,8 @@ fossil patch create|diff|apply [-f] [-n] [-v] <file>
713
771
  | `action` | `create` / `diff` / `apply` | `create` | 產生、顯示或套用 binary patch |
714
772
  | `file` | string | **必填** | patch 檔案路徑(相對路徑以 `workspace` 為基準) |
715
773
  | `force` | boolean | `false` | 覆寫既有 patch,或在有未提交改動時套用(`-f`) |
716
- | `dry_run` | boolean | `false` | 只印出會做什麼(`-n`) |
717
- | `verbose` | boolean | `false` | 額外說明(`-v`) |
774
+ | `dry_run` | boolean | `false` | `-n` 只印出 `apply` 會做什麼 |
775
+ | `verbose` | boolean | `false` | `-v` 讓 `apply` 額外說明 |
718
776
  | `workspace` | string | 見 admin §2.1 | — |
719
777
 
720
778
  真實輸出:
@@ -769,13 +827,15 @@ $ fossil bisect chart
769
827
  ### 3.27 `fossil_sql`
770
828
 
771
829
  ```bash
772
- fossil sql --readonly -json "<query>"
830
+ fossil sql --readonly [-R FILE] -json "<query>"
831
+ fossil sql --readonly --no-repository FILE -json "<query>"
773
832
  ```
774
833
 
775
834
  | 參數 | 類型 | 必填/預設 | 說明 |
776
835
  | --- | --- | --- | --- |
777
836
  | `query` | string | **必填** | 以 `SELECT` / `WITH` / `PRAGMA` / `EXPLAIN` 開頭的語句;`LIMIT` 寫在 SQL 裡 |
778
- | `repository` | string | check-out 的倉庫 | 直接指定倉庫檔(`-R`),可在沒有 check-out 的目錄查詢 |
837
+ | `repository` | string | check-out 的倉庫 | 直接指定倉庫檔(`-R`),例如 `repos/app.fossil`;可在沒有 check-out 的目錄查詢 |
838
+ | `database` | string | — | 查一般的 SQLite 檔而非倉庫(`--no-repository`),例如 chat 存檔 |
779
839
  | `workspace` | string | 見 admin §2.1 | — |
780
840
 
781
841
  輸出是製表符分隔的表格,最後一行是 `N row(s).`;空結果印 `No rows.`。查詢以 `--readonly` 開啟,
@@ -802,7 +862,7 @@ ERROR: the query must start with SELECT, WITH, PRAGMA or EXPLAIN.
802
862
  ### 4.1 `fossil_add`
803
863
 
804
864
  ```bash
805
- fossil add [--dotfiles] [-f] [--ignore GLOBS] <files...>
865
+ fossil add [--dotfiles] [-f] [--ignore GLOBS] [--case-sensitive 1|0] [--clean CSG] [--allow-reserved] <files...>
806
866
  fossil add --reset [-v] # reset: true,不需要 files
807
867
  ```
808
868
 
@@ -812,6 +872,9 @@ fossil add --reset [-v] # reset: true,不需要 files
812
872
  | `force` | boolean | `true` | 預設加 `-f`,否則命中 `ignore-glob` 的檔案會讓 fossil 互動式詢問,服務端會卡住 |
813
873
  | `dotfiles` | boolean | `false` | `--dotfiles` 遞迴點檔案 |
814
874
  | `ignore` | string | — | `--ignore` 的 CSG,用於略過未管理檔案 |
875
+ | `clean` | string | — | `--clean` 的 CSG,把符合的未管理檔案移出版本控制 |
876
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
877
+ | `allow_reserved` | boolean | `false` | 允許加入 Windows 保留檔名(`--allow-reserved`) |
815
878
  | `reset` | boolean | `false` | `--reset` 清掉 ADDED 狀態,只回報不新增 |
816
879
  | `verbose` | boolean | `false` | `-v` 逐檔回報;只在 `reset: true` 時送出 |
817
880
  | `workspace` | string | 見 admin §2.1 | — |
@@ -823,8 +886,8 @@ fossil add --reset [-v] # reset: true,不需要 files
823
886
  ### 4.2 `fossil_rm`
824
887
 
825
888
  ```bash
826
- fossil rm [--hard] [--soft] [-n] <files...>
827
- fossil rm --reset [--verbose] <files...>
889
+ fossil rm [--hard|--soft] [--case-sensitive 1|0] [-n] <files...>
890
+ fossil rm --reset [--verbose] [-n] <files...>
828
891
  ```
829
892
 
830
893
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -835,15 +898,17 @@ fossil rm --reset [--verbose] <files...>
835
898
  | `dry_run` | boolean | `false` | `-n` 只列出會移除什麼 |
836
899
  | `reset` | boolean | `false` | `--reset` 清掉 DELETED 狀態 |
837
900
  | `verbose` | boolean | `false` | `--verbose` 逐檔回報(配合 `reset`) |
901
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
838
902
  | `workspace` | string | 見 admin §2.1 | — |
839
903
 
840
- 兩個都給時參數是 `fossil rm --hard --soft <files>`——fossil 不報錯,實測後一個 flag 生效(檔案仍在磁碟上),
841
- 所以 `keep` 覆蓋 `force`。
904
+ `keep` 與 `force` 同時給時只送 `--soft`(fossil 的 `--soft` 本來就覆蓋 `--hard`)。
905
+ `reset: true` 時只送 `--reset`,`--verbose` 與 `-n` 一併帶上;`force`/`keep` 在這種情況不送出,
906
+ 因為 fossil 只接受 `--verbose` 與 `--dry-run` 搭配 `--reset`。
842
907
 
843
908
  ### 4.3 `fossil_mv`
844
909
 
845
910
  ```bash
846
- fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
911
+ fossil mv --hard|--soft [--case-sensitive 1|0] [-n] <old> <new>
847
912
  ```
848
913
 
849
914
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -852,6 +917,7 @@ fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
852
917
  | `new_name` | string | **必填** | 目標路徑 |
853
918
  | `hard` | boolean | `true` | `--hard` 同步改磁碟;`false` 時用 `--soft` 只記錄 RENAME 事件 |
854
919
  | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
920
+ | `dry_run` | boolean | `false` | 只印出 RENAME 事件(`-n`) |
855
921
  | `workspace` | string | 見 admin §2.1 | — |
856
922
 
857
923
  `hard` 預設 `true`:既記錄 RENAME 事件也在磁碟改名;`hard: false` 只記錄。
@@ -859,8 +925,8 @@ fossil mv --hard|--soft [--case-sensitive 1|0] <old> <new>
859
925
  ### 4.4 `fossil_addremove`
860
926
 
861
927
  ```bash
862
- fossil addremove [--dotfiles] [--ignore GLOBS] [--clean GLOBS] [-n]
863
- fossil addremove --reset [-n] # reset: true
928
+ fossil addremove [--dotfiles] [--ignore GLOBS] [--clean GLOBS] [--case-sensitive 1|0] [-n]
929
+ fossil addremove --reset [-n] [-v] # reset: true
864
930
  ```
865
931
 
866
932
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -868,7 +934,9 @@ fossil addremove --reset [-n] # reset: true
868
934
  | `dotfiles` | boolean | `false` | `--dotfiles` 一併處理 `.` 開頭的檔案 |
869
935
  | `ignore` | string | — | `--ignore` 覆蓋 `ignore-glob` |
870
936
  | `clean` | string | — | `--clean` 追加忽略的 glob |
937
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
871
938
  | `reset` | boolean | `false` | `--reset` 清掉 ADDED/DELETED 狀態,其餘參數被忽略 |
939
+ | `verbose` | boolean | `false` | `-v` 逐檔回報;只在 `reset: true` 時送出 |
872
940
  | `dry_run` | boolean | `false` | `-n` 只列出將要 add / rm 的檔案,工作區不變 |
873
941
  | `workspace` | string | 見 admin §2.1 | — |
874
942
 
@@ -877,9 +945,11 @@ fossil addremove --reset [-n] # reset: true
877
945
  ### 4.5 `fossil_commit`
878
946
 
879
947
  ```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"
948
+ fossil commit -m <message> [-M FILE] [--mimetype TYPE] [--branch B] [--no-warnings]
949
+ [--allow-empty] [--allow-fork] [--allow-conflict] [--allow-older] [--integrate]
950
+ [--private] [--hash] [--no-verify] [--dry-run] [--close] [--bgcolor COLOR]
951
+ [--date-override DATE] [--tag TAG ...] [--user-override U] [files...]
952
+ # stdin = "y\na\n"
883
953
  ```
884
954
 
885
955
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -889,15 +959,25 @@ fossil commit -m <message> [--branch B] [--no-warnings] [--allow-empty] [--close
889
959
  | `branch` | string | — | `--branch` 把新 check-in 放到指定分支 |
890
960
  | `no_warnings` | boolean | `false` | `--no-warnings` |
891
961
  | `allow_empty` | boolean | `false` | `--allow-empty`(無檔案變更也能提交) |
962
+ | `allow_fork` | boolean | `false` | `--allow-fork` 允許這次提交在分支上分叉 |
963
+ | `allow_conflict` | boolean | `false` | `--allow-conflict` 帶著未解決的合併衝突提交 |
964
+ | `allow_older` | boolean | `false` | `--allow-older` 允許比祖先更舊的時間戳記 |
965
+ | `integrate` | boolean | `false` | `--integrate` 關閉所有已併入本分支的分支 |
966
+ | `private_checkin` | boolean | `false` | `--private` 這個 check-in 不隨 push 出去 |
967
+ | `hash` | boolean | `false` | `--hash` 用雜湊而非大小+mtime 判斷檔案變更 |
968
+ | `no_verify` | boolean | `false` | `--no-verify` 跳過提交前的 hook |
969
+ | `dry_run` | boolean | `false` | `--dry-run` 只顯示會提交什麼 |
970
+ | `message_file` | string | — | `-M` 從檔案讀提交訊息,優先於 `message` |
971
+ | `mimetype` | string | — | `--mimetype` 提交訊息的 mimetype |
892
972
  | `close` | boolean | `false` | `--close` 提交後關閉所在分支 |
893
973
  | `bgcolor` | string | — | `--bgcolor` 只套用在這一個 check-in 的背景色 |
894
- | `mtime` | string | — | `--mtime` 指定提交時間(如 `2026-11-17 12:00:00`) |
974
+ | `date_override` | string | — | `--date-override` 指定提交時間(如 `2026-11-17 12:00:00`) |
895
975
  | `tags` | string[] | — | 每個元素一個 `--tag`,把標籤打在這個 check-in 上 |
896
976
  | `user_override` | string | — | `--user-override` |
897
977
  | `workspace` | string | 見 admin §2.1 | — |
898
978
 
899
- **關鍵點**:工具固定向 stdin 寫 `a\n`,因為提交二進位制檔案時 fossil 會問
900
- `commit anyhow (a=all/y/N)?`,沒有 stdin 就會永久阻塞。副作用是該提示被自動回答為“全部”。
979
+ **關鍵點**:工具固定向 stdin 寫 `y\na\n`。fossil 在檔案參數未知時先問 `continue (y/N)?`,
980
+ 再問 `commit anyhow (a=all/y/N)?`;沒有 stdin 就會永久阻塞。
901
981
 
902
982
  ### 4.6 `fossil_revert`
903
983
 
@@ -916,7 +996,8 @@ fossil revert [-r REV] [files...]
916
996
  ### 4.7 `fossil_clean`
917
997
 
918
998
  ```bash
919
- fossil clean -n # dry_run: true
999
+ fossil clean [--dotfiles] [--ignore GLOBS] [--clean CSG] [--keep GLOBS] [-x] [--temp]
1000
+ [--dirsonly] [--emptydirs] [--disable-undo] [--allckouts] [-i] [--case-sensitive 1|0] [-v] [-n]
920
1001
  fossil clean -f # all_files: true
921
1002
  fossil clean --no-prompt # 都不給(預設)
922
1003
  ```
@@ -925,9 +1006,22 @@ fossil clean --no-prompt # 都不給(預設)
925
1006
  | --- | --- | --- | --- |
926
1007
  | `dry_run` | boolean | `false` | 只列出會刪除的檔案(`-n`) |
927
1008
  | `all_files` | boolean | `false` | 不確認直接刪除(`-f`) |
1009
+ | `dotfiles` | boolean | `false` | 一併處理 `.` 開頭的檔案(`--dotfiles`) |
1010
+ | `ignore` | string | — | `--ignore` 覆蓋 `ignore-glob` |
1011
+ | `clean` | string | — | `--clean` 追加忽略的 glob |
1012
+ | `verily` | boolean | `false` | `-x` 連被忽略的檔案也處理 |
1013
+ | `temp` | boolean | `false` | 連暫存檔一起清(`--temp`) |
1014
+ | `dirs_only` | boolean | `false` | 只刪空目錄(`--dirsonly`) |
1015
+ | `empty_dirs` | boolean | `false` | 一併刪除空目錄(`--emptydirs`) |
1016
+ | `keep` | string | — | `--keep` 的 CSG,符合的未管理檔案永不刪除 |
1017
+ | `disable_undo` | boolean | `false` | `--disable-undo` 不留 undo 備份 |
1018
+ | `all_checkouts` | boolean | `false` | `--allckouts` 連巢狀 check-out 的空目錄一起掃 |
1019
+ | `prompt` | boolean | `false` | `-i` 每個檔案都問(等於關閉 undo 備份) |
1020
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
1021
+ | `verbose` | boolean | `false` | 逐檔回報(`-v`) |
928
1022
  | `workspace` | string | 見 admin §2.1 | — |
929
1023
 
930
- 三態互斥,優先順序 `dry_run` > `all_files` > `--no-prompt`。預設 `--no-prompt` 是為了不阻塞;
1024
+ 三態互斥,優先順序 `dry_run` > `all_files` > `--no-prompt`;`verily` 時不送 `--no-prompt`。預設 `--no-prompt` 是為了不阻塞;
931
1025
  它等於“刪除所有未跟蹤檔案且不再確認”,所以**先 `dry_run: true` 預覽**。空輸出 → `Nothing to clean.`
932
1026
 
933
1027
  ### 4.8 `fossil_stash`
@@ -953,16 +1047,27 @@ fossil stash ls|pop|apply|drop|diff [STASH_ID]
953
1047
  ### 5.1 `fossil_tag`
954
1048
 
955
1049
  ```bash
956
- fossil tag ls
957
- fossil tag add <tag> <checkin>
958
- fossil tag cancel <tag> [<checkin>] # checkin 預設 'tip'
1050
+ fossil tag ls [--raw] [--tagtype TYPE] [-v] [--prefix PREFIX]
1051
+ fossil tag find <tag> [--raw] [-t TYPE] [-n LIMIT]
1052
+ fossil tag add <tag> <checkin> [--raw] [--propagate] [--date-override WHEN] [--user-override USER] [-n]
1053
+ fossil tag cancel <tag> [<checkin>] [--raw] [--date-override WHEN] [--user-override USER] [-n]
959
1054
  ```
960
1055
 
961
1056
  | 參數 | 類型 | 必填/預設 | 說明 |
962
1057
  | --- | --- | --- | --- |
963
- | `action` | `ls` / `add` / `cancel` | `ls` | 要執行的 tag 動作 |
964
- | `tag_name` | string | `add` / `cancel` 時必填 | 標籤名 |
1058
+ | `action` | `ls` / `find` / `add` / `cancel` | `ls` | 要執行的 tag 動作 |
1059
+ | `tag_name` | string | `find` / `add` / `cancel` 時必填 | 標籤名,`find` 支援前綴比對 |
965
1060
  | `checkin` | string | `add` 時必填;`cancel` 預設 `tip` | 要標記或取消的 check-in |
1061
+ | `raw` | boolean | `false` | 不做 shell 轉義(`--raw`) |
1062
+ | `propagate` | boolean | `false` | 把標籤傳播到後代 check-in(`--propagate`),只用於 `add` |
1063
+ | `date_override` | string | — | control artifact 的時間(`--date-override`) |
1064
+ | `user_override` | string | — | control artifact 的使用者(`--user-override`) |
1065
+ | `dry_run` | boolean | `false` | 只印出 control artifact(`-n`),用於 `add`/`cancel` |
1066
+ | `type` | `ci` / `w` / `e` / `f` / `t` | — | 只找這些型別上的標籤(`-t`),用於 `find` |
1067
+ | `limit` | number | — | 最多列出的筆數(`-n`),用於 `find` |
1068
+ | `tagtype` | `propagated` / `singleton` / `cancel` | — | 只列這些種類的標籤(`--tagtype`),用於 `ls` |
1069
+ | `inverse` | boolean | `false` | 反轉 `tagtype` 的篩選(`-v`),用於 `ls` |
1070
+ | `prefix` | string | — | 只列以此開頭的標籤(`--prefix`),用於 `ls` |
966
1071
  | `workspace` | string | 見 admin §2.1 | — |
967
1072
 
968
1073
  `fossil tag cancel` 必須有 artifact id,所以工具補 `tip`;空輸出 → `No tags.`(實測 `fossil tag ls` 輸出 `trunk`)。
@@ -970,25 +1075,38 @@ fossil tag cancel <tag> [<checkin>] # checkin 預設 'tip'
970
1075
  ### 5.2 `fossil_branch`
971
1076
 
972
1077
  ```bash
973
- fossil branch ls
974
- fossil branch new <name> [<basis>] # basis 預設 'current'
1078
+ fossil branch ls [-a] [-c] [-p] [-r] [-t]
1079
+ fossil branch new <name> [<basis>] [--private] [--bgcolor COLOR] [--date-override WHEN] [--user-override USER]
1080
+ fossil branch info|close|reopen|hide|unhide <name> [-n] [-v] [--date-override WHEN] [--user-override USER]
1081
+ fossil branch current
975
1082
  ```
976
1083
 
977
- `branch_name` 在 `action: 'new'` 時必填,否則工具直接返回 `ERROR: 'branch_name' is required for action 'new'.`。
1084
+ `branch_name` 在需要具名分支的動作必填,否則工具直接返回 `ERROR: 'branch_name' is required for action '<action>'.`。
978
1085
  `basis` 省略時補 `current`(fossil 要求顯式 basis)。實測 `fossil branch ls` → `* trunk`。
979
1086
 
980
1087
  | 參數 | 類型 | 必填/預設 | 說明 |
981
1088
  | --- | --- | --- | --- |
982
- | `action` | `ls` / `new` | `ls` | 列出分支或建立新分支 |
983
- | `branch_name` | string | `new` 時必填 | 新分支名 |
1089
+ | `action` | `ls` / `new` / `info` / `current` / `close` / `reopen` / `hide` / `unhide` | `ls` | 分支動作 |
1090
+ | `branch_name` | string | `new` / `info` / `close` / `reopen` / `hide` / `unhide` 時必填 | 分支名 |
984
1091
  | `basis` | string | `current` | 新分支的起點(check-in 或分支) |
1092
+ | `all` | boolean | `false` | 連關閉的分支一起列出(`-a`) |
1093
+ | `closed` | boolean | `false` | 只列關閉的分支(`-c`) |
1094
+ | `private_branches` | boolean | `false` | 連私有分支一起列出(`-p`) |
1095
+ | `reverse` | boolean | `false` | 反向排序(`-r`) |
1096
+ | `time_order` | boolean | `false` | 依時間而非名稱排序(`-t`) |
1097
+ | `private_branch` | boolean | `false` | 新分支標為私有(`--private`) |
1098
+ | `bgcolor` | string | — | 新分支的背景色(`--bgcolor`) |
1099
+ | `dry_run` | boolean | `false` | 只顯示會做什麼(`-n`) |
1100
+ | `verbose` | boolean | `false` | 額外輸出(`-v`) |
1101
+ | `date_override` | string | — | control artifact 的時間(`--date-override`) |
1102
+ | `user_override` | string | — | control artifact 的使用者(`--user-override`) |
985
1103
  | `workspace` | string | 見 admin §2.1 | — |
986
1104
 
987
1105
  ### 5.3 `fossil_merge`
988
1106
 
989
1107
  ```bash
990
- fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binary G] [-f] [-K] [-v]
991
- <branch_or_version>
1108
+ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binary G]
1109
+ [--force-missing] [-f] [-K] [-v] <branch_or_version>
992
1110
  ```
993
1111
 
994
1112
  | 參數 | 類型 | 必填/預設 | 說明 |
@@ -1002,6 +1120,7 @@ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binar
1002
1120
  | `binary` | string | — | 符合此 glob 的檔案不做平行合併(`--binary`) |
1003
1121
  | `force` | boolean | `false` | 即使合併無效也照做(`-f`) |
1004
1122
  | `keep_merge_files` | boolean | `false` | 衝突時保留暫存檔(`-K`) |
1123
+ | `force_missing` | boolean | `false` | 即使有一側內容缺失也合併(`--force-missing`) |
1005
1124
  | `verbose` | boolean | `false` | 逐檔報告合併結果(`-v`) |
1006
1125
  | `workspace` | string | 見 admin §2.1 | — |
1007
1126
 
@@ -1010,7 +1129,7 @@ fossil merge [-n] [--integrate] [--cherrypick|--backout] [--baseline V] [--binar
1010
1129
  ### 5.4 `fossil_update`
1011
1130
 
1012
1131
  ```bash
1013
- fossil update [--latest] [--nosync] [--setmtime] [-K] [-v] [target]
1132
+ fossil update [--latest] [--nosync] [--setmtime] [--force-missing] [--case-sensitive 1|0] [-K] [-W N] [-v] [target]
1014
1133
  fossil update -n [target] # dry_run: true
1015
1134
  ```
1016
1135
 
@@ -1022,7 +1141,11 @@ fossil update -n [target] # dry_run: true
1022
1141
  | `no_sync` | boolean | `false` | `--nosync` 跳過更新前自動 sync |
1023
1142
  | `set_mtime` | boolean | `false` | `--setmtime` 把檔案時間戳設成最後一次相關提交的時間 |
1024
1143
  | `keep_merge_files` | boolean | `false` | `-K` 衝突時保留 `*-baseline` / `*-original` / `*-merge` |
1144
+ | `force_missing` | boolean | `false` | `--force-missing` 即使有一側內容缺失也更新 |
1145
+ | `case_sensitive` | boolean | 依設定 | `--case-sensitive 1\|0` 覆寫大小寫規則 |
1146
+ | `width` | number | — | `-W` 輸出寬度 |
1025
1147
  | `verbose` | boolean | `false` | `-v` 列出每個檔案的處理結果 |
1148
+ | `workspace` | string | 見 admin §2.1 | check-out 目錄 |
1026
1149
 
1027
1150
  **破壞性**:會覆蓋工作區本地改動。`target` 省略時更新當前分支。
1028
1151
 
@@ -1064,17 +1187,21 @@ fossil_timeline { limit: 5 }
1064
1187
 
1065
1188
  1. **`fossil_status` 的未跟蹤檔案來自第二條命令**(`fossil extra`),兩者併發執行。單條失敗時該段渲染成
1066
1189
  `--- STATUS ---` + `ERROR: …`,但 `isError` 只為 `true` 當**兩段都失敗**(`renderSections` 的規則)。
1067
- 2. **`commit` 自動回答互動提示為 `a`(all)**:二進位制檔案與忽略規則的衝突一律照交。
1068
- 3. **`add` 預設 `-f`**:`force: false` 時命中 `ignore-glob` 的檔案會讓 fossil 互動詢問 → 服務端可能掛住,
1069
- 不要在沒有 stdin 支援的情況下傳 `force: false`。
1190
+ 2. **`commit` 自動回答兩個互動提示**:未知檔名參數的 `continue (y/N)?` 答 `y`,內容警告的
1191
+ `Commit anyhow (a=all/y/N)?` 答 `a`(all);二進位制檔案與忽略規則的衝突一律照交。
1192
+ 3. **`add` 預設 `-f`**:`force: false` 時命中 `ignore-glob` 的檔案會讓 fossil 互動詢問,服務端因此停住;
1193
+ 保持預設 `force: true`。
1070
1194
  4. **`clean` 無參數即 `--no-prompt`**(直接刪),不是“只預覽”。先用 `dry_run`。
1071
1195
  5. **`tag cancel` / `branch new` 的預設值**(`tip` / `current`)是工具補的,不是 fossil 原生預設。
1072
1196
  6. **版本表示式**只支援 fossil 自身語法(`tip`、雜湊前綴、`branch:name` 等);`tip-1` 這類寫法會失敗。
1073
- 7. **路徑沒有 `--` 屏障**:以 `-` 開頭的檔名需要 `./` 前綴。
1197
+ 7. **路徑原樣傳遞**:以 `-` 開頭的檔名需要 `./` 前綴。
1074
1198
  8. **除 `fossil_sql` 可用 `repository` 直接查詢外,工具都要求已 open 的 check-out**;只有倉庫檔案(.fossil)時用 admin 的 `fossil_open`。
1075
1199
  9. **`fossil_ignore_from_gitignore` 沿用 fossil 的深度語意**:git 的 `*` 不跨 `/`,fossil 的跨,所以含斜線的樣式
1076
1200
  (`src/*.o`)在 fossil 會連更深的路徑一起匹配。
1077
1201
  10. **`ignore-glob` 沒有否定**:`!` 開頭的行只能略過並在 `NOTE:` 說明,被 git 重新納入的檔案在 fossil 仍被忽略。
1202
+ 11. **`fossil_mv` 的 `--hard`**:目標位置已有未管理的同名檔案時,該檔案被覆寫;來源在先前
1203
+ `hard: false` 只記錄 RENAME 後已不在磁碟上,`--hard` 會以 `cannot open "…" for reading` 失敗,
1204
+ 但 RENAME 事件已寫入。
1078
1205
 
1079
1206
  ---
1080
1207