English ▾ 主题 ▾ 最新版本 ▾ 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]（不含）。 因此，第 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。

读取基于块的文件格式

要读取基于块的文件格式，必须将该文件打开为内存映射区域。 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: 有关如何使用 chunk-format API 编写和解析 gitformat-commit-graph[5] 中的 commit-graph 文件格式文档中记录的 commit-graph 文件格式，请参见 commit-graph.c 中的 write_commit_graph_file() 和 parse_commit_graph()。

  • multi-pack-index: 有关如何使用 chunk-format API 编写和解析 gitformat-pack[5] 的 multi-pack-index 文件格式部分中记录的 multi-pack-index 文件格式，请参见 midx.c 中的 write_midx_internal() 和 load_multi_pack_index()。

GIT

属于 git[1] 套件的一部分

scroll-to-top