バンドル URI 標準は、複数のワークロードを満たすのに十分な柔軟性を持つことを目指しています。バンドルプロバイダーと Git クライアントは、バンドル URI の作成と消費においていくつかの選択肢を持っています。

各リポジトリは異なり、すべての Git サーバーには異なるニーズがあります。バンドル URI 機能がすべてのニーズを満たすのに十分な柔軟性があることを願っています。そうでない場合は、そのバージョン管理メカニズムを通じて機能を拡張できます。

バンドルサーバーのサーバーサイド実装を提供するために、Git プロトコルの他の部分は必要ありません。これにより、サーバー管理者は CDN などの静的コンテンツソリューションを使用してバンドルファイルを提供できます。

バンドル URI 機能の現在の範囲では、すべての URI は、その URL への GET リクエストを使用してコンテンツがローカルファイルにダウンロードされる HTTP(S) URL であると想定されています。サーバーは、セキュアなアクセスを可能にするために設定された認証ヘルパーをトリガーすることを目的として、これらのリクエストに認証要件を含めることができます。（将来の拡張では、「file://」URI または SSH URI を使用できます。）

サーバーからの 200 OK 応答を仮定すると、URL のコンテンツが検査されます。まず、Git はファイルをバージョン 2 以上のバンドルファイルとして解析しようとします。ファイルがバンドルでない場合、ファイルは Git の設定パーサーを使用してプレーンテキストファイルとして解析されます。その設定ファイル内のキーと値のペアは、バンドル URI のリストを記述していると想定されます。これらの解析試行のいずれも成功しない場合、Git はバンドル URI が誤ったデータを提供したというエラーをユーザーに報告します。

サーバーによって提供されるその他のデータは誤りであるとみなされます。

Git サーバーは、key=value ペアのセットを使用してバンドル URI をアドバタイズできます。バンドル URI は、これらの同じ key=value ペアを含む Git 設定形式のプレーンテキストファイルを提供することもできます。どちらの場合も、これをバンドルリストと見なします。これらのペアは、クライアントがどのバンドルをダウンロードし、どのバンドルを無視するかを決定するために使用できるバンドルに関する情報を指定します。

いくつかのキーは、リスト自体のプロパティに焦点を当てています。

残りのキーには <id> セグメントが含まれており、これは利用可能な各バンドルのサーバー指定名です。<id> は英数字と - 文字のみを含む必要があります。

以下は、Git config 形式を使用したバンドルリストの例です

この例では、bundle.mode=all と bundle.<id>.creationToken ヒューリスティックを使用しています。また、bundle.<id>.filter オプションを使用して、フルクローン用とブロブなしパーシャルクローン用の2つの並行するバンドルセットを提示しています。

このバンドルリストが URI https://bundles.example.com/git/git/ で見つかったと仮定すると、2つのブロブなしバンドルには以下の完全な URI があります

ユーザーがクローンするリポジトリのバンドル URI を知っている場合、コマンドラインオプションを通じてその URI を手動で指定できます。ただし、Git ホストは、クローン操作中にバンドル URI をアドバタイズして、この機能を知らないユーザーを助けたいと考えるかもしれません。

この機能に必要な唯一のことは、サーバーが1つ以上のバンドル URI をアドバタイズできることです。このアドバタイズは、バンドル URI を検出するための新しいプロトコル v2 機能の形式を取ります。

クライアントは、オプションとして任意のバンドル URI を選択するか、探索的なチェックによって最高のパフォーマンスを持つ URI を選択できます。複数の URI を持つことが、サーバーサイドインフラストラクチャを通じて地理的に分散された単一の URI よりも優れているかどうかは、バンドルプロバイダーが決定します。

バンドル URI の主な必要性は、クローンを高速化することです。Git クライアントは以下のフローに従ってバンドル URI と対話します

クローン中にすべてのバンドルが必要になると予想され、bundle.<uri>.creationToken などのヒューリスティックを使用して、バンドルを時系列順または並行してダウンロードできることに注意してください。

特定のバンドル URI が bundle.heuristic 値を持つバンドルリストである場合、クライアントはその URI を選択されたバンドル URI として保存することを選択できます。その後、クライアントは、後続の git fetch 呼び出し中にその URI に直接移動できます。

バンドル URI をダウンロードする際、クライアントはコンテンツ全体をダウンロードすることにコミットする前に、最初のコンテンツを検査することを選択できます。これにより、URI がバンドルリストかバンドルかを判断するのに十分な情報が得られる場合があります。バンドルの場合、クライアントはバンドルヘッダーを検査して、アドバタイズされたすべての先端がすでにクライアントリポジトリに存在するかどうかを判断し、残りのダウンロードをキャンセルすることができます。

クライアントが新しいデータをフェッチするとき、オリジンリモートからフェッチする前にバンドルサーバーからフェッチすることを決定できます。これはコマンドラインオプションを介して行うこともできますが、クローン中に指定されたような設定値を使用する方がより有用である可能性があります。

フェッチ操作は、バンドルリストからバンドルをダウンロードするために同じ手順に従います（ただし、ここでは並列ダウンロードは望ましくありません）。薄いバンドル内のすべての前提条件となるコミット OID がすでにオブジェクトデータベースにある場合に、プロセスが終了すると予想されます。

creationToken ヒューリスティックを使用する場合、クライアントは、バンドルの作成トークンが保存された作成トークンよりも大きくない場合、バンドルのダウンロードを回避できます。新しいバンドルをフェッチした後、Git はこのローカルの作成トークンを更新します。

バンドルプロバイダーがヒューリスティックを提供しない場合、クライアントは、バンドルチップがすでにクライアントリポジトリに存在する場合に備えて、完全なバンドルデータをダウンロードする前にバンドルヘッダーを検査することを試みるべきです。

Git クライアントが、バンドル URI またはその場所で見つかったバンドルリストに従って情報をダウンロードしている最中に予期せぬものを検出した場合、Git はそのデータを無視し、バンドル URI が与えられなかったかのように続行できます。リモートの Git サーバーが究極の真実の情報源であり、バンドル URI ではありません。

以下に、いくつかのエラー条件の例を示します

また、無駄と見なされる可能性があるが、エラー条件ではない状況もあります

バンドル URI 機能は、バンドルプロバイダーがオブジェクトデータを整理したいさまざまな方法に対して柔軟であるように意図的に設計されています。ただし、プロバイダーがその基盤から開始できるように、完全な組織モデルをここに記述することは役立つでしょう。

この組織例は、GVFS キャッシュサーバー（このドキュメントの末尾近くのセクションを参照）によって使用されているものを簡素化したモデルであり、Git 以外の追加ソフトウェアを使用しているものの、非常に大規模なリポジトリのクローンとフェッチを高速化するのに役立っています。

バンドルプロバイダーは複数の地理的地域にサーバーをデプロイします。各サーバーは独自のバンドルセットを管理します。サーバーは多数の Git リポジトリを追跡できますが、パターンに基づいてそれぞれにバンドルリストを提供します。たとえば、https://<domain>/<org>/<repo> でリポジトリをミラーリングする場合、バンドルサーバーは https://<server-url>/<domain>/<org>/<repo> でバンドルリストを利用可能にできます。オリジン Git サーバーは、これらのすべてのサーバーを「any」モードでリストできます。

この「リストのリスト」は静的であり、バンドルサーバーが追加または削除された場合にのみ変更されます。

各バンドルサーバーは独自のバンドルセットを管理します。最初のバンドルリストには、オリジンサーバーからリポジトリをクローンして受信したすべてのオブジェクトを含む単一のバンドルのみが含まれています。リストは creationToken ヒューリスティックを使用し、バンドルの creationToken はサーバーのタイムスタンプに基づいて作成されます。

バンドルサーバーは、1日1回など、バンドルリストの定期的な更新を実行します。このタスク中に、サーバーはオリジンサーバーから最新のコンテンツをフェッチし、最新のオリジン参照から到達可能であるが、以前に計算されたバンドルに含まれていないオブジェクトを含むバンドルを生成します。このバンドルはリストに追加され、creationToken が以前の最大 creationToken よりも厳密に大きくなるように注意が払われます。

バンドルリストが大きくなりすぎた場合、たとえば30個を超えるバンドルになった場合、最も古い「N 引く30」個のバンドルが単一のバンドルに結合されます。このバンドルの creationToken は、結合されたバンドルの中で最大の creationToken と等しくなります。

ここにバンドルリストの例を示しますが、これは2つの日次バンドルのみで、30個の完全なリストではありません

オリジンサーバーで到達不能になってもオブジェクトデータを永久に保存および提供するのを避けるために、このバンドルマージはより慎重に行うことができます。古いバンドルの絶対的な結合を行う代わりに、新しいバンドルを見て、必要なコミットがすべてこの結合されたバンドル（または新しいバンドルの別のもの）で利用可能であることを確認することによってバンドルを作成できます。これにより、この期間に新しいコミットによって使用されていないオブジェクトデータを「期限切れ」にすることができます。そのデータは、後のプッシュによって再導入される可能性があります。

このデータ構成の意図には2つの主要な目標があります。第一に、リポジトリの初期クローンは、より近いソースから事前に計算されたオブジェクトデータをダウンロードすることで高速化されます。第二に、git fetch コマンドは、特にクライアントが数日間フェッチしていない場合に高速化されます。しかし、クライアントが30日間フェッチしない場合、バンドルリストの構成により大量のオブジェクトデータが再ダウンロードされることになります。

頻繁にフェッチするユーザーにとってこの構成をより有用にする1つの方法は、バンドルの作成頻度を増やすことです。たとえば、バンドルを毎時作成し、その後1日1回それらの「時間ごと」のバンドルを「日次」バンドルにマージすることができます。日次バンドルは30日後に最も古いバンドルにマージされます。

このリポジトリのクライアントがブロブなしパーシャルクローンを使用する予定がある場合、このバンドル戦略を blob:none フィルターで繰り返すことが推奨されます。このブロブなしバンドルのリストは、完全なバンドルと同じリストに留まりますが、2つのグループを分離するために bundle.<id>.filter キーを使用します。非常に大規模なリポジトリの場合、バンドルプロバイダーはブロブなしバンドルをのみ提供したいと考えるかもしれません。

この設計ドキュメントは、言及されたすべてのクライアント機能をいくつかのパッチシリーズにわたって実装することを目標とした、将来的なドキュメントとして単独で提出されています。これらの機能を提出するための潜在的なアウトラインは以下の通りです

これらの機能がレビューされるにつれて、この計画は更新される可能性があります。また、この機能が成熟し、実際のシナリオで使用されるようになるにつれて、新しい設計が発見され、実装されることも期待しています。

Git プロトコルにはすでに、クライアント要求に応答する際に、Git サーバーがパックファイル応答とともに一連の URL をリストできる機能があります。クライアントはその後、応答を完全に理解するために、それらの場所にあるパックファイルをダウンロードすることが期待されます。

このメカニズムは Gerrit サーバー（JGit で実装）によって使用されており、CPU 負荷の軽減とクローンのユーザーパフォーマンス向上に効果的でした。

このメカニズムの大きな欠点は、オリジンサーバーがそれらのパックファイルに何が含まれているかを正確に知っている必要があり、サーバーが応答した後もパックファイルが一定期間ユーザーに利用可能である必要があることです。オリジンとパックファイルデータのこの結合は管理が困難です。

さらに、この実装をフェッチで動作させることは非常に困難です。

GVFS プロトコル [2] は、Git のパーシャルクローンが作成される前に Git プロジェクトとは独立して設計された一連の HTTP エンドポイントです。このプロトコルの1つの機能は、「キャッシュサーバー」という概念です。これはビルドマシンや開発者オフィスに併置でき、中央サーバーを過負荷にすることなく Git データを転送できます。

VFS for Git が有名にしたエンドポイントは、GET /gvfs/objects/{oid} エンドポイントであり、これによりオブジェクトをオンデマンドでダウンロードできます。これは、その製品のファイルシステム仮想化の重要な要素です。

しかし、より微妙なニーズは、GET /gvfs/prefetch?lastPackTimestamp=<t> エンドポイントです。オプションのタイムスタンプが与えられると、キャッシュサーバーは、その時間間隔で導入されたコミットとツリーを含む、事前に計算されたパックファイルのリストで応答します。

キャッシュサーバーは、以下の戦略を使用してこれらの「プリフェッチ」パックファイルを計算します

ユーザーがキャッシュサーバーを持つリポジトリに対して gvfs clone または scalar clone を実行すると、クライアントはすべてのプリフェッチパックファイル（最大でコミットとツリーのみをダウンロードする 24 + 30 + 1 個のパックファイル）を要求します。その後、クライアントはオリジンサーバーに参照を要求し、その先端参照をチェックアウトしようとします。（そのコミットがすでにプリフェッチパックファイルになかった場合に、特定のコミットから到達可能なすべてのツリーを取得するのに役立つ追加のエンドポイントがあります。）

git fetch の際、フックは以前にダウンロードされたプリフェッチパックファイルからの最新のタイムスタンプを使用してプリフェッチエンドポイントを要求します。より新しいタイムスタンプを持つパックファイルのリストのみがダウンロードされます。ほとんどのユーザーは毎時フェッチするため、最大で1つの毎時プリフェッチパックを取得します。マシンがオフになっていた、または30日以上フェッチしていなかったユーザーは、すべてのプリフェッチパックファイルを再ダウンロードする可能性があります。これは稀なケースです。

クライアントが常に参照アドバタイズのためにオリジンサーバーに接続するため、参照はプリフェッチされたパックデータよりも頻繁に「先行」していることに注意することが重要です。不足しているオブジェクトは、git checkout や git log などのコマンドで必要になったときに、GET gvfs/objects/{oid} リクエストを使用してオンデマンドでダウンロードされます。一部の Git の最適化は、これらのオンデマンドダウンロードが過度に積極的になる原因となるチェックを無効にします。

[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/ バンドル URI 機能に関する以前の RFC。

[2] https://github.com/microsoft/VFSForGit/blob/master/Protocol.md GVFS プロトコル