English ▾ トピック ▾ 最新バージョン ▾ 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番目のチャンクのサイズはOFFSET[i+1] と OFFSET[i] の差に等しくなります。これは、チャンクデータが目次と同じ順序で連続して表示されることを必要とします。

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

注: チャンクベースの形式は、ファイルに 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: gitformat-commit-graph[5] に記載されている commit-graph ファイル形式を書き込み、解析するためにチャンク形式 API がどのように使用されているかについては、commit-graph.c の write_commit_graph_file() および parse_commit_graph() を参照してください。

  • multi-pack-index: gitformat-pack[5] の multi-pack-index ファイル形式セクションに記載されている multi-pack-index ファイル形式を書き込み、解析するためにチャンク形式 API がどのように使用されているかについては、midx.c の write_midx_internal() および load_multi_pack_index() を参照してください。

GIT

git[1]スイートの一部

scroll-to-top