使用手冊
適用對象:每天用 isvn 工作的設計團隊成員。 這份手冊以「我要完成什麼」為單位,一步一步說明 GUI 的操作。每個畫面、每個指令的完整說明,請看參考用的《isvn 使用手冊》;安裝請看《isvn 安裝與部署指南》。
0. 開始之前
你需要:
- 已經安裝好的 isvn(專案安裝包,或 Portable 評估版);
- 一個以
isvn member init建立好的工作區(WORKSPACE_ROOT); - 專案的版本庫中至少有一個版本。
幾個一定會看到的詞:
| 詞 | 意思 |
|---|---|
| 版本 | 四段的 ID,例如 trial/cpu/200_fe_datain/v2。每個版本是一個 SVN branch |
| 工作區 | 你的工作目錄。每個取得的版本各自放在 WORKSPACE_ROOT/<phase>/<block>/<stage>/<version>/ |
| 使用中的版本 | 「工作」頁正在操作的那一個版本 |
| LINKED | 檔案是指向共用唯讀內容的連結;要修改前必須先「設為可編輯」 |
| LOCAL | 檔案是你工作副本中的實體檔:設為可編輯後的副本,或還沒簽入的新檔 |
| 簽入 | 把修改提交到版本庫,產生一個新的修訂 |
本手冊的畫面取自 TUT01 Demo Kit 的示範專案(帳號 learner),介面語言是繁體中文;英文介面的畫面放在英文版中。

圖 M-01 一天的工作:最常用的路線,以及每一步對應的任務。

圖 M-02 依想做的事選擇動作。
任務 1:開啟 GUI
-
開啟終端機,進入你的工作區:
cd <WORKSPACE_ROOT> -
啟動 GUI:
isvn-gui # 專案安裝包(先 source PM 提供的環境檔) ~/.local/opt/isvn/current/isvn-gui # Portable 評估版 -
視窗開啟後是「工作」頁。工作區中還沒有任何版本時,畫面如圖 U-06。

圖 U-06 第一次開啟 GUI:「工作」頁,工作區中還沒有任何版本。
- GUI 以啟動時所在的目錄決定專案;一個視窗只處理一個專案。
- GUI 啟動時是繁體中文、深色主題。右上角的語言按鈕依序切換 繁體中文 → 简体中文 → English;旁邊的按鈕切換深色與淺色主題。
- 再啟動一次不會開第二個視窗,原本的視窗會回到前面。
任務 2:取得一個版本,並開始在上面工作
要在某個版本上工作,先把它 checkout 到工作區,再把它設為使用中的版本。

圖 M-03 取得一個版本並設為使用中。
- 按上方的「探索」,再按「選擇版本」。
- 在清單中點選要的版本。上方的「檢視中的版本」會顯示它,下方提示「這個版本不在此工作區中」。
- 按右上角的「Checkout…」。對話框列出版本與將要建立的本機資料夾;按「Checkout」。
- 完成時會提示已經 checkout,並說明使用中的版本沒有改變。
- 按「設為啟用並開啟工作」。畫面切到「工作」頁,頁首顯示這個版本。
也可以在終端機取得版本;之後回到 GUI 按「重新整理」,再到「工作」頁左邊的「本機工作版本」點選它:
cd <WORKSPACE_ROOT>
isvn checkout trial/cpu/200_fe_datain/v2
要知道的事:
- 一次只 checkout 一個版本,不會帶出上游版本的檔案。
- 取得後,所有檔案都是 LINKED。
- 版本已經在工作區時,選擇它會提示「這個版本已在此工作區中」,直接按「設為啟用並開啟工作」即可。
任務 3:看懂「工作」頁

圖 U-10 「工作」頁的三個區域:① 本機工作版本 ② 檔案狀態 ③ 工作流程。
| 區域 | 內容 |
|---|---|
| ① 本機工作版本 | 已經 checkout 到這個工作區的版本。點選其中一個,它就成為使用中的版本 |
| ② 檔案狀態 | 使用中版本的檔案:路徑、狀態、來源(LINKED/LOCAL)、大小。每一列前面的方框用來勾選 |
| ③ 工作流程 | 對勾選的項目執行的動作,以及「簽入批次」與「簽入訊息」 |
- 所有動作只處理你勾選的項目。
- 檔案狀態上方的篩選(All、Changed、Editable、LOCAL、Conflict)只改變顯示,不改變勾選。
- 在 GUI 以外改了檔案(編輯器、EDA 工具、
cp)之後,按右上角的「重新整理」更新畫面。 - 按鈕是灰色時,代表目前的選取不能做這個動作。
任務 4:修改一個已經在版本中的檔案
LINKED 檔案指向共用的唯讀內容,不能直接覆寫。先把它設為可編輯:
- 在「檔案狀態」勾選檔案。
- 按「設為可編輯」。確認畫面顯示「將受管檔案轉為可編輯的本機副本,不會建立版本庫修訂。」——這個畫面不列出檔名,按之前請先確認勾選的項目。
- 按「套用」,再按「完成」。
- 檔案的狀態變成「可編輯」,來源變成 LOCAL。

圖 U-13 設為可編輯之後:top.v 的狀態是「可編輯」,來源是 LOCAL。
- 用你平常的編輯器或 EDA 工具修改這個檔案(它就在版本資料夾中)。
- 回到 GUI 按「重新整理」。檔案的狀態變成「已修改」。
- 簽入它(任務 6)。

圖 M-04 修改一個受管的檔案並簽入。
- 共用的內容不會被修改;其他人或其他版本連到相同內容的檔案不受影響。
- 一次可以勾選多個檔案一起設為可編輯。資料夾不能設為可編輯。
- 不要用其他方式(例如複製一份蓋過去,或用
isvn edit)把檔案變成 LOCAL;那樣的檔案在簽入(任務 6)時會被擋下。
任務 5:把新檔案加進版本

圖 M-05 把新檔案加進版本的兩種方式。
方式 A:直接放進版本資料夾。 用檔案管理員、EDA 工具或 cp 把檔案存進版本資料夾,回到 GUI 按「重新整理」。檔案出現為「新增」、LOCAL。
方式 B:拖放匯入。 從工作區以外把檔案或資料夾拖進「檔案狀態」:
- 拖到資料夾的那一列,目的地就是那個資料夾;拖到空白處,目的地是版本的根目錄。
- 放開時只會開始預覽。「匯入預覽」列出每個檔案的目的路徑與大小。
- 按「匯入工作並加入批次」,確認後開始複製。匯入的檔案會自動加入簽入批次。
兩種方式都只是本機複製,還沒有進版本庫;接著要簽入(任務 6)。新檔案不需要先設為可編輯。
匯入的規則:來源中有 symlink 或特殊檔案時,整個匯入會被拒絕;不能覆寫受管的檔案;空資料夾不會匯入。
任務 6:簽入
- 在「檔案狀態」勾選要提交的檔案(已修改或新增的)。它們會出現在右邊的「簽入批次」中,旁邊顯示「就緒」。
- 在「簽入訊息」輸入說明(必填)。
- 按「檢視簽入」。「簽入批次檢視」列出這次確切會提交的內容;後端已經略過沒有變更的項目。
- 確認清單,按「繼續」。
- 「確認簽入」再顯示一次清單與訊息。按「簽入」。
- 結果畫面顯示「簽入完成」、「已精確簽入一次」與修訂編號(例如「版本庫修訂 r14」)。按「關閉」。

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

圖 U-17 批次簽入的結果:「簽入完成」與修訂編號(空白處已省略)。
簽入之後:
- 提交的檔案回到 LINKED、「乾淨」。
- 一次簽入只產生一個修訂;沒有「部分成功」。
- 只提交你勾選的項目,其他修改留在原地。
- 預覽之後檔案有變動時,執行會被擋下,請重新按「檢視簽入」。
- 項目不能提交時,「簽入批次檢視」顯示「簽入已封鎖」與原因,「繼續」不能按。
任務 7:放棄還沒簽入的修改
還原(已設為可編輯或已修改的受管檔案):
- 勾選檔案,按「還原」。
- 確認畫面警告「這會捨棄本機變更」。想保留修改就按「取消」;確定要放棄才按「套用」,再按「完成」。
- 檔案回到「乾淨」與 LINKED。

圖 M-07 還原:放棄一個檔案的本機修改。
捨棄本機(從未簽入過的新檔案):勾選「新增」的檔案,按「捨棄本機」並確認。這會刪除本機的檔案,無法復原。
兩個動作都不會建立版本庫修訂。
任務 8:把檔案從版本中移除
- 勾選要移除的受管檔案或資料夾,按「工作流程」中紅色框內的「移除」。
- 「從版本移除」的確認畫面不會列出檔名,按之前請先確認勾選的項目。
- 輸入「移除訊息(必填)」。項目有本機修改時,需要另外確認放棄這些修改。
- 按右下角的「移除」。結果顯示「已完成」與修訂編號;按「完成」。

圖 M-06 從版本移除一個檔案。
- 一次移除建立一個修訂。移除不會進入簽入批次。
- 還沒簽入過的新檔案不能用「移除」,請用「捨棄本機」。
- 「移除」移除的是版本中的檔案,不是整個版本。
任務 9:以目前的版本為上游,開一個新版本
在 GUI 中:
- 確認使用中的版本就是要當作上游的那一個。
- 按「建立衍生版本」。
- 確認對話框有兩個按鈕:「取消」與「建立 → 檢出 → 設為使用中」(圖 U-22)。
- 按「建立 → 檢出 → 設為使用中」。完成後,新版本就是使用中的版本。

圖 U-22 「建立衍生版本」的確認對話框。
- 新版本的名稱固定是「使用中版本的 ID」加上
.d,例如trial/cpu/200_fe_datain/v2.d;GUI 中不能改名。同名的版本已經存在時,建立會失敗,什麼都不會改變。 - 新版本一開始就包含上游的所有檔案。
要自訂名稱時,用 CLI:
cd <WORKSPACE_ROOT>
isvn create trial/cpu/200_fe_datain/v3 --parent trial/cpu/200_fe_datain/v2
完成時印出 created <新版本> from <上游版本>,新版本也會 checkout 到工作區。回到 GUI 按「重新整理」,在本機工作版本清單中點選它。
任務 10:查一個版本或檔案從哪裡來
版本的上游:
- 在「探索」頁按「選擇版本」,點選版本。
- 在「血緣與證據探索」左邊的「查詢面板」:模式選「版本血緣」,查詢類型選「Ancestor Chain」。
- 按「執行版本血緣查詢」。血緣圖由最早的版本畫到這個版本;點選節點,右邊的「節點檢視器」顯示它的詳細資訊。

圖 U-24 版本血緣(Ancestor Chain)的查詢結果:血緣圖與節點檢視器。
一個檔案出現在哪些版本:
- 把查詢面板的模式改成「檔案血緣」。
- 在「檔案路徑」輸入相對於版本根目錄的路徑,例如
top.v;查詢類型選「Versions」。 - 按「執行檔案血緣查詢」。

圖 U-25 檔案血緣(Versions)的查詢結果:top.v 出現在本機已 checkout 的兩個版本。
閱讀結果時:
- 血緣是建立版本時由使用者登記的上游,不是從檔案內容推算的。畫面上的「宣告來源」與「未驗證內容」就是在提醒這一點。
- 檔案血緣只看得到已經 checkout 到你工作區的版本。要看得更完整,先 checkout 其他版本。
在終端機也可以查(圖 U-27):
isvn ancestry trial/cpu/400_layout_datain/v1

圖 U-27 isvn workspaces、isvn status、isvn ancestry 與 isvn log 的實際輸出。
任務 11:確認操作的結果
- 下方狀態列顯示上一個動作與結果,例如「上次動作: work-read-workStatus · success」。
- 按狀態列的「操作中心」:列出執行中與已完成的操作;點選「開啟」查看。
- 按「活動紀錄」:這個使用者、這個專案的近期操作摘要。

圖 U-32 操作中心。
結果是「結果未知」或「需要復原」時:
- 不要直接重做同樣的簽入或移除,以免重複提交。
- 在操作中心開啟那個操作,只執行畫面提供的驗證或復原,例如「驗證版本庫歷史」。
- 不要手動修改工作區中的
.isvn_local/。
任務 12:在幾個版本之間切換
- 在「工作」頁左邊的「本機工作版本」點選另一個版本,它就成為使用中的版本。
- 每個版本各自保留勾選、簽入訊息與尚未送出的內容,切換時不會混在一起。
- 一個版本的操作還在執行時,可以切換到另一個版本繼續工作;原來的版本顯示「操作進行中」。

圖 U-31 工作區中有兩個版本時的「本機工作版本」清單;反白的是使用中的版本。
任務 13:關閉 GUI
- 沒有操作在執行時,直接關閉視窗。
- 有操作在執行時,會出現三個選項:「在背景執行」(隱藏視窗,操作繼續)、「返回操作」(不關閉)、「強制離開」(停止執行中的程序,不保證能復原)。一般請選「在背景執行」或「返回操作」。
- 選了「在背景執行」之後,再啟動一次 GUI 會回到原本的視窗。
任務 14:用指令完成同樣的工作
需要寫成腳本時,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"])'; }
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
echo "# tighter clock" >> $V/constraints.sdc
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

圖 U-34 以 batch 指令修改並簽入一個受管檔案的實際輸出。
| GUI | 指令 |
|---|---|
| 設為可編輯/還原/捨棄本機 | isvn work-local-op preview|apply --action make-editable|revert|discard-local --in <版本> --path <路徑> |
| 簽入 | isvn checkin-batch preview|apply <版本> --path <路徑> [--expected-plan <雜湊>] [--message <訊息>] |
| 移除 | isvn remove-batch preview|apply --from <版本> --path <路徑> [--expected-plan <雜湊>] [--message <訊息>] |
| Checkout | isvn checkout <版本> |
| 建立衍生版本 | isvn create <新版本> --parent <上游版本> |
- 腳本要檢查輸出 JSON 中的
status,不能只看 exit code。 - 單一檔案或整個資料夾也可以用
isvn checkin <路徑>提交;資料夾中的新檔案會一起提交;內容沒有變更時,指令會說明沒有變更,不會提交任何東西。詳見參考用《isvn 使用手冊》第 19.2 節。
任務 15:遇到問題時
| 你看到的 | 原因 | 怎麼做 |
|---|---|---|
| 按鈕是灰色的 | 勾選的項目不適合這個動作 | 看圖 M-02 選擇正確的動作;不要繞過 |
| 改過檔案,但畫面沒變 | GUI 不會自動偵測 GUI 以外的修改 | 按「重新整理」 |
| 直接修改 LINKED 檔案時被拒絕寫入 | LINKED 檔案是唯讀的共用內容 | 先「設為可編輯」(任務 4) |
| 執行時被擋下,要求重新預覽 | 預覽之後檔案或版本庫有變動 | 重新按「檢視簽入」或重新執行動作 |
| 結果是「結果未知」 | 提交過程被中斷 | 在操作中心按「驗證版本庫歷史」,不要直接重試(任務 11) |
回報問題時,請提供:isvn version 的輸出、版本 ID、操作中心中的操作 ID、畫面上的原因代碼與修訂編號。
附錄:速查表
| 我想要…… | GUI 操作 |
|---|---|
| 取得一個版本 | 探索 → 選擇版本 → Checkout… → Checkout |
| 開始在它上面工作 | 探索 → 設為啟用並開啟工作;或在「工作」頁的本機工作版本點選 |
| 修改受管的檔案 | 勾選 → 設為可編輯 → 套用 → 完成 → 修改 → 重新整理 |
| 加入新檔案 | 放進版本資料夾 → 重新整理;或拖放 → 匯入預覽 → 匯入工作並加入批次 |
| 簽入 | 勾選 → 簽入訊息 → 檢視簽入 → 繼續 → 簽入 |
| 放棄修改 | 勾選 → 還原 → 套用 → 完成 |
| 刪除從未簽入的新檔案 | 勾選 → 捨棄本機 |
| 從版本移除 | 勾選 → 移除 → 移除訊息 → 移除 → 完成 |
| 開新版本 | 建立衍生版本 → 建立 → 檢出 → 設為使用中 |
| 查版本的上游 | 探索 → 版本血緣 → Ancestor Chain → 執行版本血緣查詢 |
| 查檔案在哪些版本 | 探索 → 檔案血緣 → 檔案路徑 → 執行檔案血緣查詢 |
| 看操作結果 | 狀態列 → 操作中心/活動紀錄 |