Path-Walk API

path-walk API は、到達可能なオブジェクトを走査するために使用しますが、共通のパスに基づいて、または型ごとに、バッチ単位でオブジェクトを訪問します。

たとえば、到達可能なコミットはすべて1つのグループとして訪問されます。タグもすべて1つのグループとして訪問されます。続いて、すべてのルートツリーが訪問されます。どこかの時点で、パス my/dir/to/A を介して到達可能なすべてのブロブが訪問されます。同じオブジェクトに到達するためのパスが複数ある場合でも、そのうちの1つのパスだけを使用してそのオブジェクトを訪問します。

Basics

path-walk API を使用するには、 path-walk.h をインクルードし、カスタマイズした path_walk_info 構造体を指定して walk_objects_by_path() を呼び出します。この構造体は、走査をどのように進めるかに関するすべてのオプションを設定するために使用します。以下、各オプションとその用途を詳しく見ていきましょう。

path_fn and path_fn_data: もっとも重要なオプションは path_fn オプションです。これは、型とパスでグループ化されたオブジェクトのオブジェクトIDに対してロジックを実行できるコールバックへの関数ポインタです。この関数は、コールバック関数にカスタムデータ構造を渡すために、path_fn_data メンバーに対応する data 値も受け取ります。
revs: 到達可能なオブジェクト集合の厳密な詳細を設定するには、revs メンバーを使用し、 revision.h のリビジョン機構を使って初期化します。 setup_revisions() や parse_revision_opt() などの呼び出しで revs を初期化します。 prepare_revision_walk() は walk_objects_by_path() の内部で呼び出されるため、呼び出さないでください。

また、revs 構造体に対して --objects フラグを指定しないことも重要です。リビジョンウォークはコミットを走査するためにのみ使用し、オブジェクトはそれらの開始コミットに基づいて別の方法で走査します。
commits
blobs
trees
tags: デフォルトでは、これらのメンバーは有効になっており、path-walk API がこれらの型のオブジェクトに対して path_fn を呼び出すべきであることを示します。特化したアプリケーションでは、オブジェクトの走査を単純にしたり path_fn の呼び出し回数を減らしたりするために、いくつかのオプションを無効化できます。

この方法でコミットだけを走査することも可能ですが、利用側はリビジョンウォーク API を使うほうがよいでしょう。
prune_all_uninteresting: デフォルトでは、path-walk API は到達可能なパスをすべて出力します。このオプションにより、含まれるオブジェクトがすべて UNINTERESTING フラグでマークされているパスには関心がないことを利用側が宣言できます。これには、リビジョンウォークで boundary オプションを使用して、UNINTERESTING フラグでマークされたコミットを走査が出力するようにする必要があります。
edge_aggressive: 性能上の理由から、通常は UNINTERESTING オブジェクトを見つけるために境界コミットだけを探索します。しかし、浅いクローン(shallow clones)の場合は、 UNINTERESTING な先端コミットから到達可能なすべてのツリーとブロブを UNINTERESTING としてマークすると役に立つことがあります。これはリビジョン API の --objects-edge-aggressive の挙動に一致します。
pl: このパターンリストポインタを使うと、 path-walk の検索対象をパターン集合に絞り込み、指定されたパターンに一致するパスだけを出力できます。パターンリストの詳細については gitignore(5) または git-sparse-checkout(1) を参照してください。パターンリストが cone-mode のパターンを使用している場合、 path-walk API は走査するパス集合を刈り込んで性能を改善できます。

Examples

使用例については以下を参照してください: t/helper/test-path-walk.c, builtin/pack-objects.c, builtin/backfill.c