简体中文 ▾ 主题 ▾ 最新版本 ▾ 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