介紹
適用對象:剛加入的團隊成員、PM,以及想了解 isvn 能做什麼的人。 這份文件說明 isvn 是什麼、怎麼運作、提供哪些功能。操作步驟請看《isvn 使用手冊(任務導向)》。
1. isvn 是什麼
isvn 是建構在 Subversion(SVN)之上的設計資料管理工具,為 IC 設計流程中「每個階段都有很多個版本」的情況而設計。它有命令列工具 isvn 與圖形介面 isvn-gui,兩者使用同一組功能。

圖 P-01 isvn 為每個設計版本回答的三個問題,以及它不回答的事。
一句話:SVN 保存內容,isvn 在上面加上版本的命名與取得方式、使用者登記的血緣,以及共用的去重快取。
2. 它解決的問題
| 設計團隊常遇到的情況 | isvn 的做法 |
|---|---|
| 同一個 block 的同一個 stage 有好幾個版本,很難說清楚現在在用哪一個 | 每個版本有固定四段的 ID,例如 trial/cpu/200_fe_datain/v2;「工作」頁永遠顯示使用中的是哪一個版本 |
| 下游拿到一份輸入,說不清它是從哪一版來的 | 建立版本時登記上游;之後任何人都能查到完整的上游鏈,以及誰、何時登記 |
| 很多版本裡有大量相同的檔案,各自複製一份很佔空間 | 內容相同的檔案在 pool 中只存一份,工作副本中以連結使用 |
| 修改大量檔案、移除檔案時,怕提交了不該提交的東西 | GUI 與支援預覽的 Batch 操作先預覽、再確認;批次簽入只提交勾選的項目,一次一個修訂 |
| 外部工具需要知道一個檔案、一個版本的來歷 | 提供唯讀的 JSON 查詢指令,供 Terminux 等工具呼叫 |
3. 核心概念
3.1 版本
每個版本有一個四段的 ID:<phase>/<block>/<stage>/<version>。這個 ID 同時是 SVN branch 的名稱、工作副本的資料夾名稱,也是查詢結果中的身分。

圖 U-02 四段版本 ID,以及它出現的三個地方。
3.2 工作區與檔案
每位成員有自己的工作區。取得的每個版本各自是一份工作副本。工作副本中的檔案有兩種來源:
- LINKED:指向 pool 中唯讀內容的連結,不佔額外空間;修改前要先「設為可編輯」。
- LOCAL:工作副本中的實體檔,也就是你正在修改的副本或還沒簽入的新檔。
簽入之後,檔案回到 LINKED。

圖 U-03 檔案的來源(LINKED/LOCAL)與狀態如何隨動作改變。
3.3 血緣
建立版本時,由建立的人登記它的上游。每個版本最多一個直接上游;紀錄只增不改,刪除版本也只是加上一筆移除紀錄。

圖 U-05 示範專案六個版本的血緣。
isvn 不會從 SVN 的複製紀錄或檔案內容推算血緣,也不驗證檔案內容是否真的來自上游。血緣回答的是「使用者宣告了什麼」,因此查詢結果都標示為「宣告來源」與「未驗證內容」。
3.4 去重快取(pool)
pool 依內容儲存檔案:內容相同的檔案只存一份。工作副本中的 LINKED 檔案指向它。空間不足時,PM 的回收作業可以刪除最久沒用的內容;之後用到時,isvn 會從 SVN 取回並重新連結,內容不會遺失。

圖 P-02 去重的效果:TUT01 示範專案的 isvn pool-stat 實測值。
4. 一天的工作長什麼樣子

圖 M-01 一天的工作:最常用的路線,以及每一步對應的任務。
- 在「探索」頁選一個版本,checkout 到工作區,設為使用中的版本。
- 在「工作」頁把要改的檔案設為可編輯,用你平常的工具修改;新檔案直接放進版本資料夾。
- 勾選要提交的檔案,寫一段訊息,檢視後簽入。
- 需要開新一版時,以目前的版本為上游建立衍生版本。
GUI 與支援預覽的 Batch 操作遵循同樣的順序:

圖 U-28 預覽 → 確認 → 執行 → 結果:batch 指令與 GUI 共用的順序。
單一路徑指令(isvn edit、isvn checkin、isvn revert、isvn remove)不提供獨立預覽,會直接執行;請參閱User Guide 第 19.2 節。
5. 介面一覽
GUI 有四個頁面。
首頁:使用中的版本、本機 checkout 的數量與「繼續工作」。

圖 U-09 首頁:使用中的版本、本機 checkout 數量與「繼續工作」。
工作:日常操作的中心。左邊是本機工作版本,中間是檔案狀態,右邊是工作流程與簽入批次。

圖 U-10 「工作」頁的三個區域:① 本機工作版本 ② 檔案狀態 ③ 工作流程。
探索:查看版本庫中的版本、版本與檔案的血緣、提交歷史。在這裡選取版本不會改變「工作」頁的目標。

圖 U-23 「探索」頁:① 檢視中的版本 ② 選擇版本 ③ 血緣與證據探索 ④ 提交歷史、來源紀錄與版本關係。
維運:PM 看到完整的維護控制中心(快取池、容量、完整性檢查、GC);成員只能做唯讀的檢查。

圖 U-26 PM 的「維運」頁:維護控制中心。
6. 架構與部署
一次部署有三個可以分開放置的位置:SVN repository、pool、專案目錄(設定與血緣資料庫),加上每位成員自己的工作區。

圖 I-03 一次部署的四個位置,以及它們之間的關係。
- 安裝有兩種方式:PM 一次裝好、成員共用的專案安裝包,以及每個人裝在自己家目錄的 Portable 評估版。兩者都不需要 root。
- Production 的程式以 release slot 管理:部署與回復都是切換一個連結,CLI 與 GUI 一定成對。
- GUI 需要 Qt 6.7.3;Qt 不隨附,安裝時指定既有的 Qt。
詳見《isvn 安裝與部署指南》。
7. 角色
| 角色 | 是誰 | 能做什麼 |
|---|---|---|
| PM | 專案目錄中 .isvn 的擁有者(建立專案的帳號) |
全部功能,包含 GC 等維護操作 |
| MEMBER | 專案 Linux group 的成員 | 日常操作;維運只能做唯讀檢查 |
| DENIED | 不在專案 group 中 | GUI 只顯示「拒絕存取」,不讀取任何專案資料 |
8. 與其他工具的整合
外部工具可以用兩組唯讀指令查詢血緣,輸出都是 JSON:
isvn provenance query:某個版本的上游、祖先鏈、根版本、完整血緣;isvn file query:某個路徑出現在哪些版本(只看呼叫者工作區中已 checkout 的版本)。

圖 Q-01 兩組查詢指令各自讀取的資料,以及 isvn 回答與不回答的事。
Terminux 已經包裝了這兩組指令,並以 isvn checkin 簽入 DQE 的結果。詳見《isvn × Terminux 血緣查詢指令參考》。
9. isvn 提供的功能

圖 P-04 isvn 提供的功能,依領域分類。
| 範圍 | 可以做的事 |
|---|---|
| 版本與檔案 | 每個版本有固定四段的 ID;checkout 版本,或以目前的版本為上游建立衍生版本;把檔案設為可編輯、加入新檔、簽入與移除,GUI 與支援預覽的 Batch 操作先預覽、再確認 |
| 血緣 | 建立版本時登記上游;查詢任何版本的上游、祖先鏈、根版本與完整血緣,以及一個檔案出現在哪些已 checkout 的版本 |
| 儲存與維護 | 內容相同的檔案在 pool 中只存一份,工作副本中以連結使用;PM 有完整的維護控制中心(快取池、容量、完整性檢查、GC),成員可以做唯讀的檢查 |
| 介面與整合 | GUI(繁體中文、簡體中文、英文三種語言)與 CLI 使用同一組功能;另有唯讀的 JSON 查詢指令,供 Terminux 等工具呼叫 |
| 安裝與部署 | 專案安裝包(PM 裝一次,成員共用)、Portable 評估版(每個人裝在自己的家目錄),以及以 release slot 管理的部署與回復 |
10. 接下來讀什麼

圖 P-03 文件地圖:接下來讀哪一份。
| 你是 | 先讀 |
|---|---|
| 剛加入的成員 | 《isvn 使用手冊(任務導向)》的任務 1 至 6 |
| 要建立專案的 PM | 《isvn 安裝與部署指南》第 0、3、5、6 節 |
| 要串接外部工具的開發者 | 《isvn × Terminux 血緣查詢指令參考》第 1、2、5、7 節 |
| 想查某個畫面或指令的細節 | 參考用《isvn 使用手冊》 |