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

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

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

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

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

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

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

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

残りのキーには、各利用可能なバンドルに対してサーバーによって指定された名前である<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回など、バンドルリストの定期的な更新を実行します。このタスク中に、サーバーはオリジンサーバーから最新のコンテンツをフェッチし、最新のオリジンリファレンスから到達可能であるが、以前に計算されたバンドルに含まれていないオブジェクトを含むバンドルを生成します。このバンドルはリストに追加され、creationTokenが以前の最大creationTokenよりも厳密に大きくなるように注意されます。

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

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

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

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

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

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

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

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

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時間ごとにフェッチするため、最大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プロトコル