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

名稱

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

概要

被 gitformat-commit-graph[5] 和“MIDX”格式使用（參見 gitformat-pack[5] 中的包格式文件）。

描述

Git 中的一些檔案格式使用“資料塊”（chunk）的通用概念來描述檔案的不同部分。這允許透過掃描一個小的“目錄”來獲取剩餘資料，從而實現對大檔案的結構化訪問。這種通用格式被 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]（不包含）儲存的資料的標籤。因此，第 i 個數據塊的大小等於 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 資料。這不會關閉記憶體對映區域。呼叫者應在需要區域內指標的時間段內擁有該資料。

讀取基於資料塊的檔案格式

要讀取基於資料塊的檔案格式，必須將檔案作為記憶體對映區域開啟。資料塊格式 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 資料。這不會關閉記憶體對映區域。呼叫者應在需要區域內指標的時間段內擁有該資料。

示例

這些檔案格式使用資料塊格式 API，可以作為未來格式的示例

  • 提交圖：參見 commit-graph.c 中的 write_commit_graph_file() 和 parse_commit_graph()，瞭解如何使用資料塊格式 API 寫入和解析在 gitformat-commit-graph[5] 中有文件的提交圖檔案格式。

  • 多包索引：參見 midx.c 中的 write_midx_internal() 和 load_multi_pack_index()，瞭解如何使用資料塊格式 API 寫入和解析在 gitformat-pack[5] 的多包索引檔案格式部分中記錄的多包索引檔案格式。

GIT

Git[1] 套件的一部分

scroll-to-top