Git

名稱

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]（不包含）。因此，第 i 個區塊的大小等於 OFFSET[i+1] 和 OFFSET[i] 之間的差值。這需要區塊資料以與目錄相同的順序連續出現。

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

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

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

寫入基於區塊的檔案格式

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

然後，為每個要寫入的區塊呼叫 add_chunk()。這會使用要寫入的每個區塊的順序和大小資訊來填入 chunkfile。提供一個 chunk_write_fn 函數指標，以便在要求時執行區塊資料的寫入。

呼叫 write_chunkfile() 將目錄寫入 hashfile，然後是每個區塊。這將驗證每個區塊都寫入了預期的資料量，因此目錄是正確的。

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

讀取基於區塊的檔案格式

若要讀取基於區塊的檔案格式，必須將檔案開啟為記憶體對應區域。區塊格式 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：請參閱 commit-graph.c 中的 write_commit_graph_file() 和 parse_commit_graph()，了解如何使用區塊格式 API 來寫入和剖析在 gitformat-commit-graph[5] 中記錄的 commit-graph 檔案格式。

  • multi-pack-index：請參閱 midx.c 中的 write_midx_internal() 和 load_multi_pack_index()，了解如何使用區塊格式 API 來寫入和剖析在 gitformat-pack[5] 的 multi-pack-index 檔案格式區段中記錄的 multi-pack-index 檔案格式。

GIT

屬於 git[1] 套件的一部分

scroll-to-top