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 番目のチャンクのサイズは、OFFSET[i+1] と OFFSET[i] の差に等しくなります。 これには、チャンクデータが目次に示されているのと同じ順序で連続して出現する必要があります。

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

注：チャンクベースの形式では、ファイルに 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 をファイナライズする必要があります。

チャンクベースのファイル形式の読み取り

チャンクベースのファイル形式を読み取るには、ファイルをメモリマップされた領域として開く必要があります。 チャンク形式 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 ファイル形式で説明されている 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