Git
英语 ▾ 主题 ▾ 最新版本 ▾ gitformat-chunk 最后更新于 2.43.0

名称

gitformat-chunk - 基于块的文件格式

概要

由 gitformat-commit-graph[5] 和 “MIDX” 格式使用（参见 gitformat-pack[5] 中的包格式文档）。

描述

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`th 块的大小等于 `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。

读取基于块的文件格式

要读取基于块的文件格式，必须将文件打开为内存映射区域。块格式 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()，了解如何在 gitformat-commit-graph[5] 中记录的提交图文件格式中使用块格式 API 来写入和解析提交图文件格式。

  • multi-pack-index: 在 midx.c 中查看 write_midx_internal() 和 load_multi_pack_index()，了解如何在 gitformat-pack[5] 的多包索引文件格式部分记录的多包索引文件格式中使用块格式 API 来写入和解析多包索引文件格式。

GIT

是 git[1] 套件的一部分

scroll-to-top