gitformat-chunk(5) Manual Page

gitformat-commit-graph(5) や MIDX形式で使用されます(gitformat-pack(5) の「pack format」のドキュメントを参照してください)。

Git の一部のファイル形式では、 「チャンク」という一般的な概念を使用して、ファイルのセクションを記述します。 これにより、小さな「目次」をスキャンして残りのデータを探すことで、 大きなファイルへの構造化されたアクセスが可能になります。 この一般的な形式は、 コミット・グラフ・ファイルとマルチ・パック・インデックス・ファイルで使用されます。チャンクを使用して構造化データを記述する方法については、 gitformat-pack(5) の マルチ・パックインデックス形式と gitformat-commit-graph(5) の コミット・グラフ形式を参照してください。

チャンクベースファイル形式(chunk-based file format)は、その形式に合わせたヘッダー情報から始まります。 そのヘッダーには、ファイルタイプ、形式バージョン、ファイル内のチャンクの数、を識別するのに十分な情報が含まれている必要があります。 この情報から、そのファイルはチャンクベース領域(chunk-based region)の開始を決定する事ができます。

チャンクベース領域(chunk-based region)は、各チャンクの開始と終了を説明する目次(table of contents)で始まります。 これは、各行(row)12バイトの (C+1)行(row)で構成されます。ここで、Cはチャンクの数です。 以下の表をじっくり見やがれしてください。

各行(row)は、4バイトのチャンク識別子(ID)と8バイトのオフセットで構成されます。各整数はネットワークバイトオーダーで格納されます。

The chunk identifier ID[i] is a label for the data stored within this file from OFFSET[i] (inclusive) to OFFSET[i+1] (exclusive). Thus, the size of the i`th chunk is equal to the difference between `OFFSET[i+1] and OFFSET[i]. This requires that the chunk data appears contiguously in the same order as the table of contents.

目次の最後のエントリは、4つのゼロバイトである必要があります。 これにより、目次が終了していることが確認され、チャンクベースのデータの終了のオフセットが提供されます。

注意: チャンクベース形式では、ファイルの OFFSET[C+1] の後に、「少なくとも」末尾のハッシュ(trailing hash)が含まれている必要があります。

チャンクベースのファイル形式を操作するための関数は、 chunk-format.h で宣言されています。 これらのメソッドを使用すると、開発者が新しいファイル形式を作成するときに役立つ追加のチェックが提供されます。

チャンクベースファイル形式を作成するには、 init_chunkfile()_ を呼び出して `struct chunkfile を作成し、 struct hashfile ポインタを渡します。 呼び出し元は、 hashfile を開き、ヘッダー情報を書き込む責任があります。これにより、チャンクベース形式が始まる前にファイル形式を識別できます。

Then, call add_chunk() for each chunk that is intended for writing. This populates the chunkfile with information about the order and size of each chunk to write. Provide a chunk_write_fn function pointer to perform the write of the chunk data upon request.

write_chunkfile() を呼び出して、目次(table of contents)を hashfile に書き込み、その後に各チャンクを書き込みます。 これにより、各チャンクが予想される量のデータを書き込んだことを確認し、目次が正しいことを確認します。

最後に、 free_chunkfile() を呼び出して、 structc hunkfile データをクリアします。 呼び出し元は、末尾のハッシュ(trailing hash)を書き込んでファイルを閉じることにより、 hashfile を完成させる責任があります。

チャンクベースファイル形式を読み取るには、ファイルをメモリマップ領域(memory-mapped region)として開く必要があります。 チャンク形式のAPIは、ファイル全体が連続したメモリ領域としてマップされることを想定しています。

init_chunkfile(NULL) で struct chunkfile ポインタを初期化します。

ファイルの先頭からチャンクカウント(chunk count)を含むヘッダー情報を読み取った後、 read_table_of_contents() を呼び出して、 structc hunkfile にチャンクのリスト、それらのオフセット、およびそれらのサイズを入力します。

pair_chunk() または read_chunk() を使用して、各チャンクのデータ情報を抽出します:

これらのメソッドを呼び出した後、 free_chunkfile() を呼び出して structc hunkfile データをクリアします。 これにより、メモリマップ領域は閉じられません。 呼び出し元は、領域へのポインタが必要とされている間はデータを所有しつづけることが期待されます。

これらのファイル形式はチャンク形式のAPIを使用しており、将来の形式の例として使用できます:

Part of the git(1) suite