简体中文 ▾ 主题 ▾ 最新版本 ▾ 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] 套件的一部分