簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitformat-chunk 最後更新於 2.43.0

名稱

gitformat-chunk - 基於塊的檔案格式

概要

由 gitformat-commit-graph[5] 和 "MIDX" 格式使用（請參閱 gitformat-pack[5] 中的 pack 格式文件）。

描述

Git 中的某些檔案格式使用“塊”的通用概念來描述檔案的各個部分。這允許透過掃描一小部分“目錄”來結構化地訪問大檔案。這種通用格式由 commit-graph 和 multi-pack-index 檔案使用。有關它們如何使用塊來描述結構化資料的資訊，請參閱 gitformat-pack[5] 中的 multi-pack-index 格式以及 gitformat-commit-graph[5] 中的 commit-graph 格式。

基於塊的檔案格式以該格式特有的某些頭部資訊開頭。該頭部應包含足夠的資訊來標識檔案型別、格式版本和檔案中的塊數。根據這些資訊，該檔案可以確定基於塊的區域的起始位置。

基於塊的區域以一個目錄開頭，該目錄描述了每個塊的開始和結束位置。這由 C+1 行組成，每行 12 位元組，其中 C 是塊的數量。請考慮以下表

| Chunk ID (4 bytes) | Chunk Offset (8 bytes) |
|--------------------|------------------------|
| ID[0]              | OFFSET[0]              |
| ...                | ...                    |
| ID[C]              | OFFSET[C]              |
| 0x0000             | OFFSET[C+1]            |

每一行由一個 4 位元組的塊識別符號（ID）和一個 8 位元組的偏移量組成。每個整數都以網路位元組序儲存。

塊識別符號 ID[i] 是儲存在此檔案中的資料標籤，從 OFFSET[i]（包含）到 OFFSET[i+1]（不包含）。因此，ith chunk 的大小 等於 OFFSET[i+1] 和 OFFSET[i] 之間的差值。這就要求塊資料以與目錄相同的順序連續出現。

目錄中的最後一個條目必須是四個零位元組。這確認了目錄的結束，並提供了基於塊資料的結束偏移量。

注意：基於塊的格式期望檔案在 OFFSET[C+1] 之後*至少*包含一個尾隨雜湊。

用於處理基於塊的檔案格式的函式宣告在 chunk-format.h 中。使用這些方法可以提供額外的檢查，以協助開發人員建立新的檔案格式。

編寫基於塊的檔案格式

要編寫基於塊的檔案格式，請透過呼叫 init_chunkfile() 並傳入 struct hashfile 指標來建立一個 struct chunkfile。呼叫者負責開啟 hashfile 並寫入頭部資訊，以便在基於塊的格式開始之前就可以識別檔案格式。

然後，為要寫入的每個塊呼叫 add_chunk()。這將用有關要寫入的塊的順序和大小的資訊填充 chunkfile。提供一個 chunk_write_fn 函式指標，以便在請求時執行塊資料的寫入。

呼叫 write_chunkfile() 將目錄寫入 hashfile，然後寫入每個塊。這將驗證每個塊是否寫入了預期的數量資料，從而確保目錄的準確性。

最後，呼叫 free_chunkfile() 來清除 struct chunkfile 資料。呼叫者負責透過寫入尾隨雜湊並關閉檔案來完成 hashfile。

讀取基於塊的檔案格式

要讀取基於塊的檔案格式，檔案必須作為記憶體對映區域開啟。chunk-format API 期望整個檔案被對映為一個連續的記憶體區域。

使用 init_chunkfile(NULL) 初始化一個 struct chunkfile 指標。

在從檔案開頭讀取頭部資訊（包括塊計數）後，呼叫 read_table_of_contents() 來用塊列表、它們的偏移量和大小填充 struct chunkfile。

使用 pair_chunk() 或 read_chunk() 提取每個塊的資料資訊。

  • pair_chunk() 將給定指標設定為記憶體對映檔案中對應於該塊偏移量的位置。如果塊不存在，則指標不會被修改。

  • read_chunk() 接受一個 chunk_read_fn 函式指標，並使用適當的初始指標和大小資訊呼叫它。如果塊不存在，則不呼叫該函式。如果您需要執行即時解析或需要基於塊的大小執行邏輯，請使用此方法讀取塊。

呼叫這些方法後，呼叫 free_chunkfile() 來清除 struct chunkfile 資料。這不會關閉記憶體對映區域。呼叫者應負責在需要指向該區域的指標期間擁有該資料。

示例

這些檔案格式使用 chunk-format API，並且可以作為未來格式的示例

  • commit-graph: 請參閱 commit-graph.c 中的 write_commit_graph_file() 和 parse_commit_graph()，瞭解如何使用 chunk-format API 來編寫和解析 gitformat-commit-graph[5] 中記錄的 commit-graph 檔案格式。

  • multi-pack-index: 請參閱 midx.c 中的 write_midx_internal() 和 load_multi_pack_index()，瞭解如何使用 chunk-format API 來編寫和解析 gitformat-pack[5] 的 multi-pack-index 檔案格式部分中記錄的 multi-pack-index 檔案格式。

GIT

Git[1] 套件的一部分