バンドル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設定形式を使用したバンドルリストの例を次に示します

この例では、 `bundle.mode = all` と `bundle.<id>.creationToken` ヒューリスティックを使用しています。また、 `bundle.<id>.filter` オプションを使用して、2つの並列バンドルセットを提示します。1つは完全なクローン用、もう1つはブロブレスの部分クローン用です。

このバンドルリストが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キャッシュサーバー（このドキュメントの最後付近のセクションを参照）で使用されているものの簡略化されたモデルです。GVFSキャッシュサーバーは、Git外部の追加ソフトウェアを使用していますが、非常に大きなリポジトリのクローン作成とフェッチの高速化に役立っています。

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

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

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

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

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

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

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

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

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

このリポジトリのクライアントがブロブレスの部分クローンを使用することが想定される場合、`blob:none` フィルターを使用してこのバンドル戦略を繰り返すことをお勧めします。このブロブレスバンドルのリストは、完全なバンドルと同じリストに保持されますが、`bundle.<id>.filter` キーを使用して2つのグループを区別します。非常に大きなリポジトリの場合、バンドルプロバイダーは *ブロブレスバンドルのみ* を提供することを希望する場合があります。

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

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

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プロトコル