跳至主要内容

使用指南

適用對象:使用 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 設計流程提供三件事:

  1. 版本管理: 每個版本對應一個 SVN branch,你在版本上 checkout、修改、簽入檔案。
  2. 血緣(Lineage): 建立版本時,由你登記它是從哪個版本衍生的。血緣是使用者的決定,不是系統推算的,每一筆都記錄了誰、何時登記。
  3. 去重快取(pool): 內容相同的工作檔案在專案的快取池中只存一份,工作副本裡以連結指向它。

isvn 有命令列工具 isvn 與圖形介面 isvn-gui。日常的修改與簽入建議用 GUI;CLI 適合查詢、建立與取得版本,以及寫成腳本。

圖 U-01:isvn 做的三件事,以及各自的資料放在哪裡。

圖 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,以及它出現的三個地方。

圖 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)與狀態如何隨動作改變。

圖 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:四種「版本」是同一份清單上的四個標記(示範專案)。

圖 U-04 四種「版本」是同一份清單上的四個標記(示範專案)。

2.5 血緣

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

圖 U-05:示範專案六個版本的血緣。

圖 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
  • 使用專案安裝包時,先 source PM 提供的環境檔,isvn-gui 就在 PATH 上。
  • 使用 Portable 評估版時,執行 ~/.local/opt/isvn/current/isvn-gui。
  • GUI 以啟動時所在的目錄決定專案與工作區。一個 GUI 視窗只處理一個專案,沒有切換專案的功能;要操作另一個專案,請到那個專案的工作區另外啟動。
  • 啟動後直接進入「工作」頁。

圖 U-06:第一次開啟 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:上方列:① 專案 ② 頁面分頁 ③ 角色 ④ 語言 ⑤ 主題 ⑥ 後端狀態。

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

圖 U-32:操作中心。

圖 U-32 操作中心。


5. 首頁

首頁是唯讀的摘要:「目前工作版本」、「本機 checkout」的數量、「操作健康狀態」、「近期活動」,以及「繼續工作」(Continue Work)按鈕。

  • 「繼續工作」只會切到「工作」頁,不會改變使用中的版本。
  • 「操作健康狀態」一格顯示「請檢視操作中心」:操作的詳細狀態要到下方的操作中心看。
  • 「近期活動」是活動紀錄中列出的操作數量(第 17 節)。
  • 首頁不會執行任何變更。

圖 U-09:首頁:使用中的版本、本機 checkout 數量與「繼續工作」。

圖 U-09 首頁:使用中的版本、本機 checkout 數量與「繼續工作」。


6. 工作頁

「工作」頁是日常操作的中心,分成三個區域(圖 U-10 的編號):① 本機工作版本、② 檔案狀態、③ 工作流程。

頁首顯示「使用中的工作版本」。還沒有選定時顯示「尚無使用中版本」,檔案清單是空的。

圖 U-10:「工作」頁的三個區域:① 本機工作版本 ② 檔案狀態 ③ 工作流程。

圖 U-10 「工作」頁的三個區域:① 本機工作版本 ② 檔案狀態 ③ 工作流程。

6.1 本機工作版本(Local Working Versions)

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

圖 U-31:工作區中有兩個版本時的「本機工作版本」清單;反白的是使用中的版本。

圖 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」。

圖 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. 在「檔案狀態」勾選檔案。「工作流程」會顯示「已選路徑 · 1」。
  2. 按「設為可編輯」。
  3. 確認畫面顯示:「將受管檔案轉為可編輯的本機副本,不會建立版本庫修訂。」這個畫面不會列出檔名,按下之前請先確認勾選的項目。
  4. 按「套用」(Apply)。結果畫面顯示「已完成」與「未建立版本庫修訂」,再按「完成」(Done)。
  5. 檔案的狀態變成「可編輯」、來源變成 LOCAL。現在可以用編輯器或 EDA 工具修改它。

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

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

圖 U-13:設為可編輯之後:top.v 的狀態是「可編輯」,來源是 LOCAL。

圖 U-13 設為可編輯之後:top.v 的狀態是「可編輯」,來源是 LOCAL。

  • pool 中的共用內容不會被修改,其他連結到相同內容的工作副本不受影響。
  • 系統會為這個檔案保存一份「可編輯憑證」,之後簽入時用來確認它是合法的受管副本。用其他方式(包括 isvn edit)變成 LOCAL 的檔案沒有憑證,批次簽入時會被擋下;用 isvn edit 開啟的檔案請用 isvn checkin 提交(第 19.2 節),或先還原,再重新設為可編輯。

7.2 還原

要放棄受管檔案的本機修改:

  1. 勾選檔案,按「還原」。
  2. 確認畫面會警告「這會捨棄本機變更」:「還原受管狀態並捨棄本機修改,不會建立版本庫修訂。」
  3. 想保留修改就按「取消」;確定要放棄才按「套用」,再按「完成」。

檔案回到「乾淨」與 LINKED。

圖 U-14:「還原」的確認畫面:會捨棄本機變更(中間的空白已省略)。

圖 U-14 「還原」的確認畫面:會捨棄本機變更(中間的空白已省略)。

7.3 捨棄本機

「捨棄本機」只用於從未提交過的新檔(狀態為「新增」):

  • 它只刪除本機的檔案,不會建立版本庫修訂。
  • 受管的檔案不能用它刪除;要從版本庫移除請用「移除」(第 10 節)。
  • 這是無法復原的本機刪除,確認前請看清楚項目。

8. 匯入外部檔案

把工作區以外的檔案或資料夾複製到使用中的版本。匯入只是本機複製,不會寫入版本庫;之後仍要簽入。

8.1 拖放的目的地

  • 拖到資料夾的那一列:目的地是那個資料夾。
  • 拖到「檔案狀態」的空白處:目的地是使用中版本的根目錄。
  • 檔案的那一列不能當作目的地。
  • 拖入資料夾時,會保留最上層的資料夾名稱。例如把外部的 rtl/ 拖到 src 資料夾,結果是 src/rtl/...。

8.2 流程

  1. 拖入檔案或資料夾。放開時只會開始預覽,還沒有複製任何東西。
  2. 「匯入預覽」列出每個來源對應的目的路徑、大小,以及目的地是否已經有檔案。
  3. 目的地有同名、而且是從未提交過的新檔時,可以逐項勾選「取代 LOCAL」(Replace Local),預設不勾選。
  4. 按「匯入工作並加入批次」(Import to Work & Add to Batch),確認後開始複製。
  5. 完成後,匯入的路徑會加入這個版本的簽入批次。輸入簽入訊息並完成簽入(第 9 節),檔案才會進版本庫。

8.3 安全規則

  • 來源中有 symlink(包括資料夾內層的)或特殊檔案:整個匯入被拒絕。
  • 空資料夾:不會匯入。
  • 目的地是受管的檔案(LINKED、設為可編輯的 LOCAL,或版本庫中有但本機遺失的項目):一律不允許覆寫。要修改受管檔案請用「設為可編輯」。
  • 預覽之後來源或目的地有變動:執行時會被擋下,需要重新預覽。
  • 匯入要嘛全部完成,要嘛全部不做,不會留下一半。
  • 目標空間不足時會被擋下。
  • 規模上限:單次最多 50,000 個檔案、總量 1 TiB、單一檔案 256 GiB。
  • 外部來源的絕對路徑不會寫進活動紀錄、通知或錯誤訊息。

9. 批次簽入

簽入批次屬於單一版本,而且只存在於這次的 GUI 執行期間。

9.1 流程

  1. 在「檔案狀態」勾選要提交的檔案或資料夾。勾選的項目會出現在右邊的「簽入批次」中。
  2. 在「簽入訊息」欄位輸入訊息(必填),按「檢視簽入」。
  3. 「簽入批次檢視」(Checkin Batch Review)列出選取範圍與這次批次確切的內容:後端已經展開資料夾、去除重複,並略過沒有變更的項目。每個項目旁邊是它的狀態,例如「就緒」。確認後按「繼續」(Continue)。
  4. 「確認簽入」(Confirm Checkin)再次顯示同一份清單與訊息。按「簽入」(Checkin)執行。
  5. 結果畫面顯示「簽入完成」(Checkin complete)、「已精確簽入一次」(Committed exactly once)與修訂編號,例如「版本庫修訂 r14」。按「關閉」回到「工作」頁。

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

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

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

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

圖 U-17:批次簽入的結果:「簽入完成」與修訂編號(空白處已省略)。

圖 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 移除:

  1. 勾選受管的項目,按「工作流程」中紅色框內的「移除」。
  2. 出現「從版本移除」(Remove from Version)的確認畫面:「一次移除只會建立一個版本庫修訂。移除不會進入簽入批次。」這個畫面不會列出檔名,按下之前請先確認勾選的項目。
  3. 輸入「移除訊息(必填)」。項目有本機修改時,需要另外確認放棄這些修改。
  4. 按右下角的「移除」執行。結果畫面顯示「已完成」與修訂編號,例如「版本庫修訂 r15」;再按「完成」。

圖 U-18:「從版本移除」的確認畫面:訊息必填(中間的空白已省略)。

圖 U-18 「從版本移除」的確認畫面:訊息必填(中間的空白已省略)。

「移除」和「捨棄本機」的差別:

移除 捨棄本機
對象 受管的項目 從未提交過的新檔
版本庫 建立一個修訂 不變

畫面顯示 USE_DISCARD_LOCAL 這類原因時,代表你選的項目應該用另一個動作處理。

「移除」移除的是版本中的檔案;刪除整個版本是 CLI 的 isvn delete(第 18.3 節)。


11. 取得版本:Checkout、設為啟用、建立衍生版本

11.1 Checkout 版本庫中的版本

在「探索」頁操作:

  1. 按「選擇版本」(Choose version),在清單中點選要的版本。
  2. 「檢視中的版本」欄位顯示這個版本,下方提示:「這個版本不在此工作區中。Checkout 只會建立它的本機 working copy,不會改變啟用中的版本。」
  3. 按右上角的「Checkout…」。對話框列出版本與將要建立的本機資料夾。
  4. 按對話框中的「Checkout」。按「取消」則什麼都不會改變。
  5. 完成後提示版本已 checkout,並再次說明啟用中的版本沒有改變。

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

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

圖 U-20:Checkout 的確認對話框:列出版本與將要建立的本機資料夾。

圖 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 完成後的提示,以及右上角的「設為啟用並開啟工作」。

圖 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:「建立衍生版本」的確認對話框。

圖 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:「探索」頁:① 檢視中的版本 ② 選擇版本 ③ 血緣與證據探索 ④ 提交歷史、來源紀錄與版本關係。

圖 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-24 版本血緣(Ancestor Chain)的查詢結果:血緣圖與節點檢視器。

圖 U-25:檔案血緣(Versions)的查詢結果:top.v 出現在本機已 checkout 的兩個版本。

圖 U-25 檔案血緣(Versions)的查詢結果:top.v 出現在本機已 checkout 的兩個版本。


15. 維運頁與角色

15.1 PM

PM 看到完整的「維護控制中心」(Maintenance Control Center)。上方有「重新整理」「完整性檢查」「GC 預覽」三個按鈕;下面依序是「維護總覽」「快取池」「保留活動」「容量健康」「完整性檢查」「管理總覽」,右邊是「維護操作」:「清理預覽」,以及標示為危險區域的「快取回收」與「完整 GC」。

  • 進入頁面時各區塊顯示「尚未載入」;按「重新整理」讀取資料,按「完整性檢查」檢查血緣紀錄。

  • PM GUI 中會變更資料的維運動作都要先預覽,再明確確認。

  • 有需要復原的操作時,動作可能被停用;先在操作中心處理那個操作(第 16 節)。

圖 U-26:PM 的「維運」頁:維護控制中心。

圖 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:活動紀錄:你在這個專案執行過的操作,最新的在最上面。

圖 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 的實際輸出。

圖 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 共用的順序。

圖 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 指令修改並簽入一個受管檔案的實際輸出。

圖 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 <路徑> 提交的範圍:指定檔案時只有那個檔案;指定資料夾時包含其中的修改與新檔案。

圖 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 提交單一檔案、新的資料夾、資料夾中的新檔案,以及沒有變更時的實際輸出。

圖 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. 使用上的原則

下列規則在各自的章節中有完整說明:

  1. 檔案血緣只看你的工作區: isvn file query 與「探索」頁的檔案血緣,只看已經 checkout 到你的工作區的版本(第 14 節)。
  2. 血緣是登記的,不是推算的: 血緣由使用者登記;isvn 不推斷血緣,也不核對檔案內容(第 2.5 節、第 14 節)。
  3. isvn reconcile 只回報: 它不和 SVN 的複製來源比對,也不修改血緣(第 18.1 節)。
  4. 衍生版本的名稱: GUI 的「建立衍生版本」建立的版本名稱是使用中版本的 ID 加上 .d;要用其他名稱請用 isvn create(第 11.3 節)。
  5. 匯入的規則: 來源中有 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