跳至主要内容

Terminux 血緣查詢參考

這份文件是 isvn provenance query 與 isvn file query 的指令參考。所有 JSON 範例都是實際執行的輸出。

1. 定位

isvn 提供兩組唯讀的查詢指令,讓 Terminux 之類的外部工具以 subprocess 呼叫並解析 JSON:

isvn provenance query --type parent|ancestor-chain|root|pedigree   # 版本層級
isvn file query       --type versions|parent|root                  # 檔案層級
  • 只有 CLI 與 JSON,沒有 daemon,也沒有 HTTP API。
  • 兩組指令都是唯讀的,不修改版本、檔案或血緣。
  • 血緣是使用者宣告的:兩組指令不驗證檔案內容,也不從快取的 hash 或 refcount 推論血緣。每個版本最多一個直接上游;檔案以完全相同的路徑比對。

圖 Q-01:兩組查詢指令各自讀取的資料,以及 isvn 回答與不回答的事。

圖 Q-01 兩組查詢指令各自讀取的資料,以及 isvn 回答與不回答的事。

1.1 信任模型

系統 權威類型 回答什麼 不回答什麼
isvn 宣告的血緣與清單(declared provenance/declared inventory) 使用者建立版本時登記的上游關係;某個路徑出現在哪些版本 檔案內容是否真的來自那個來源
Terminux 內容事實(content fact) checksum ledger 顯示的實際產出鏈 取代 isvn 的版本決策

每個成功或失敗的查詢結果都帶有這兩個欄位,提醒呼叫端不要把它當成內容事實:

{ "authority": "declared_provenance", "content_verified": false }
{ "authority": "declared_inventory",  "content_verified": false }

1.2 適用版本

本文說明目前 isvn 的 isvn provenance query 與 isvn file query 兩組指令。使用中的 isvn 版本可以用 isvn version 查看。

本文的範例都在示範專案上執行,專案目錄是 /proj/demo/project。

2. 指令格式

isvn provenance query [--project <專案目錄>] --version <版本 ID> \
     --type parent|ancestor-chain|root|pedigree [--max-depth <N>] --json

isvn file query [--project <專案目錄>] [--version <版本 ID>] --path <相對路徑> \
     --type versions|parent|root --json

isvn file locate --path <路徑> [--project <專案目錄>] --json
參數 規則
--json 必填。省略時指令直接結束:stderr 印出 isvn: provenance query requires --json(或 file query requires --json),exit code 1
--project 選填。省略時依序使用環境變數 ISVN_PROJECT_DIR、目前所在的 workspace。都找不到時 stderr 印出 isvn: cannot locate project dir; set ISVN_PROJECT_DIR or run from a workspace,exit code 1。外部工具呼叫時建議明確傳入,結果就不受環境影響
--version 必須是完整的四段版本 ID:<phase>/<block>/<stage>/<version>,例如 trial/cpu/400_layout_datain/v1。不接受 v1 這類短名
--type 見第 3、4 節
--max-depth 只影響 ancestor-chain 與 pedigree。正整數,預設 20
--path 相對於版本根目錄的路徑,不可為絕對路徑,也不可含 ..

file query 必須在 workspace 內執行才有結果,原因見第 4.1 節。file locate 的 --path 可以是絕對路徑,規則見第 4.5 節。

2.1 版本物件與 canonical

查詢結果中的每個版本都是同一種物件:

{
  "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
  "phase": "trial", "block": "cpu", "stage": "200_fe_datain", "version": "v2"
}
  • canonical 的格式是 isvn://<專案目錄的名稱>/<phase>/<block>/<stage>/<version>。
    • 「專案目錄的名稱」是專案目錄路徑的最後一段。例如專案目錄是 /proj/demo/project,前綴就是 isvn://project/。
    • 因此不同專案只要目錄同名,canonical 就會相同。跨專案比對時,呼叫端要自己加上專案的區分。
  • 比對版本身分請用 canonical;phase/block/stage/version 只供顯示。

圖 Q-06:canonical 的組成。

圖 Q-06 canonical 的組成。

  • 視查詢類型,物件還會帶 depth(或 depth_from_subject)、relation、file_state、role。provenance query 的 subject 另外帶有 resolved: true。

舊資料的 ROOT 節點: 早期專案的血緣鏈可能以字串 ROOT 作為最上層的 parent。這種節點會輸出為:

{ "canonical": "isvn://<專案>/ROOT", "phase": null, "block": null, "stage": null, "version": "ROOT" }

以 create --parent ROOT 建立的根版本(目前的做法)沒有這個節點,鏈的最後一個就是根版本本身。

3. 版本層級:provenance query

資料來源只有 Lineage(建立版本時登記的上游)。每個版本最多一個直接上游。

假設鏈是 base → v1 → v2 → v3,subject 是 v3:

--type 回答 結果
parent 直接上游是誰 parent:單一物件,或 null
ancestor-chain 從上游一路往上有哪些祖先 ancestor_chain:由近到遠的陣列,不含 subject;另有 root 與 truncated
root 這條鏈最早的版本 root:單一物件
pedigree 從最早的版本到 subject 的完整鏈 pedigree.chain:由遠到近的陣列,包含 subject;另有 truncated

relation 的取值:parent(depth 1)、ancestor、root(鏈上最遠的一個)、subject(只出現在 pedigree)。 當直接上游同時也是根版本時,relation 是 parent。

圖 Q-02:provenance query 四種 --type 涵蓋的範圍。

圖 Q-02 provenance query 四種 --type 涵蓋的範圍。

3.1 ancestor-chain

Terminux 判斷「使用者宣告的來源是上游、祖先、根,還是不相符」時,只需要這一個查詢。

isvn provenance query --project /proj/demo/project \
     --version trial/cpu/400_layout_datain/v1 --type ancestor-chain --json
{
  "schema_version": "isvn.provenance.query.v0",
  "authority": "declared_provenance",
  "content_verified": false,
  "status": "ok",
  "query": {
    "type": "ancestor-chain",
    "project": "/proj/demo/project",
    "version": "trial/cpu/400_layout_datain/v1",
    "max_depth": 20
  },
  "subject": {
    "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
    "phase": "trial",
    "block": "cpu",
    "stage": "400_layout_datain",
    "version": "v1",
    "resolved": true
  },
  "ancestor_chain": [
    {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "phase": "trial",
      "block": "cpu",
      "stage": "200_fe_datain",
      "version": "v2",
      "depth": 1,
      "relation": "parent"
    },
    {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v1",
      "phase": "trial",
      "block": "cpu",
      "stage": "200_fe_datain",
      "version": "v1",
      "depth": 2,
      "relation": "ancestor"
    },
    {
      "canonical": "isvn://project/trial/cpu/000_datain/v1",
      "phase": "trial",
      "block": "cpu",
      "stage": "000_datain",
      "version": "v1",
      "depth": 3,
      "relation": "root"
    }
  ],
  "root": {
    "canonical": "isvn://project/trial/cpu/000_datain/v1",
    "phase": "trial",
    "block": "cpu",
    "stage": "000_datain",
    "version": "v1",
    "depth": 3,
    "relation": "root"
  },
  "truncated": false,
  "warnings": []
}

保證事項:

  1. ancestor_chain 不含 subject,由近到遠排序,depth 從 1 開始連續遞增。
  2. depth: 1 一定是直接上游。
  3. 沒有截斷時,root 等於 ancestor_chain 的最後一個元素。
  4. subject 本身是根版本時:ancestor_chain 是空陣列,root 是 subject 自己(depth: 0)。

截斷: 祖先數超過 --max-depth 時,truncated 是 true,root 是 null,並附上警告:

isvn provenance query --version trial/cpu/400_layout_datain/v1 --type ancestor-chain --max-depth 2 --json

和未截斷時不同的欄位(ancestor_chain 只剩最近的兩個):

{
  "root": null,
  "truncated": true,
  "warnings": [
    {
      "code": "MAX_DEPTH_REACHED",
      "message": "The provenance traversal reached --max-depth."
    }
  ]
}

3.2 parent

圖 Q-03 是在終端機實際執行的樣子(輸出經 python3 -m json.tool 排版):

圖 Q-03:provenance query --type parent 的實際輸出。

圖 Q-03 provenance query --type parent 的實際輸出。

{
  "schema_version": "isvn.provenance.query.v0",
  "authority": "declared_provenance",
  "content_verified": false,
  "status": "ok",
  "query": {
    "type": "parent",
    "project": "/proj/demo/project",
    "version": "trial/cpu/400_layout_datain/v1"
  },
  "subject": {
    "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
    "phase": "trial",
    "block": "cpu",
    "stage": "400_layout_datain",
    "version": "v1",
    "resolved": true
  },
  "parent": {
    "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
    "phase": "trial",
    "block": "cpu",
    "stage": "200_fe_datain",
    "version": "v2",
    "depth": 1,
    "relation": "parent"
  },
  "warnings": []
}

subject 是根版本時,parent 是 null,並附上警告 ROOT_VERSION(節錄,省略 schema_version、authority、content_verified、query):

{
  "status": "ok",
  "subject": {
    "canonical": "isvn://project/trial/cpu/000_datain/v1",
    "phase": "trial",
    "block": "cpu",
    "stage": "000_datain",
    "version": "v1",
    "resolved": true
  },
  "parent": null,
  "warnings": [
    {
      "code": "ROOT_VERSION",
      "message": "This version has no declared parent."
    }
  ]
}

3.3 root

節錄,省略的欄位同上:

{
  "status": "ok",
  "subject": {
    "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
    "phase": "trial",
    "block": "cpu",
    "stage": "400_layout_datain",
    "version": "v1",
    "resolved": true
  },
  "root": {
    "canonical": "isvn://project/trial/cpu/000_datain/v1",
    "phase": "trial",
    "block": "cpu",
    "stage": "000_datain",
    "version": "v1",
    "depth": 3,
    "relation": "root"
  },
  "warnings": []
}

3.4 pedigree

陣列方向是「根 → subject」,深度欄位叫 depth_from_subject。截斷時只保留最近的 --max-depth 個祖先,truncated 是 true。

節錄(省略 schema_version、authority、content_verified、query、subject):

{
  "status": "ok",
  "pedigree": {
    "model": "single_parent_chain",
    "direction": "root_to_subject",
    "chain": [
      {
        "canonical": "isvn://project/trial/cpu/000_datain/v1",
        "phase": "trial",
        "block": "cpu",
        "stage": "000_datain",
        "version": "v1",
        "depth_from_subject": 3,
        "relation": "root"
      },
      {
        "canonical": "isvn://project/trial/cpu/200_fe_datain/v1",
        "phase": "trial",
        "block": "cpu",
        "stage": "200_fe_datain",
        "version": "v1",
        "depth_from_subject": 2,
        "relation": "ancestor"
      },
      {
        "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
        "phase": "trial",
        "block": "cpu",
        "stage": "200_fe_datain",
        "version": "v2",
        "depth_from_subject": 1,
        "relation": "parent"
      },
      {
        "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
        "phase": "trial",
        "block": "cpu",
        "stage": "400_layout_datain",
        "version": "v1",
        "depth_from_subject": 0,
        "relation": "subject"
      }
    ]
  },
  "truncated": false,
  "warnings": []
}

4. 檔案層級:file query

三種查詢的主要結果一律是陣列,即使只有一筆:

--type 主要結果 其他欄位
versions versions[] summary(version_count、first_seen、latest_seen)
parent parent_versions[] subjects[]、per_subject[]
root root_versions[] subjects[]、per_subject[]

4.1 清單的來源是「本機 workspace」,不是整個專案

使用 file query 之前,務必先了解它的清單範圍:

  • file query 檢查的版本,只限於呼叫者目前 workspace 已經 checkout 的版本(.isvn_local/workspaces 登記、而且工作副本實際存在)。
  • 「某版本包含這個路徑」的判斷方式,是該版本的工作副本中存在這個路徑。
  • 它不會讀取 SVN repository,也不會替你 checkout。
  • 只要路徑存在就算數:尚未提交、只存在於工作副本的新檔案也會被列入,managed 同樣是 true。
  • 因此:
    • file.managed: false 的意思是「本機已 checkout 的版本裡都沒有這個路徑」,不代表專案中沒有這個檔案。
    • 在 workspace 之外執行(即使給了 --project),結果一定是 managed: false。
    • 換一個 workspace、或多 checkout 一個版本,同一個查詢的結果就會不同。

圖 Q-04:file query 的清單範圍:只有呼叫者 workspace 中已 checkout 的版本。

圖 Q-04 file query 的清單範圍:只有呼叫者 workspace 中已 checkout 的版本。

同一個專案、同一個路徑,在只 checkout 一個版本時與 checkout 兩個版本時的結果:

isvn file query --path top.v --type versions --json      # 只 checkout 了 200_fe_datain/v2

節錄 file、versions、summary:

{
  "file": {
    "path": "top.v",
    "managed": true
  },
  "versions": [
    {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "phase": "trial",
      "block": "cpu",
      "stage": "200_fe_datain",
      "version": "v2",
      "file_state": "checked_in",
      "role": "first_seen"
    }
  ],
  "summary": {
    "version_count": 1,
    "first_seen": {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "version": "v2"
    },
    "latest_seen": {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "version": "v2"
    }
  }
}
isvn file query --path top.v --type versions --json      # 再 checkout 400_layout_datain/v1 之後
{
  "schema_version": "isvn.file.query.v0",
  "authority": "declared_inventory",
  "content_verified": false,
  "status": "ok",
  "query": {
    "type": "versions",
    "project": "/proj/demo/project",
    "path": "top.v"
  },
  "file": {
    "path": "top.v",
    "managed": true
  },
  "versions": [
    {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "phase": "trial",
      "block": "cpu",
      "stage": "200_fe_datain",
      "version": "v2",
      "file_state": "checked_in",
      "role": "first_seen"
    },
    {
      "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
      "phase": "trial",
      "block": "cpu",
      "stage": "400_layout_datain",
      "version": "v1",
      "file_state": "checked_in",
      "role": "seen"
    }
  ],
  "summary": {
    "version_count": 2,
    "first_seen": {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "version": "v2"
    },
    "latest_seen": {
      "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
      "version": "v1"
    }
  },
  "warnings": []
}

4.2 欄位的意義

欄位 行為
versions[] 的順序 依版本 ID 的字串順序,不是血緣或時間順序
role 排序後第一筆是 first_seen,其餘是 seen
summary.first_seen/latest_seen 排序後的第一筆與最後一筆
file_state 路徑是檔案時是 checked_in(LINKED 的 symlink、LOCAL 的實體檔、尚未提交的新檔都一樣),是目錄時是 directory。取值只有這兩種:它區分檔案與目錄,不表示檔案是否已提交或被修改
--type versions 加上 --version 只檢查那一個版本的工作副本有沒有這個路徑:有就回傳該版本,沒有就是空陣列加上 FILE_NOT_MANAGED
subjects[] 帶 --version 時是該版本(如果它包含這個路徑);不帶時是本機所有包含這個路徑的版本

4.3 parent 與 root

對每個 subject,沿著 Lineage 的祖先鏈往上找:

  • file parent: 最近一個「本機已 checkout、而且包含相同路徑」的祖先。depth 是它在祖先鏈上的距離。
  • file root: 最遠一個符合同樣條件的祖先。如果沒有任何祖先符合,而 subject 自己包含這個路徑,結果就是 subject 自己(depth: 0)。
  • 祖先沒有 checkout 到本機時會被略過,所以結果可能比實際的血緣短。
  • 只比對完全相同的路徑,不追蹤改名。
  • 不帶 --version 時,對每個 subject 各自計算,再把候選版本去重後放進 parent_versions[]/root_versions[];每個 subject 各自的結果在 per_subject[]。
isvn file query --version trial/cpu/400_layout_datain/v1 --path top.v --type parent --json
{
  "schema_version": "isvn.file.query.v0",
  "authority": "declared_inventory",
  "content_verified": false,
  "status": "ok",
  "query": {
    "type": "parent",
    "project": "/proj/demo/project",
    "version": "trial/cpu/400_layout_datain/v1",
    "path": "top.v"
  },
  "file": {
    "path": "top.v",
    "managed": true
  },
  "subjects": [
    {
      "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
      "phase": "trial",
      "block": "cpu",
      "stage": "400_layout_datain",
      "version": "v1",
      "file_state": "checked_in"
    }
  ],
  "parent_versions": [
    {
      "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
      "phase": "trial",
      "block": "cpu",
      "stage": "200_fe_datain",
      "version": "v2",
      "file_state": "checked_in",
      "depth": 1,
      "relation": "file_parent"
    }
  ],
  "per_subject": [
    {
      "subject": {
        "canonical": "isvn://project/trial/cpu/400_layout_datain/v1",
        "version": "v1"
      },
      "parent_versions": [
        {
          "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
          "version": "v2",
          "depth": 1,
          "relation": "file_parent"
        }
      ]
    }
  ],
  "warnings": []
}

--type root 的結構相同,只是鍵名換成 root_versions、relation 是 file_root。

4.4 不在清單中的路徑

查詢合法、但本機沒有任何版本包含這個路徑時,exit code 仍是 0,陣列是空的,並附上警告:

{
  "schema_version": "isvn.file.query.v0",
  "authority": "declared_inventory",
  "content_verified": false,
  "status": "ok",
  "query": {
    "type": "versions",
    "project": "/proj/demo/project",
    "path": "tmp/debug.log"
  },
  "file": {
    "path": "tmp/debug.log",
    "managed": false
  },
  "versions": [],
  "summary": {
    "version_count": 0,
    "first_seen": null,
    "latest_seen": null
  },
  "warnings": [
    {
      "code": "FILE_NOT_MANAGED",
      "message": "The file path is not managed by isvn."
    }
  ]
}

parent/root 查詢在這種情況下輸出 subjects: []、空的 parent_versions(或 root_versions)與 per_subject: []。

4.5 路徑所在的版本:file locate

file locate 回答「這個路徑在哪一個版本的工作副本中、是什麼座標」。外部工具手上只有絕對路徑時用它:

isvn file locate --path /proj/demo/ws/trial/cpu/200_fe_datain/v2/top.v --json
{
  "schema_version": "isvn.file.locate.v0",
  "authority": "declared_inventory",
  "content_verified": false,
  "status": "ok",
  "query": {
    "type": "locate",
    "path": "/proj/demo/ws/trial/cpu/200_fe_datain/v2/top.v"
  },
  "managed": true,
  "project": {
    "dir": "/proj/demo/project",
    "name": "project"
  },
  "version": {
    "canonical": "isvn://project/trial/cpu/200_fe_datain/v2",
    "phase": "trial",
    "block": "cpu",
    "stage": "200_fe_datain",
    "version": "v2"
  },
  "file": {
    "path": "top.v",
    "kind": "file",
    "link_state": "LINKED",
    "working_copy": "/proj/demo/ws/trial/cpu/200_fe_datain/v2"
  },
  "warnings": []
}
  • --path 可以是絕對路徑,也可以是相對於目前目錄的路徑。isvn 從路徑往上找 workspace,再用該 workspace 的版本清單(.isvn_local/workspaces)找出包含這個路徑的版本;呼叫者不需要在 workspace 內執行,也不需要指定專案。
  • 路徑上層的目錄若是經由連結到達(例如 workspace 位於連結過去的目錄),isvn 會解析上層目錄;路徑本身不解析,所以 LINKED 檔案回報的是它所在的版本,不是 pool。
  • 結果是唯一的:只看路徑所在的工作副本,不受其他已 checkout 版本的影響。
  • --project 選填,是核對條件:給了而與查到的專案目錄不同時,回傳錯誤 PROJECT_MISMATCH(exit code 2)。
  • 指令只讀:不讀檔案內容、不連線 SVN、不讀 Lineage,也不改動任何東西。
欄位 意義
managed 路徑在某個版本的工作副本中,而且存在
project.dir、project.name 專案目錄,以及組成 canonical 的名稱
version 路徑所在的版本,格式同第 2.1 節
file.path 相對於版本根目錄的路徑,可以直接用於 file query --path
file.kind file、directory、link(不指向 pool 的連結)或 absent
file.link_state LINKED(pool 連結)、LOCAL(實體檔);目錄與其他連結是空字串
警告 情況 managed
PATH_NOT_IN_VERSION 路徑不在任何 workspace 已 checkout 的版本中;project、version、file 都是 null false
FILE_NOT_FOUND 路徑在版本中,但不存在 false
VERSION_ROOT 路徑就是版本的根目錄 false

5. 錯誤、警告與 exit code

情況 輸出位置與格式 exit code
成功(包含「不在清單中」) stdout,單一 JSON 文件,status: "ok" 0
參數錯誤:缺 --type/--version/--path、--type 不合法、--max-depth 不是正整數、--path 是絕對路徑或含 ..、provenance query 的版本 ID 不是四段 stdout,isvn.error.v0 2
provenance query 找不到版本 stdout,isvn.provenance.query.v0,status: "error",error.code: "VERSION_NOT_FOUND" 2
血緣資料出現循環 同上,error.code: "PROVENANCE_CYCLE_DETECTED";其他走訪失敗是 PROVENANCE_QUERY_FAILED 2
沒有 --json stderr 純文字 1
找不到專案目錄 stderr 純文字 1
file query 的 --version 不是四段,或該版本沒有 checkout 到本機 stderr 純文字,例如 isvn: version is not checked out in this workspace; run isvn checkout <版本> first 1

呼叫端的處理原則:exit code 不是 0 時,stdout 不一定是 JSON。先看 exit code,再解析。

圖 Q-05:三種 exit code 與對應的輸出位置。

圖 Q-05 三種 exit code 與對應的輸出位置。

三種情況在終端機中的樣子:

圖 Q-09:參數錯誤(exit code 2)、找不到版本(exit code 2)與缺少 --json(exit code 1)的實際輸出。

圖 Q-09 參數錯誤(exit code 2)、找不到版本(exit code 2)與缺少 --json(exit code 1)的實際輸出。

參數錯誤的格式:

{
  "schema_version": "isvn.error.v0",
  "status": "error",
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "version must contain exactly four path segments"
  }
}

找不到版本:

{
  "schema_version": "isvn.provenance.query.v0",
  "authority": "declared_provenance",
  "content_verified": false,
  "status": "error",
  "query": {
    "type": "parent",
    "project": "/proj/demo/project",
    "version": "trial/cpu/400_layout_datain/v9"
  },
  "error": {
    "code": "VERSION_NOT_FOUND",
    "message": "Version not found: trial/cpu/400_layout_datain/v9"
  },
  "warnings": []
}

警告代碼(warnings[].code):

代碼 出現時機
ROOT_VERSION --type parent,而 subject 沒有上游
MAX_DEPTH_REACHED ancestor-chain/pedigree 被 --max-depth 截斷
FILE_NOT_MANAGED file query 在本機找不到包含這個路徑的版本

6. 相容性

  • 查詢結果是 JSON,schema_version 是第 3 至 5 節所示的名稱:isvn.provenance.query.v0、isvn.file.query.v0、isvn.error.v0。
  • 之後的版本可能增加欄位。呼叫端必須忽略不認識的欄位,也不可依賴鍵的順序。

7. 呼叫端規則

用 canonical 比對版本身分。
用 depth/relation 分類(上游、祖先、根)。
phase/block/stage/version 只用於顯示。

用 ancestor-chain 一次完成分類的建議順序(declared 是使用者宣告的來源版本的 canonical):

declared == ancestor_chain 中 depth 為 1 的 canonical   → match_parent
declared == root.canonical(root 不是 null)            → match_root
declared 出現在 ancestor_chain 的 canonical 中          → match_ancestor
truncated 為 true 而且以上都不符合                      → 不能下結論,加大 --max-depth 再查
其他                                                    → mismatch_declared_source

要找出某個檔案所在的版本時,用 file locate(第 4.5 節),不要直接取 file query 的 versions[0]:versions[] 依版本 ID 的字串順序排列,而且只包含呼叫者 workspace 已 checkout 的版本(見第 4.1、4.2 節)。

7.1 Terminux 的 DQE check-in

Terminux 把 DQE package 寫進一個版本時,依序呼叫 isvn:

  1. 以 isvn status --json 列出版本中的檔案;link_state 是 LINKED 的項目就是受管的檔案,files[].path 是相對於版本目錄的路徑。
  2. 對即將覆寫的受管檔案執行 isvn edit。
  3. 寫入 package 的檔案。
  4. 對每個檔案執行 isvn checkin <檔案> --to <版本>。

單一路徑的 isvn checkin 只提交指定的路徑,工作副本中其他的 LINKED 檔案不受影響;新檔案上層還沒有入版的資料夾(例如 attachments/)會一起提交。提交後,檔案再度是 LINKED(見《isvn 使用手冊》第 19.2 節)。

呼叫順序與三種結果如圖 Q-07,三種結果都是成功:

圖 Q-07:Terminux DQE check-in 的呼叫順序,以及三種情況的結果。

圖 Q-07 Terminux DQE check-in 的呼叫順序,以及三種情況的結果。

情況 結果
第一次 check-in package 的每個檔案都被提交
同一個 job 再 check-in,內容有變更 只有變更的檔案產生新修訂,例如數值改變時只有 package 的 JSON;內容沒有變更的檔案回報沒有變更
同一個 job 再 check-in,內容沒有變更 不建立修訂;每個檔案的 isvn checkin 都以 exit code 0 結束,並印出 no changes in <名稱> compared with <版本>; nothing was committed(加 --json 時是 "result":"unchanged","revision":null)

8. GUI 入口

GUI 的「探索」頁(「Workspace B — 血緣與證據探索」)使用同樣的兩組指令:

  • 版本血緣(Version Lineage): Parent、Ancestor Chain、Root、Pedigree。
  • 檔案血緣(File Lineage): Versions、Parent Versions、Root Versions。
  • 畫面上固定顯示「宣告來源」(Declared provenance)或「宣告清單」(Declared inventory),以及「未驗證內容」(Not content-verified)。
  • 查詢結果畫成關係圖,點選節點可以在節點檢視器看到 canonical 等資訊。
  • GUI 的檔案血緣同樣只看本機已 checkout 的版本。

圖 U-24 是版本血緣(Ancestor Chain)的查詢結果,圖 U-25 是檔案血緣(Versions)的查詢結果;兩張圖也出現在《isvn 使用手冊》第 14 節。

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

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

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

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

9. 測試與證據

兩組指令都有自動測試,涵蓋七種查詢、根版本、--max-depth、找不到版本、不在清單中的路徑,以及舊資料的 ROOT 節點。本文的 JSON 範例與終端機插圖,都是在示範專案上實際執行的輸出。

10. 範圍

isvn provenance query 回答版本層級的血緣:使用者建立版本時宣告的上游,以及由此串成的祖先鏈、根與完整血緣。isvn file query 回答檔案層級的出現情況:某個路徑出現在呼叫者 workspace 已 checkout 的哪些版本中,以及沿著宣告的血緣找到的檔案上游與根。isvn file locate 回答一個路徑在哪一個版本的工作副本中。檔案內容是否真的來自宣告的來源,由 Terminux 的 checksum ledger 回答(見第 1.1 節)。