日本語 ▾ トピック ▾ 最新バージョン ▾ 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がチャンク数である場合、それぞれ12バイトの(C+1)行で構成されます。以下のテーブルを考慮してください

| 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: チャンクフォーマットAPIがgitformat-commit-graph[5]で文書化されているコミットグラフファイルフォーマットの書き込みと解析にどのように使用されるかについては、`commit-graph.c`の`write_commit_graph_file()`および`parse_commit_graph()`を参照してください。

  • multi-pack-index: チャンクフォーマットAPIがgitformat-pack[5]のmulti-pack-indexファイルフォーマットセクションで文書化されているmulti-pack-indexファイルフォーマットの書き込みと解析にどのように使用されるかについては、`midx.c`の`write_midx_internal()`および`load_multi_pack_index()`を参照してください。

Git

git[1] スイートの一部

scroll-to-top