使用指南
適用對象:使用 isvn 的 IC 設計團隊成員(MEMBER)與專案管理者(PM)。 安裝與專案初始化請看《isvn 安裝與部署指南》;提供給 Terminux 的查詢指令請看《isvn × Terminux 血緣查詢指令參考》。 一步一步的日常操作請看《isvn 使用手冊(任務導向)》;isvn 的整體介紹請看《isvn 介紹》。
0. 適用範圍
本手冊說明 isvn 的圖形介面 isvn-gui(第 3 至 17 節)與命令列工具 isvn(第 18 至 21 節);第 1、2 節說明兩者共用的概念。
用 isvn version 可以查看自己使用的版本:
isvn <版本>
commit: <commit>
build_time: <建置時間>
build_type: <建置類型>
本手冊的畫面取自 TUT01 Demo Kit v3 的示範專案(帳號 learner)。圖號以 U- 開頭;每張圖都有對應的英文介面版本,放在英文版手冊中。
1. isvn 是什麼
isvn 建構在 SVN 之上,為 IC 設計流程提供三件事:
- 版本管理: 每個版本對應一個 SVN branch,你在版本上 checkout、修改、簽入檔案。
- 血緣(Lineage): 建立版本時,由你登記它是從哪個版本衍生的。血緣是使用者的決定,不是系統推算的,每一筆都記錄了誰、何時登記。
- 去重快取(pool): 內容相同的工作檔案在專案的快取池中只存一份,工作副本裡以連結指向它。
isvn 有命令列工具 isvn 與圖形介面 isvn-gui。日常的修改與簽入建議用 GUI;CLI 適合查詢、建立與取得版本,以及寫成腳本。

圖 U-01 isvn 做的三件事,以及各自的資料放在哪裡。
2. 核心概念
2.1 版本 ID
版本 ID 固定是四段:
<phase>/<block>/<stage>/<version> 例如 trial/cpu/200_fe_datain/v2
- 必須剛好四段;每一段不可為空、不可是
.或..、不可含空白。 - 版本 ID 同時是 SVN branch 的名稱,也是血緣中的節點名稱。
- 指令中一律使用完整的四段 ID,沒有
v2這類短名。

圖 U-02 四段版本 ID,以及它出現的三個地方。
2.2 工作區與工作副本
- 工作區(WORKSPACE_ROOT) 是你用
isvn member init建立的目錄。它本身不是 SVN 工作副本。 - 每個取得的版本,各自放在
WORKSPACE_ROOT/<phase>/<block>/<stage>/<version>/,是一份獨立的工作副本。一個工作區可以同時有多個版本。 - 工作區的私有狀態放在
WORKSPACE_ROOT/.isvn_local/,請不要手動修改。
WORKSPACE_ROOT/
.isvn_local/ 工作區狀態(勿手動修改)
trial/cpu/200_fe_datain/v2/ 一個版本的工作副本
trial/cpu/400_layout_datain/v1/ 另一個版本的工作副本
需要「目前版本」的 CLI 指令,要在某個版本的工作副本目錄內執行。在工作區根目錄執行時會看到:
isvn: current directory is not a registered isvn version workspace; cd into WORKSPACE_ROOT/<phase>/<block>/<stage>/<version> or pass --parent <version|ROOT>
2.3 LINKED、LOCAL 與檔案狀態
工作副本中的檔案有兩種來源:
| 來源 | 意義 |
|---|---|
| LINKED | 檔案是指向 pool 中唯讀內容的連結。內容相同的檔案只佔一份空間。不能直接修改 |
| LOCAL | 檔案是工作副本中的實體檔。可能是你「設為可編輯」後的副本,也可能是還沒提交的新檔 |
GUI 的「工作」頁另外顯示每個檔案的狀態:
| 狀態(英文介面) | 意義 |
|---|---|
| 乾淨(Clean) | 和版本庫中的內容相同 |
| 可編輯(Editable) | 已設為可編輯,但還沒有修改內容 |
| 已修改(Modified) | 內容和版本庫不同 |
| 新增(New) | 版本庫中還沒有這個檔案 |
| 遺失(Missing) | 版本庫中有,但工作副本中找不到 |
| 已移除(Removed) | 已排定從版本庫移除 |
| 衝突(Conflict) | SVN 回報衝突,必須先處理才能繼續 |
- 取得版本後,檔案都是 LINKED。
- 修改受管的檔案之前,必須先「設為可編輯」,它才會變成 LOCAL(第 7 節)。
- 簽入成功後,檔案會回到 LINKED。

圖 U-03 檔案的來源(LINKED/LOCAL)與狀態如何隨動作改變。
pool 物件被回收時: 空間不足時,PM 的回收作業可能刪除仍在使用的 pool 物件,LINKED 檔案會暫時斷開。下一次用 isvn 指令(checkout、status、update、edit、revert)碰到它時,isvn 會從 SVN 取回內容並重新連結,內容不會遺失。EDA 工具如果直接開啟斷開的檔案會讀取失敗;遇到時先在該版本目錄執行一次 isvn status。
2.4 四種「版本」
| 名稱 | 說明 |
|---|---|
| Repository Version | SVN repository 中存在的版本 |
| Local Working Version(本機工作版本) | 已經 checkout 到目前工作區的版本 |
| Active Working Version(使用中的工作版本) | 「工作」頁目前操作的那一個本機版本 |
| Inspected Version(檢視中的版本) | 「探索」頁正在查看的版本 |
請記住三件事:
- 在「探索」頁選取版本,不會改變「工作」頁使用中的版本。
- Checkout 成功,也不會自動改變使用中的版本。
- 只有明確執行「設為啟用並開啟工作」,或在「工作」頁的本機工作版本清單中選取,才會切換使用中的版本。

圖 U-04 四種「版本」是同一份清單上的四個標記(示範專案)。
2.5 血緣
- 血緣記錄「這個版本的上游(parent)是誰」,每個版本最多一個直接上游。
- 上游在
create時決定:來自--parent,或來自你當時所在的版本目錄。isvn 不會從 SVN 的複製來源或檔案內容推斷血緣。 - 血緣只增不改:刪除版本是「加上一筆移除紀錄」,舊紀錄仍然查得到。
- 取得版本不會帶出上游: checkout 一個版本,只會得到這個版本的檔案。需要上游的內容時,另外 checkout 上游版本,或使用
checkout-ancestor(第 18.3 節)。 - 新版本是從上游的 SVN branch 複製出來的,所以它一開始就包含上游的所有檔案,
isvn log也會列出上游的提交。

圖 U-05 示範專案六個版本的血緣。
2.6 角色
| 角色 | 判定方式 | 能做什麼 |
|---|---|---|
| PM | 專案目錄中 .isvn 的擁有者(執行 admin init 的帳號) |
全部功能,包含 GC 等維護操作 |
| MEMBER | 屬於專案的 Linux group | 日常操作;維護功能只能做唯讀檢查 |
| DENIED | 不屬於專案 group | GUI 只顯示「拒絕存取」,不讀取任何專案資料 |
GC 的權限在 CLI 也會檢查:不是 PM 的帳號執行 isvn gc 會得到 AUTHORIZATION_DENIED。
3. 啟動 GUI
3.1 啟動
在已經完成 isvn member init 的工作區中啟動:
cd <WORKSPACE_ROOT>
isvn-gui
- 使用專案安裝包時,先
sourcePM 提供的環境檔,isvn-gui就在PATH上。 - 使用 Portable 評估版時,執行
~/.local/opt/isvn/current/isvn-gui。 - GUI 以啟動時所在的目錄決定專案與工作區。一個 GUI 視窗只處理一個專案,沒有切換專案的功能;要操作另一個專案,請到那個專案的工作區另外啟動。
- 啟動後直接進入「工作」頁。

圖 U-06 第一次開啟 GUI:「工作」頁,工作區中還沒有任何版本。
3.2 語言與主題
- 介面有繁體中文、简体中文、English 三種語言。GUI 啟動時是繁體中文、深色主題。
- 右上角顯示目前語言的按鈕切換語言,順序是 繁體中文 → 简体中文 → English。
- 語言按鈕右邊的按鈕切換深色與淺色主題。本手冊的畫面都是深色主題。
本手冊的介面文字以繁體中文為主,第一次出現時附上英文。完整對照見附錄 A。
3.3 同一個專案只有一個視窗
同一個使用者、同一個專案只會有一個 GUI:
- 再次啟動時不會開第二個視窗;終端機會印出
isvn-gui activation acknowledged,原本的視窗如果被隱藏會重新顯示。 - 使用中的版本、執行中的操作與尚未送出的內容都不受影響。
- 不同專案可以各自啟動。
3.4 舊版介面
環境變數 ISVN_GUI_SHELL 可以選擇介面:
ISVN_GUI_SHELL=legacy isvn-gui # 暫時使用舊版介面
ISVN_GUI_SHELL=new isvn-gui # 新介面;不設定時也是新介面
- 只接受
new與legacy,其他值會拒絕啟動。 - 同一個專案的新介面正在執行時,不能同時啟動舊版介面;請先正常結束。
- 本手冊只說明新介面。舊版介面的簽入按鈕執行的是單一路徑的
isvn checkin(第 19.2 節)。
3.5 無法啟動時
| 終端機訊息 | 原因 | 處理 |
|---|---|---|
ISVN_GUI_SHELL must be exactly 'new' or 'legacy' |
環境變數的值不合法 | 改成 new、legacy,或取消設定 |
isvn-gui: refusing to start without its own isvn CLI |
安裝目錄中找不到配對的 isvn(Portable 評估版) |
重新安裝,不要只複製 isvn-gui |
| 提到另一種介面模式正在執行 | 同一個專案已有另一種介面的視窗 | 先結束那個視窗 |
An existing GUI endpoint could not be authenticated |
XDG_RUNTIME_DIR 的路徑特別長(常見於容器或測試環境) |
從一般桌面環境的終端機啟動 |
| 視窗只顯示「拒絕存取」(Access Denied) | 你的帳號不屬於專案 group | 請管理員加入 group 後重新登入 |
4. 畫面導覽
4.1 上方列
由左到右(圖 U-07 的編號):① 專案名稱;② 四個頁面的分頁;③ 角色(PM/MEMBER);④ 語言按鈕;⑤ 主題按鈕;⑥ 後端狀態(「後端就緒」)。

圖 U-07 上方列:① 專案 ② 頁面分頁 ③ 角色 ④ 語言 ⑤ 主題 ⑥ 後端狀態。
4.2 四個頁面
首頁(Home) | 工作(Work) | 探索(Explore) | 維運(Maintenance)
4.3 下方狀態列
所有頁面都看得到(圖 U-08 的編號):
- ① 目前狀態,例如「就緒」;
- ② 上一個動作與結果,例如「上次動作: work-read-workStatus · success」;
- ③ 目標版本;
- ④ 儲存狀態(「儲存正常」);
- ⑤ 「操作中心」(Operation Center):列出執行中與需要處理的操作;
- ⑥ 「活動紀錄」(Activity Log):列出你在這個專案執行過的操作(第 17 節);
- ⑦ GUI 的 build 資訊,格式是
isvn-gui <版本> · <commit> · <建置類型>。
操作完成時不會自動切換頁面或使用中的版本。要看某個操作的結果,在操作中心點選它。

圖 U-08 下方狀態列:① 狀態 ② 上次動作 ③ 目標版本 ④ 儲存狀態 ⑤ 操作中心 ⑥ 活動紀錄 ⑦ build 資訊。

圖 U-32 操作中心。
5. 首頁
首頁是唯讀的摘要:「目前工作版本」、「本機 checkout」的數量、「操作健康狀態」、「近期活動」,以及「繼續工作」(Continue Work)按鈕。
- 「繼續工作」只會切到「工作」頁,不會改變使用中的版本。
- 「操作健康狀態」一格顯示「請檢視操作中心」:操作的詳細狀態要到下方的操作中心看。
- 「近期活動」是活動紀錄中列出的操作數量(第 17 節)。
- 首頁不會執行任何變更。

圖 U-09 首頁:使用中的版本、本機 checkout 數量與「繼續工作」。
6. 工作頁
「工作」頁是日常操作的中心,分成三個區域(圖 U-10 的編號):① 本機工作版本、② 檔案狀態、③ 工作流程。
頁首顯示「使用中的工作版本」。還沒有選定時顯示「尚無使用中版本」,檔案清單是空的。

圖 U-10 「工作」頁的三個區域:① 本機工作版本 ② 檔案狀態 ③ 工作流程。
6.1 本機工作版本(Local Working Versions)
- 只列出已經 checkout 到這個工作區的版本。
- 點選其中一個,後端確認它仍然存在後,它就成為使用中的版本。這個動作不會 checkout 或建立任何版本。
- 每個版本會顯示狀態:乾淨、已變更、衝突、操作進行中、需要復原。「操作進行中」只是進度指示(第 12 節);「需要復原」表示有被中斷的操作要先處理(第 16 節)。

圖 U-31 工作區中有兩個版本時的「本機工作版本」清單;反白的是使用中的版本。
6.2 檔案狀態(File Status)
- 欄位:路徑、狀態、來源(LINKED/LOCAL)、大小。
- 上方的篩選:All、Changed、Editable、LOCAL、Conflict。
- 每一列前面的方框用來勾選;所有動作只處理你明確勾選的項目。「選取所有變更」可以一次勾選所有有變更的項目。
- 頁首會統計變更,例如「1 已變更」「1 LOCAL」。

圖 U-11 有變更時的「工作」頁:notes.txt 是新增的檔案,top.v 已修改;頁首統計「2 已變更」「2 LOCAL」。
6.3 工作流程(Workflow)
| 按鈕 | 用途 | 說明在 |
|---|---|---|
| 設為可編輯(Make Editable) | 把 LINKED 檔案變成自己的 LOCAL 副本 | 第 7.1 節 |
| 還原(Revert) | 放棄本機修改,回到 LINKED | 第 7.2 節 |
| 捨棄本機(Discard Local) | 刪除從未提交過的新檔 | 第 7.3 節 |
| 加入簽入批次(Add to Checkin Batch)、檢視簽入(Review Checkin) | 提交勾選的項目。「檢視簽入」在區域的最下方,上面是「簽入訊息」欄位 | 第 9 節 |
| 移除(Remove) | 從版本庫移除受管的項目 | 第 10 節 |
| 建立衍生版本(Create Derived Version) | 以使用中的版本為上游建立新版本 | 第 11.3 節 |
| 在探索檢視(Inspect in Explore) | 到「探索」頁查看使用中的版本 | 第 14 節 |
「建立衍生版本」與「在探索檢視」在頁首的右上角也各有一個按鈕,作用相同。「重新整理」(Refresh)重新讀取工作副本的狀態;在終端機或其他工具改過檔案之後,按它更新畫面。
按鈕是灰色時,代表目前的選取或狀態不允許這個動作。可不可以執行由後端決定,請依畫面上的原因處理,不要改用其他方式繞過。
GUI 與支援預覽的 Batch 操作都依同樣的順序進行:預覽 → 確認 → 執行 → 結果。預覽之後如果檔案或版本庫有變動,執行時會被擋下並要求重新預覽。
單一路徑指令(isvn edit、isvn checkin、isvn revert、isvn remove)不提供獨立預覽,會直接執行;請參閱User Guide 第 19.2 節。
7. 修改受管檔案
7.1 設為可編輯
LINKED 檔案指向共用的唯讀內容,不能直接覆寫。要修改時:
- 在「檔案狀態」勾選檔案。「工作流程」會顯示「已選路徑 · 1」。
- 按「設為可編輯」。
- 確認畫面顯示:「將受管檔案轉為可編輯的本機副本,不會建立版本庫修訂。」這個畫面不會列出檔名,按下之前請先確認勾選的項目。
- 按「套用」(Apply)。結果畫面顯示「已完成」與「未建立版本庫修訂」,再按「完成」(Done)。
- 檔案的狀態變成「可編輯」、來源變成 LOCAL。現在可以用編輯器或 EDA 工具修改它。

圖 U-12 「設為可編輯」的確認畫面(中間的空白已省略)。

圖 U-13 設為可編輯之後:top.v 的狀態是「可編輯」,來源是 LOCAL。
- pool 中的共用內容不會被修改,其他連結到相同內容的工作副本不受影響。
- 系統會為這個檔案保存一份「可編輯憑證」,之後簽入時用來確認它是合法的受管副本。用其他方式(包括
isvn edit)變成 LOCAL 的檔案沒有憑證,批次簽入時會被擋下;用isvn edit開啟的檔案請用isvn checkin提交(第 19.2 節),或先還原,再重新設為可編輯。
7.2 還原
要放棄受管檔案的本機修改:
- 勾選檔案,按「還原」。
- 確認畫面會警告「這會捨棄本機變更」:「還原受管狀態並捨棄本機修改,不會建立版本庫修訂。」
- 想保留修改就按「取消」;確定要放棄才按「套用」,再按「完成」。
檔案回到「乾淨」與 LINKED。

圖 U-14 「還原」的確認畫面:會捨棄本機變更(中間的空白已省略)。
7.3 捨棄本機
「捨棄本機」只用於從未提交過的新檔(狀態為「新增」):
- 它只刪除本機的檔案,不會建立版本庫修訂。
- 受管的檔案不能用它刪除;要從版本庫移除請用「移除」(第 10 節)。
- 這是無法復原的本機刪除,確認前請看清楚項目。
8. 匯入外部檔案
把工作區以外的檔案或資料夾複製到使用中的版本。匯入只是本機複製,不會寫入版本庫;之後仍要簽入。
8.1 拖放的目的地
- 拖到資料夾的那一列:目的地是那個資料夾。
- 拖到「檔案狀態」的空白處:目的地是使用中版本的根目錄。
- 檔案的那一列不能當作目的地。
- 拖入資料夾時,會保留最上層的資料夾名稱。例如把外部的
rtl/拖到src資料夾,結果是src/rtl/...。
8.2 流程
- 拖入檔案或資料夾。放開時只會開始預覽,還沒有複製任何東西。
- 「匯入預覽」列出每個來源對應的目的路徑、大小,以及目的地是否已經有檔案。
- 目的地有同名、而且是從未提交過的新檔時,可以逐項勾選「取代 LOCAL」(Replace Local),預設不勾選。
- 按「匯入工作並加入批次」(Import to Work & Add to Batch),確認後開始複製。
- 完成後,匯入的路徑會加入這個版本的簽入批次。輸入簽入訊息並完成簽入(第 9 節),檔案才會進版本庫。
8.3 安全規則
- 來源中有 symlink(包括資料夾內層的)或特殊檔案:整個匯入被拒絕。
- 空資料夾:不會匯入。
- 目的地是受管的檔案(LINKED、設為可編輯的 LOCAL,或版本庫中有但本機遺失的項目):一律不允許覆寫。要修改受管檔案請用「設為可編輯」。
- 預覽之後來源或目的地有變動:執行時會被擋下,需要重新預覽。
- 匯入要嘛全部完成,要嘛全部不做,不會留下一半。
- 目標空間不足時會被擋下。
- 規模上限:單次最多 50,000 個檔案、總量 1 TiB、單一檔案 256 GiB。
- 外部來源的絕對路徑不會寫進活動紀錄、通知或錯誤訊息。
9. 批次簽入
簽入批次屬於單一版本,而且只存在於這次的 GUI 執行期間。
9.1 流程
- 在「檔案狀態」勾選要提交的檔案或資料夾。勾選的項目會出現在右邊的「簽入批次」中。
- 在「簽入訊息」欄位輸入訊息(必填),按「檢視簽入」。
- 「簽入批次檢視」(Checkin Batch Review)列出選取範圍與這次批次確切的內容:後端已經展開資料夾、去除重複,並略過沒有變更的項目。每個項目旁邊是它的狀態,例如「就緒」。確認後按「繼續」(Continue)。
- 「確認簽入」(Confirm Checkin)再次顯示同一份清單與訊息。按「簽入」(Checkin)執行。
- 結果畫面顯示「簽入完成」(Checkin complete)、「已精確簽入一次」(Committed exactly once)與修訂編號,例如「版本庫修訂 r14」。按「關閉」回到「工作」頁。

圖 U-15 批次簽入第一步:「簽入批次檢視」列出確切的內容(空白處已省略)。

圖 U-16 批次簽入第二步:「確認簽入」顯示清單與訊息(空白處已省略)。

圖 U-17 批次簽入的結果:「簽入完成」與修訂編號(空白處已省略)。
項目不能提交時,「簽入批次檢視」會顯示「簽入已封鎖」(Checkin is blocked)與每個項目的原因,「繼續」不能按。
9.2 規則
- 一個批次只做一次 SVN commit,對應一個修訂。
- 只提交批次中列出的路徑,不會把沒選到的檔案一起帶進去。
- 檢視之後內容有變動,執行時會停下來並要求重新檢視。
- 成功後檔案回到 LINKED。
- 沒有「部分成功」:批次要嘛整批提交,要嘛都不提交。
- 設為可編輯後才修改的檔案才能簽入(見第 7.1 節的憑證說明)。
- 規模上限:單一批次最多 50,000 個項目。
9.3 同時進行的操作
- 操作不會因為另一個操作正在執行而被拒絕或排隊,不論那個操作屬於你的帳號還是其他帳號。
- 多個帳號可以使用同一個專案,各自在自己的工作區中操作。
- 在 GUI 中,一個版本的操作還在執行時,可以在同一個版本或另一個版本開始另一個操作。本機工作版本清單中的「操作進行中」只是進度指示(第 12 節)。
- 被中斷的操作(當機、強制離開)必須先在操作中心復原或驗證,這個版本才能再變更(第 16 節)。
- 設計流程中沒有兩個人同時修改同一個 stage 版本的理由,isvn 也不為此仲裁;從過時的工作副本提交時,Subversion 會照常拒絕。
10. 移除
「移除」是把受管的檔案或資料夾從這個版本的 SVN branch 移除:
- 勾選受管的項目,按「工作流程」中紅色框內的「移除」。
- 出現「從版本移除」(Remove from Version)的確認畫面:「一次移除只會建立一個版本庫修訂。移除不會進入簽入批次。」這個畫面不會列出檔名,按下之前請先確認勾選的項目。
- 輸入「移除訊息(必填)」。項目有本機修改時,需要另外確認放棄這些修改。
- 按右下角的「移除」執行。結果畫面顯示「已完成」與修訂編號,例如「版本庫修訂 r15」;再按「完成」。

圖 U-18 「從版本移除」的確認畫面:訊息必填(中間的空白已省略)。
「移除」和「捨棄本機」的差別:
| 移除 | 捨棄本機 | |
|---|---|---|
| 對象 | 受管的項目 | 從未提交過的新檔 |
| 版本庫 | 建立一個修訂 | 不變 |
畫面顯示 USE_DISCARD_LOCAL 這類原因時,代表你選的項目應該用另一個動作處理。
「移除」移除的是版本中的檔案;刪除整個版本是 CLI 的 isvn delete(第 18.3 節)。
11. 取得版本:Checkout、設為啟用、建立衍生版本
11.1 Checkout 版本庫中的版本
在「探索」頁操作:
- 按「選擇版本」(Choose version),在清單中點選要的版本。
- 「檢視中的版本」欄位顯示這個版本,下方提示:「這個版本不在此工作區中。Checkout 只會建立它的本機 working copy,不會改變啟用中的版本。」
- 按右上角的「Checkout…」。對話框列出版本與將要建立的本機資料夾。
- 按對話框中的「Checkout」。按「取消」則什麼都不會改變。
- 完成後提示版本已 checkout,並再次說明啟用中的版本沒有改變。

圖 U-19 「探索」頁的「選擇版本」清單。

圖 U-20 Checkout 的確認對話框:列出版本與將要建立的本機資料夾。
也可以在終端機執行:
cd <WORKSPACE_ROOT>
isvn checkout trial/cpu/200_fe_datain/v2
再回到 GUI 按「重新整理」(Refresh)。
兩種方式的結果相同:一次只 checkout 一個版本,使用中的版本不變。
11.2 設為啟用並開啟工作
要開始操作已經 checkout 的版本:
- 在「探索」頁,檢視中的版本是它的時候,按「設為啟用並開啟工作」(Set Active and Open Work);或
- 在「工作」頁的本機工作版本清單中點選它。
後端確認它仍是本機的工作副本之後,才會更新使用中的版本並切到「工作」頁。確認失敗時,原本使用中的版本不變。版本還沒有 checkout 時,會提示先 Checkout。

圖 U-21 Checkout 完成後的提示,以及右上角的「設為啟用並開啟工作」。
11.3 建立衍生版本
「建立衍生版本」以使用中的版本作為上游,依序執行三個步驟:
建立 → 檢出 → 設為使用中
- 按下「建立衍生版本」後會先出現確認對話框(圖 U-22),兩個按鈕是「取消」與「建立 → 檢出 → 設為使用中」。
- 新版本的 ID 由 GUI 決定:使用中版本的 ID 後面加上
.d。例如使用中的版本是trial/cpu/200_fe_datain/v2,新版本就是trial/cpu/200_fe_datain/v2.d。要使用其他名稱,請用 CLI 的isvn create(第 18.2 節),再回到 GUI 設為啟用。 - 建立失敗(例如同名的版本已經存在):後面的步驟不會執行。
- 檢出失敗:新版本已經存在於版本庫,原本使用中的版本不變;可以只重試檢出,不會重複建立。
- 檢出成功後才會設為使用中。

圖 U-22 「建立衍生版本」的確認對話框。
11.4 重新開啟 GUI 之後
GUI 會記住使用中的版本。重新開啟時,「工作」頁直接以上次使用中的版本開啟;GUI 只檢查它是否仍然存在、是否仍是本機的工作副本,不會自動 checkout,也不會自己挑另一個版本。
活動紀錄(第 17 節)同樣會保留到下一次開啟。
12. 同時處理多個版本
版本 A 的操作還在執行時:
- 可以切換到版本 B 正常讀取與操作;A 會顯示「操作進行中」,這只是進度指示。
- 不必等 A 完成,就可以在 B 或 A 開始另一個操作(第 9.3 節)。
- A 完成後畫面不會自動切回 A;結果顯示在 A 的那一列與操作中心,點選才會前往。
每個版本各自保留尚未送出的內容(勾選、訊息、匯入待處理的路徑),切換版本不會混在一起。關閉整個 GUI 之後,這些內容不會保留。
13. 關閉視窗與背景操作
沒有操作在執行時,關閉視窗就是正常結束。
有變更操作在執行時關閉視窗,會出現三個選項:
| 選項 | 行為 |
|---|---|
| 在背景執行(Run in Background) | 隱藏視窗,操作繼續進行 |
| 返回操作(Return to Operations) | 取消關閉,回到 GUI |
| 強制離開(Force Exit) | 再確認一次後,停止執行中的子程序 |
在背景執行之後:
- 再次啟動同一個專案的 GUI,會回到原本的視窗。
- 所有操作都成功時,系統保存結果後自動結束背景中的 GUI。
- 只要有一個操作失敗、結果未知,或需要人工處理,GUI 會留在背景,等你再次啟動來處理。
強制離開不保證復原。 如果操作停在無法判斷是否已提交的位置,下一次啟動會要求先驗證或復原。系統不會自動重試、還原或提交,必須由你看過證據後決定。
14. 探索頁
「探索」頁用來查看版本庫與版本之間的關係,不會改變「工作」頁的目標。畫面由上到下(圖 U-23 的編號):
- ① 「檢視中的版本」欄位,以及「Checkout…」與「設為啟用並開啟工作」按鈕;
- ② 「選擇版本」與「重新整理證據」;
- ③ 「血緣與證據探索」:左邊是「查詢面板」,中間是「血緣圖」,右邊是「節點檢視器」;
- ④ 下方的「SVN Commit 歷史」「版本來源紀錄」「版本關係」,以及右邊的「檢視器」與「來源核對」。

圖 U-23 「探索」頁:① 檢視中的版本 ② 選擇版本 ③ 血緣與證據探索 ④ 提交歷史、來源紀錄與版本關係。
主要內容:
| 區塊 | 內容 |
|---|---|
| 血緣與證據探索(Lineage & Evidence Explorer) | 「版本血緣」可以查詢上游、祖先鏈、根版本與完整血緣;「檔案血緣」可以查詢某個路徑出現在哪些版本。結果畫在「血緣圖」上,點選節點可以在「節點檢視器」看到詳細資訊 |
| 版本關係(Version Relationships) | 檢視中版本的登記資料:建立時間與帳號 |
| SVN Commit 歷史(SVN Commit History) | 這個版本的提交歷史 |
| 版本來源紀錄(Provenance Log) | 使用者登記的版本來源決定 |
| 來源核對(Source Check) | 把檢視中的版本和可取得的來源資訊比對,提供檢視建議;僅供檢視 |
閱讀時請分清楚:
- 提交歷史是 SVN 的修訂紀錄;血緣是版本之間登記的來源關係。兩者不同。
- 血緣查詢結果旁的「宣告來源」(Declared provenance)與「未驗證內容」(Not content-verified)表示:這是登記的資料,不代表檔案內容已經過驗證。
- 「來源核對」只供檢視,不會套用、修復、checkout 或修改任何版本。
- 檔案相關的查詢只看得到已經 checkout 到你的工作區的版本(原因見《isvn × Terminux 血緣查詢指令參考》第 4.1 節)。

圖 U-24 版本血緣(Ancestor Chain)的查詢結果:血緣圖與節點檢視器。

圖 U-25 檔案血緣(Versions)的查詢結果:top.v 出現在本機已 checkout 的兩個版本。
15. 維運頁與角色
15.1 PM
PM 看到完整的「維護控制中心」(Maintenance Control Center)。上方有「重新整理」「完整性檢查」「GC 預覽」三個按鈕;下面依序是「維護總覽」「快取池」「保留活動」「容量健康」「完整性檢查」「管理總覽」,右邊是「維護操作」:「清理預覽」,以及標示為危險區域的「快取回收」與「完整 GC」。
-
進入頁面時各區塊顯示「尚未載入」;按「重新整理」讀取資料,按「完整性檢查」檢查血緣紀錄。
-
PM GUI 中會變更資料的維運動作都要先預覽,再明確確認。
-
有需要復原的操作時,動作可能被停用;先在操作中心處理那個操作(第 16 節)。

圖 U-26 PM 的「維運」頁:維護控制中心。
15.2 MEMBER
MEMBER 可以進入「維運」頁,但只看到「維運診斷」:可以執行「驗證完整性」(Verify integrity)這類唯讀檢查。清理、回收、修復與所有變更都由後端拒絕,不只是按鈕停用;直接用 CLI 也一樣。
15.3 DENIED
只顯示「拒絕存取」。系統不會建立任何頁面,也不讀取專案資料。
16. 操作結果與復原
| 結果 | 意義 | 你該做什麼 |
|---|---|---|
| 成功 | 操作完成。變更版本庫的操作會顯示修訂編號 | 無 |
| 失敗(Failed) | 後端確認操作沒有完成,或已安全復原 | 依原因修正後重新預覽,不要沿用舊的預覽 |
| 結果未知(Outcome Unknown) | 提交過程被中斷,無法直接判斷版本庫是否已經改變 | 按「驗證版本庫歷史」(Verify repository history)讓系統核對。不要直接重試,以免重複提交 |
| 需人工檢視/需要復原(Manual Review/Recovery Required) | 工作副本、紀錄與版本庫的證據對不起來,或上次強制離開、當機留下未完成的操作 | 在操作中心開啟該操作,只執行畫面提供的驗證或復原動作 |
被中斷的操作(當機、強制離開)必須先在操作中心復原或驗證,之後這個版本才能再變更。在這之前,對這個版本的變更會被拒絕(VERSION_RECOVERY_REQUIRED),本機工作版本清單中這個版本顯示「需要復原」。仍在執行中的操作不能復原(OPERATION_IN_PROGRESS);等它結束後再處理。
出現「結果未知」或「需要復原」時:
- 不要手動刪除或修改
.isvn_local/work_operations/裡的任何東西。 - 不要直接重做同樣的簽入或移除。
- 先看操作中心裡那個操作的資訊,再決定。
17. 活動紀錄
按下方狀態列的「活動紀錄」開啟。它列出你在這個專案執行過的操作,最新的在最上面,每個操作一筆:
- 第一行是
<操作> · <n 個項目> · <結果> · r<修訂>,例如設為可編輯 · 1 個項目 · 完成、簽入 · 2 個項目 · 已簽入 · r14;沒有建立修訂的操作沒有最後一段。 - 第二行是版本與時間。
- 讀取與預覽不會列出。
- 首頁的「近期活動」是這裡列出的操作數量。
活動紀錄是「這個使用者、這個專案」範圍的本機摘要,重新開啟 GUI 之後仍然保留:
- 最多保留 200 筆,超過時淘汰最舊的。
- 只保存安全的欄位;不保存外部匯入來源的絕對路徑、備份路徑、原始指令或機密資料。
- 它是操作摘要,不能取代 SVN log 或復原時需要的證據。

圖 U-33 活動紀錄:你在這個專案執行過的操作,最新的在最上面。
18. CLI:查詢與版本操作
除非另外說明,指令都在工作區內執行。需要「目前版本」的指令,請先 cd 到那個版本的工作副本目錄,或在參數中寫出版本 ID。
只讀取專案層級資料的指令(branches、reconcile、lineage verify、lineage audit、pool-stat、admin status、gc、provenance query)在工作區之外也可以執行,條件是設定了環境變數 ISVN_PROJECT_DIR,或人在專案目錄內。
18.1 查詢
| 指令 | 用途 |
|---|---|
isvn version [--json] |
顯示版本、commit、建置時間與類型 |
isvn workspaces [--json] |
列出這個工作區已經 checkout 的版本 |
isvn branches [--json] |
列出版本庫中的所有版本 |
isvn status [<版本>] [--json] |
列出檔案的 SVN 狀態與 LINKED/LOCAL |
isvn work-status <版本> --json |
「工作」頁使用的完整狀態(每個檔案可以做哪些動作、不能做的原因) |
isvn log [<版本>] [--json] |
提交歷史,最多 50 筆 |
isvn ancestry [<版本>] [--json] |
血緣鏈 |
isvn lineage audit [<版本>] [--json] |
血緣的變更紀錄 |
isvn lineage verify [--json] |
檢查血緣紀錄的完整性 |
isvn reconcile [<版本>] [--json] |
回報版本登記的上游與血緣完整性 |
isvn renew-status [<版本>] [--json] |
每個 LINKED 檔案對應的 pool 物件、最近存取時間與引用數 |
isvn status 的每一行是「SVN 狀態、路徑、來源」:
obstructed trial/cpu/200_fe_datain/v2/README.md [LINKED]
M trial/cpu/200_fe_datain/v2/top.v [LOCAL]
? trial/cpu/200_fe_datain/v2/notes.txt [LOCAL]
- LINKED 檔案的 SVN 狀態顯示為
obstructed,這是正常的:工作副本中放的是連結,不是 SVN 原本的實體檔。 M是已修改,?是版本庫中還沒有的新檔,D是排定移除。status不是純唯讀:它會順便修復斷開的 LINKED 檔案。

圖 U-27 isvn workspaces、isvn status、isvn ancestry 與 isvn log 的實際輸出。
isvn ancestry 由近到遠列出上游:
trial/cpu/400_layout_datain/v1
<- trial/cpu/200_fe_datain/v2
<- trial/cpu/200_fe_datain/v1
<- trial/cpu/000_datain/v1
它只顯示資訊,不會取得任何內容。
isvn log 有兩種用法,結果可能不同:
isvn log <版本>直接讀取版本庫,一定包含最新的提交。- 在版本目錄內執行、不寫版本時,顯示的是工作副本目前所在修訂為止的歷史。你剛剛提交的修訂要先執行
isvn update才會出現。
isvn lineage audit 的每一行是「序號 | 時間 | 帳號 | 動作 | 版本 | 舊上游 -> 新上游 | 原因」:
8 | 2026-11-13T18:31:48Z | pm01 | create | trial/cpu/200_fe_datain/v4 | null -> trial/cpu/200_fe_datain/v2 | create
9 | 2026-11-13T18:31:48Z | pm01 | remove | trial/cpu/200_fe_datain/v4 | trial/cpu/200_fe_datain/v2 -> null | delete by user
isvn reconcile 只回報,做兩件事:列出版本登記的上游,並檢查血緣紀錄的完整性。它不會和 SVN 的複製來源比對,也不會修改血緣:
svn copy-source comparison is not available in this MVP
Lineage integrity: ok
提供給外部工具的 isvn provenance query、isvn file query 與 isvn file locate,請看《isvn × Terminux 血緣查詢指令參考》。
18.2 建立與取得版本
isvn create <新版本> --parent <上游版本> # 明確指定上游
isvn create <新版本> --parent ROOT # 沒有上游的根版本
isvn create <新版本> # 在某個版本目錄內執行:以該版本為上游
isvn checkout <版本> # 取得一個版本
isvn update # 在版本目錄內執行:更新到最新
create會在 SVN 建立 branch(從上游複製)、登記血緣,並把新版本 checkout 到工作區。完成時印出created <新版本> from <上游>。- 在工作區根目錄執行
create而沒有--parent,會被拒絕。 - 版本庫剛建立時沒有任何版本,第一個版本要用
--parent ROOT建立。 checkout一次只取得一個版本,檔案都是 LINKED。版本已經在工作區時,它的作用等於更新。update更新目前版本並重建連結。
18.3 上游內容與刪除版本
isvn checkout-ancestor [<版本>] [--depth N] [--yes]
isvn delete <版本>
checkout-ancestor 把上游第 N 層(預設 1)的內容取到工作區:
ancestor depth 1: trial/cpu/200_fe_datain/v2
checkout this ancestor content? (y/n)
- 沒有
--yes時會先顯示上游是誰並詢問;回答y以外的內容就不會取得任何東西。 - 內容放在
WORKSPACE_ROOT/ancestor-<N>/,是一般的 SVN 工作副本(實體檔,不是 LINKED),不會出現在isvn workspaces與 GUI 的本機工作版本清單中。它只供參考。 - 層數超過血緣鏈的長度時,印出
already at root; ancestry depth N is unavailable。 - 需要在 GUI 中操作上游版本時,請直接
isvn checkout <上游版本>。
delete 刪除整個版本:
- 版本還有下游時會拒絕,並列出下游;必須先處理下游。
- 沒有下游時:刪除本機的工作副本、在血緣中加上移除紀錄,並刪除 SVN branch。
- CLI 不限制只有 PM 才能執行,請先和團隊確認再刪除。
refusing to delete trial/cpu/200_fe_datain/v2 because it has descendants:
trial/cpu/200_fe_datain/v4
trial/cpu/400_layout_datain/v1
19. CLI:檔案操作
19.1 建議的做法:batch 指令
GUI 的「設為可編輯」「還原」「捨棄本機」「批次簽入」「移除」背後就是下面這些指令。它們都分成 preview(預覽,取得 plan_hash)與 apply(執行,必須帶回同一個 plan_hash)兩步,輸出都是 JSON。這些指令在工作區內執行,版本以參數指定。

圖 U-28 預覽 → 確認 → 執行 → 結果:batch 指令與 GUI 共用的順序。
修改並簽入一個受管檔案:
cd <WORKSPACE_ROOT>
V=trial/cpu/200_fe_datain/v2
plan_of() { python3 -c 'import json,sys; print(json.load(sys.stdin)["plan_hash"])'; }
# 1. 設為可編輯
plan=$(isvn work-local-op preview --action make-editable --in $V --path constraints.sdc --json | plan_of)
isvn work-local-op apply --action make-editable --in $V --path constraints.sdc --expected-plan "$plan" --json
# 2. 修改檔案
echo "# tighter clock" >> $V/constraints.sdc
# 3. 簽入
plan=$(isvn checkin-batch preview $V --path constraints.sdc --json | plan_of)
isvn checkin-batch apply $V --path constraints.sdc --expected-plan "$plan" --message "tighten clock constraint" --json
plan_of 只是從 preview 的 JSON 取出 plan_hash 的小工具;用 jq -r .plan_hash 也可以。第 2 步請換成你實際的修改。
簽入成功的輸出(節錄):
{"schema":"checkin-batch-result/v1","target_version":"trial/cpu/200_fe_datain/v2","status":"committed","revision":14,"changed_paths_verified":true,"recovery_required":false}

圖 U-34 以 batch 指令修改並簽入一個受管檔案的實際輸出。
| 指令 | 說明 |
|---|---|
isvn work-local-op preview|apply --action make-editable|revert|discard-local --in <版本> --path <路徑>... |
設為可編輯、還原、捨棄本機 |
isvn checkin-batch preview|apply <版本> --path <路徑>... |
批次簽入;apply 需要 --expected-plan 與 --message |
isvn remove-batch preview|apply --from <版本> --path <路徑>... |
移除;apply 需要 --expected-plan 與 --message;項目有本機修改時另加 --allow-discard-local |
isvn work-recovery status|restore|verify [<操作 ID>] |
查看或處理未完成的操作 |
isvn import preview|apply --request-stdin |
匯入;請求內容由 GUI 產生,不建議手動使用 |
寫腳本時請注意:
--path可以重複,一次處理多個路徑。新檔案不需要先設為可編輯,直接checkin-batch即可。preview的結果中,ready或can_apply是false時不能執行;每個項目的reason_code說明原因。- 要檢查 JSON 的
status,不能只看 exit code。checkin-batch apply沒有提交成功時,可能仍以 exit code 0 結束,而status是failed。 - 被後端拒絕時,輸出是
{"schema_version":"work-error/v1","ok":false,"error":{"code":"..."}},exit code 是 1。 - 常見的原因代碼如下,出現在
error.code或預覽結果中各項目的reason_code:
| 代碼 | 意義 |
|---|---|
SELECTION_REQUIRED |
沒有指定 --path |
NOT_CHECKIN_ELIGIBLE |
選取的項目沒有可以提交的變更 |
EDIT_PROVENANCE_REQUIRED |
檔案不是經由「設為可編輯」變成 LOCAL 的;先還原,再重新設為可編輯 |
USE_DISCARD_LOCAL |
這是從未提交過的新檔,請用 discard-local |
PLAN_STALE |
預覽之後內容有變動,重新預覽 |
INVALID_VERSION |
版本沒有 checkout 到這個工作區 |
AUTHORIZATION_DENIED |
需要 PM |
19.2 單一路徑的指令:isvn checkin、isvn remove、isvn edit、isvn revert
這組指令一次處理一個檔案或資料夾。它們沒有預覽與 plan_hash,一個指令直接完成;外部工具(例如 Terminux 的 DQE checkin)呼叫的就是這一組。
isvn edit <檔案> [--in <版本>] # LINKED → LOCAL
isvn checkin <檔案或資料夾> [--to <版本>] # 提交;完成後回到 LINKED
isvn revert <檔案> # 放棄修改,回到 LINKED
isvn remove <檔案或資料夾> [--from <版本>] # 從版本移除並提交
isvn checkin <檔案或資料夾> 只提交指定的路徑與它底下的內容;工作副本中其他地方受管的(LINKED)檔案不受影響。指定資料夾時,資料夾中的新檔案與新資料夾會一起加入,並在同一個修訂中提交(Subversion 忽略清單上的名稱會略過)。提交之後,檔案回到 LINKED。

圖 U-29 isvn checkin <路徑> 提交的範圍:指定檔案時只有那個檔案;指定資料夾時包含其中的修改與新檔案。
範例:修改一個受管的檔案並簽入
cd <WORKSPACE_ROOT>/trial/cpu/200_fe_datain/v2
isvn edit top.v # [LOCAL] trial/cpu/200_fe_datain/v2/top.v
# ……修改 top.v……
isvn checkin top.v # committed r15
| 情況 | 結果 |
|---|---|
| 修改過的檔案、新檔案 | 只提交你指定的路徑,印出 committed r<N>。工作副本中其他檔案的修改不會被帶進去 |
| 資料夾 | 資料夾中已入版檔案的修改,以及其中的新檔案與新資料夾,在同一個修訂中提交,印出 committed r<N> |
| 新檔案所在的資料夾還沒有入版 | 資料夾會一起提交。同一個資料夾中其他還沒入版的檔案不會被帶進去 |
| 內容和版本庫相同 | 不建立修訂,印出 no changes in <名稱> compared with <版本>; nothing was committed,exit code 是 0。用 isvn edit 開啟過的檔案會回到 LINKED |
| 指定的路徑沒有入版,也沒有可以提交的內容 | isvn: nothing to check in under <路徑>,exit code 是 1 |
工作區以外的檔案,加上 --to <版本> |
先複製到該版本的根目錄再提交,印出 copied <檔名> into <版本> and committed r<N>。指令本身仍要在工作區內執行 |
加上 --json |
{"result":"committed","revision":15,"file":"top.v","version":"…","copied":false};沒有變更時是 "result":"unchanged"、"revision":null |
圖 U-30 是實際的終端機紀錄:提交單一檔案、提交含有新檔案的資料夾,以及對沒有變更的路徑執行 isvn checkin。

圖 U-30 以 isvn checkin 提交單一檔案、新的資料夾、資料夾中的新檔案,以及沒有變更時的實際輸出。
isvn remove <檔案或資料夾> 從版本移除指定的路徑,只提交這一次移除:
| 情況 | 結果 |
|---|---|
| 受管的檔案 | 從版本移除並提交,印出 removed in r<N>。其他 LINKED 檔案不受影響 |
| 資料夾 | 連同其中受管的檔案一起移除 |
| 資料夾中有還沒入版的檔案,或有本機修改 | 拒絕(svn: E200005),工作副本與版本庫都不變。先把那些檔案簽入、還原或移走 |
| 資料夾落後版本庫(其中的檔案在資料夾取得之後又被提交過) | 提交被拒絕(svn: E155011 … is out of date),工作副本與版本庫都不變。在版本目錄執行 isvn update,再執行一次 |
| 還沒入版的檔案 | 拒絕,檔案保留。它不在版本庫中,直接刪除檔案即可 |
使用這組指令時要知道的事:
- 不要混用單一路徑的指令與 batch 指令處理同一次修改。 用
isvn edit變成 LOCAL 的檔案沒有可編輯憑證,batch 簽入會以EDIT_PROVENANCE_REQUIRED拒絕;它要用isvn checkin提交,或先isvn revert再以「設為可編輯」重新開始。 - 這組指令沒有預覽,也不會出現在 GUI 的操作中心。
- Terminux 的 DQE checkin 用
isvn status --json列出版本中 LINKED 的檔案,對要覆寫的檔案執行isvn edit,寫入之後對每個檔案執行isvn checkin。同一份工作再簽入一次也會成功,內容沒有改變的檔案會回報沒有變更。
20. CLI:PM 維護
20.1 pool 的健康狀態
isvn pool-stat [--evict-events] [--evict-threshold N] [--json]
objects=13
refs=29
physical_bytes=4615
logical_ref_bytes=10203
dedupe_ratio=2.21083
pool_used_ratio=0.602842
atime_usable=true
renewed_objects=0
renewed_bytes=0
refcount_distribution=1:5,2:4,3:2,5:2
evict_events=0
latest_evict_event=
dedupe_ratio是去重率;pool_used_ratio是 pool 所在檔案系統的使用率。- 加上
--evict-events會多兩行,顯示「強制回收」事件的數量與最近一次的時間。強制回收是指空間不足時,被迫刪除仍在使用的物件。- 幾乎沒有:健康。
- 偶爾出現:留意即可。
- 短期內持續出現:工作中的資料量已經超過 pool 容量,應該協調 IT 擴充儲存空間。
- pool 的容量由掛載的儲存空間決定,isvn 沒有「設定容量」的功能。
20.2 垃圾回收
isvn gc --reconcile --dry-run # 預覽:列出將被清除的失效連結紀錄,不刪除任何東西
isvn gc --reconcile # 清除失效的連結紀錄,校正引用數;不回收空間
isvn gc --reclaim --high 0.9 --low 0.7 # 使用率超過 high 時回收,直到低於 low
isvn gc # 先對帳,再視使用率回收
- 只有 PM(
.isvn的擁有者)可以執行。 --dry-run只能搭配--reconcile。對--reclaim或完整 GC 使用--dry-run會被拒絕(exit code 2),不會執行任何回收。- 回收會先刪除沒有任何引用的物件;仍然不夠時,才會強制回收最久沒有使用的物件。被強制回收的內容之後可以從 SVN 取回(見第 2.3 節)。
- 輸出兩行計數,例如
refs_removed=0 objects_reclaimed=0 objects_force_evicted=0 bytes_freed=0與low_watermark_reached=true;加--json得到同樣的欄位。
20.3 保留重要的內容
isvn renew <檔案>...
把檔案對應的 pool 物件標記為「最近使用過」,降低它被強制回收的機會。任何成員都可以使用。大量使用代表工作中的資料量很大,本身就是需要擴容的訊號。
20.4 血緣與專案狀態
isvn lineage verify # 完整性檢查;正常時印出 Lineage integrity ok
isvn lineage audit # 所有血緣變更紀錄
isvn admin status --json # 三個路徑的空間、權限、規模與血緣完整性摘要
lineage verify 回報不完整時,代表有人繞過 isvn 直接改動了血緣資料;請用 lineage audit 查看是誰、何時。
21. 指令總表
| 指令 | 用途 |
|---|---|
isvn version [--json] |
build 資訊 |
isvn admin init --project-dir <目錄> --repo <URL> --pool <目錄> --group <名稱> |
PM 初始化專案(見安裝指南) |
isvn admin status --json |
專案狀態摘要 |
isvn member init --project-dir <目錄> --workspace <目錄> |
成員建立工作區(見安裝指南) |
isvn create <版本> [--parent <版本|ROOT>] [--json] |
建立版本並登記上游 |
isvn checkout <版本> [--json] |
取得版本 |
isvn update |
更新目前版本 |
isvn checkout-ancestor [<版本>] [--depth N] [--yes] [--json] |
取得上游內容到 ancestor-N/ |
isvn delete <版本> [--json] |
刪除版本(有下游時拒絕) |
isvn workspaces [--json]、isvn branches [--json] |
本機的版本、版本庫中的版本 |
isvn status [<版本>] [--json]、isvn work-status <版本> --json |
檔案狀態 |
isvn log [<版本>] [--json] |
提交歷史 |
isvn ancestry [<版本>] [--json] |
血緣鏈 |
isvn lineage verify [--json]、isvn lineage audit [<版本>] [--json] |
血緣完整性、變更紀錄 |
isvn reconcile [<版本>] [--json] |
上游與完整性回報 |
isvn provenance query …、isvn file query …、isvn file locate … |
提供給外部工具的 JSON 查詢 |
isvn work-local-op …、isvn checkin-batch …、isvn remove-batch … |
檔案操作(第 19.1 節) |
isvn work-recovery status|restore|verify |
未完成操作的查看與處理 |
isvn import preview|apply --request-stdin |
匯入(GUI 使用) |
isvn edit、isvn checkin、isvn revert、isvn remove |
單一路徑的檔案操作(第 19.2 節) |
isvn renew <檔案>...、isvn renew-status [<版本>] |
保留 pool 內容、查看狀態 |
isvn pool-stat [--evict-events] [--evict-threshold N] [--json] |
pool 健康狀態 |
isvn gc [--reconcile [--dry-run] | --reclaim [--high H] [--low L]] [--json] |
垃圾回收(PM) |
舊的 isvn init 已經停用,會提示改用 admin init 或 member init。
22. 常見工作流程速查
| 想做的事 | GUI | CLI |
|---|---|---|
| 看有哪些版本 | 探索 → 選擇版本 | isvn branches |
| 查某版本從哪裡來 | 探索 → 血緣與證據探索 → 版本血緣 | isvn ancestry <版本> |
| 取得一個版本 | 探索 → Checkout… | isvn checkout <版本> |
| 把已取得的版本設為工作目標 | 探索 → 設為啟用並開啟工作 | 沒有對應指令(這是 GUI 的狀態) |
| 修改受管檔案 | 勾選 → 設為可編輯 → 修改 | work-local-op … make-editable |
| 提交修改 | 勾選 → 檢視簽入 → 確認 | checkin-batch preview → apply |
| 放棄修改 | 勾選 → 還原 | work-local-op … revert |
| 加入外部檔案 | 拖放 → 匯入預覽 → 簽入 | 複製到版本目錄後 checkin-batch |
| 移除受管檔案 | 勾選 → 移除 | remove-batch preview → apply |
| 刪除還沒提交的新檔 | 勾選 → 捨棄本機 | work-local-op … discard-local |
| 以目前版本為上游開新版本 | 建立衍生版本(名稱固定是「使用中版本的 ID」加上 .d) |
isvn create <新版本> --parent <版本> |
| 看操作進度與結果 | 下方的操作中心 | isvn work-recovery status --json |
| (PM)看 pool 健康 | 維運 | isvn pool-stat --evict-events |
| (PM)回收空間 | 維運 → GC 預覽 → 確認 | isvn gc |
23. 使用上的原則
下列規則在各自的章節中有完整說明:
- 檔案血緣只看你的工作區:
isvn file query與「探索」頁的檔案血緣,只看已經 checkout 到你的工作區的版本(第 14 節)。 - 血緣是登記的,不是推算的: 血緣由使用者登記;isvn 不推斷血緣,也不核對檔案內容(第 2.5 節、第 14 節)。
isvn reconcile只回報: 它不和 SVN 的複製來源比對,也不修改血緣(第 18.1 節)。- 衍生版本的名稱: GUI 的「建立衍生版本」建立的版本名稱是使用中版本的 ID 加上
.d;要用其他名稱請用isvn create(第 11.3 節)。 - 匯入的規則: 來源中有 symlink 或特殊檔案時整個匯入被拒絕;受管的檔案不能被覆寫;空資料夾不會匯入(第 8.3 節)。
24. 不要這樣做
- 不要直接覆寫 LINKED 檔案;先「設為可編輯」。
- 不要把「匯入」當成已經簽入。
- 不要在「結果未知」時直接重試。
- 不要手動刪除或修改
.isvn_local/裡的內容。 - 不要同時用新介面與舊版介面操作同一個專案。
- 不要用 CLI 繞過 GUI 顯示的「不可執行」;CLI 會做同樣的檢查。
- 不要把「宣告來源」(Declared provenance)當成內容已經驗證。
- 不要用原生的
svn指令直接改動 isvn 管理的 branch 或工作副本。 - 不要在真正的設計版本上練習復原或失敗情境;請用獨立的測試版本。
25. 回報問題時請提供
- 專案名稱與你的角色。
isvn version的輸出,以及使用的是新介面還是舊版介面。- 目標版本的四段 ID。
- 操作的類型與操作 ID(操作中心或 JSON 輸出中的
operation_id)。 - 畫面或輸出中的原因代碼。
- 修訂編號(如果有)。
- 是否曾經強制離開,或遇到主機、連線中斷。
請不要貼出外部來源的絕對路徑、.isvn_local/work_operations/ 的原始內容或任何機密資料。
附錄 A · 介面文字對照
| 繁體中文 | English |
|---|---|
| 首頁、工作、探索、維運 | Home, Work, Explore, Maintenance |
| 目前工作版本、本機 checkout、操作健康狀態、近期活動、繼續工作 | Active Working Version, Local checkouts, Operation health, Recent activity, Continue Work |
| 後端就緒、儲存正常、就緒 | Backend Ready, Storage OK, Ready |
| 重新整理 | Refresh |
| 使用中的工作版本/尚無使用中版本 | ACTIVE WORKING VERSION/No active version |
| 本機工作版本 | Local Working Versions |
| 檔案狀態(路徑、狀態、來源、大小) | File Status (Path, State, Source, Size) |
| 選取所有變更 | Select all changed |
| 乾淨、已修改、可編輯、新增、衝突、遺失、已移除 | Clean, Modified, Editable, New, Conflict, Missing, Removed |
| 工作流程/已選路徑 | Workflow/Selected paths |
| 設為可編輯、還原、捨棄本機、移除 | Make Editable, Revert, Discard Local, Remove |
| 加入簽入批次、簽入批次、簽入訊息、檢視簽入 | Add to Checkin Batch, Checkin Batch, Checkin Message, Review Checkin |
| 簽入批次檢視、繼續、確認簽入、簽入 | Checkin Batch Review, Continue, Confirm Checkin, Checkin |
| 簽入完成、已精確簽入一次、版本庫修訂、簽入已封鎖 | Checkin complete, Committed exactly once, Repository revision, Checkin is blocked |
| 從版本移除、移除訊息(必填) | Remove from Version, Removal Message (required) |
| 套用、取消、完成 | Apply, Cancel, Done |
| 建立衍生版本、在探索檢視 | Create Derived Version, Inspect in Explore |
| 匯入預覽、取代 LOCAL、匯入工作並加入批次 | Import Preview, Replace Local, Import to Work & Add to Batch |
| 檢視中的版本、選擇版本、重新整理證據、設為啟用並開啟工作 | Inspected Version, Choose version, Refresh evidence, Set Active and Open Work |
| 血緣與證據探索、版本血緣、檔案血緣 | Lineage & Evidence Explorer, Version Lineage, File Lineage |
| 查詢面板、血緣圖、節點檢視器 | Query Panel, Lineage Graph Canvas, Node Inspector |
| 執行版本血緣查詢、執行檔案血緣查詢、使用目前版本 | Run Lineage Query, Run File Query, Use current |
| 宣告來源、宣告清單、未驗證內容 | Declared provenance, Declared inventory, Not content-verified |
| 版本關係、SVN Commit 歷史、版本來源紀錄、檢視器、來源核對 | Version Relationships, SVN Commit History, Provenance Log, Inspector, Source Check |
| 操作中心、活動紀錄 | Operation Center, Activity Log |
| 在背景執行、返回操作、強制離開 | Run in Background, Return to Operations, Force Exit |
| 提交結果未知 — 需要驗證、驗證版本庫歷史 | Commit outcome unknown — verification required, Verify repository history |
| 需要復原、需人工檢視 | Recovery Required, Manual Review Required |
| 維護控制中心、維運診斷、驗證完整性 | Maintenance Control Center, Maintenance diagnostics, Verify integrity |
| 完整性檢查、GC 預覽、快取池、保留活動、容量健康、管理總覽 | Integrity check, GC preview, Cache Pool, Retention Activity, Capacity Health, Admin Overview |
| 維護操作、清理預覽、快取回收、完整 GC、操作憑據 | Operations, Cleanup Preview, Cache Reclaim, Full GC, Operation Evidence |
| 拒絕存取 | Access Denied |