gitprotocol-capabilities - プロトコル v0 および v1 の機能

サーバーは、このドキュメントで定義されているすべての機能をサポートする必要があります。

receive-pack と upload-pack のどちらかの最初のサーバー応答の最初の行では、最初の参照の後に NUL バイトが続き、次にスペースで区切られたサーバー機能のリストが続きます。これにより、サーバーはクライアントに対してサポートできる機能とサポートできない機能を宣言できます。

クライアントは、有効にする必要のある機能のスペース区切りのリストを送信します。クライアントは、サーバーがサポートすると言わなかった機能を要求してはなりません。

サーバーは、理解できない機能が送信された場合は診断して中止する必要があります。サーバーは、クライアントが要求し、サーバーがアドバタイズした機能を無視してはなりません。これらの規則の結果として、サーバーは理解できない機能をアドバタイズしてはなりません。

atomic、report-status、report-status-v2、delete-refs、quiet、および push-cert 機能は、receive-pack（サーバーへのプッシュ）プロセスによって送信および認識されます。

ofs-delta および side-band-64k 機能は、upload-pack と receive-pack の両方のプロトコルによって送信および認識されます。agent および session-id 機能は、両方のプロトコルでオプションで送信できます。

他のすべての機能は、upload-pack（サーバーからのフェッチ）プロセスでのみ認識されます。

multi_ack 機能を使用すると、サーバーはクライアントの want とクライアントの have セットの間で共通のベースとして使用できるコミットを見つけるとすぐに、「ACK obj-id continue」を返すことができます。

これを早期に送信することで、サーバーはクライアントがクライアントのリポジトリ履歴の特定のブランチをさらにたどるのを防ぐことができます。サーバーが DAG を完全にカットするか、クライアントが「done」と言うまで、クライアントは他のブランチをたどり、それらの have 行を送信する必要がある場合があります。

multi_ack がない場合、クライアントは、サーバーが共通のベースを見つけるまで、--date-order で have 行を送信します。つまり、クライアントは、サーバーがまだ共通のベースを見つけていない別のブランチと時間的に重複しているため、サーバーによって共通であることがすでに知られている have 行を送信することになります。

たとえば、クライアントにはサーバーにない大文字のコミットがあり、サーバーにはクライアントにない小文字のコミットがあるとします。次の図のように

クライアントが x、y を必要とし、最初に F、S を have すると言った場合、サーバーは F、S が何であるかを知りません。最終的にクライアントが「have d」と言うと、サーバーは「ACK d continue」を送信して、クライアントにその行をたどるのを停止するように知らせます（したがって、c-b-a を送信しないでください）。ただし、まだ完了していません。x のベースが必要です。クライアントは S-R-Q で進み続け、a に到達すると、サーバーには明確なベースがあり、すべてが終了します。

multi_ack がない場合、クライアントは S-R-Q とインターリーブして、とにかくその c-b-a チェーンを送信したでしょう。

これは multi_ack の拡張で、クライアントがサーバーのメモリ内の状態をよりよく理解できるようにします。詳細については、gitprotocol-pack[5] の「パックファイルのネゴシエーション」のセクションを参照してください。

この機能は、スマート HTTP プロトコルでのみ使用する必要があります。multi_ack_detailed と no-done の両方が存在する場合、送信者は最初の「ACK obj-id ready」メッセージの後にパックをすぐに送信できます。

スマート HTTP プロトコルで no-done がない場合、サーバーセッションは終了し、クライアントはサーバーがパックを送信する前に「done」を送信するために別のトリップを行う必要があります。no-done は最後のラウンドを削除し、これによりレイテンシをわずかに短縮します。

thin pack は、パックに含まれていない（ただし、受信側には存在することがわかっている）ベースオブジェクトを参照するデルタを持つパックです。これにより、ネットワークトラフィックを大幅に削減できますが、受信側は不足しているベースをパックに追加して、これらのパックを「厚く」する方法を知っている必要があります。

upload-pack サーバーは、薄いパックを生成して送信できる場合、thin-pack をアドバタイズします。クライアントは、薄いパックを「厚く」する方法を理解している場合、thin-pack 機能を要求し、そのようなパックを受信できることをサーバーに通知します。クライアントは、薄いパックを自己完結型パックに変換できない場合は、thin-pack 機能を要求してはなりません。

一方、receive-pack はデフォルトで thin pack を処理できると想定されていますが、no-thin 機能をアドバタイズすることにより、クライアントにこの機能を使用しないように要求できます。サーバーが no-thin 機能をアドバタイズする場合、クライアントは thin pack を送信してはなりません。

この非対称性の理由は歴史的なものです。receive-pack プログラムは thin pack の発明後まで存在しなかったため、歴史的に receive-pack の参照実装は常に thin pack を理解していました。後で no-thin を追加することで、receive-pack は下位互換性を維持しながら機能を無効にすることができました。

この機能は、サーバーが多重化された進捗レポートとエラー情報をパックファイル自体とインターリーブして送信でき、クライアントがそれを理解できることを意味します。

これらの 2 つのオプションは相互に排他的です。最新のクライアントは常に side-band-64k を優先します。

どちらのモードも、パックファイルデータが、side_band の場合は最大 1000 バイト、side_band_64k の場合は 65520 バイトまでのパケットに分割されてストリーミングされることを示します。各パケットは、パケット内のデータの量を示す先頭の 4 バイトの pkt-line の長さ、それに続く 1 バイトのストリームコード、および実際のデータで構成されます。

ストリームコードは次のいずれかになります

「side-band-64k」機能は、はるかに大きなパケットを処理できる新しいクライアントが、実際にはほぼいっぱいに詰め込まれたパケットを要求できるようにするための方法として登場し、古いクライアントとの下位互換性を維持しています。

さらに、side-band とその最大 1000 バイトのメッセージでは、実際には 999 バイトのペイロードと 1 バイトのストリームコードです。side-band-64k では、同じように、最大 65519 バイトのデータと 1 バイトのストリームコードがあります。

クライアントは、「side-band」と「side-band-64k」のいずれか 1 つのみを送信する必要があります。クライアントが両方を要求した場合、サーバーはそれをエラーとして診断する必要があります。

サーバーは、オブジェクト ID ではなくパック内の位置によってベースを参照するデルタを持つ PACKv2 を送信でき、クライアントはそれを理解できます。つまり、パックファイル内で OBJ_OFS_DELTA（タイプ 6 とも呼ばれます）を送信/読み取ることができます。

サーバーは、サーバーがバージョン X を実行していることをクライアントに通知するために、オプションで agent=X という形式の機能を送信できます。クライアントは、agent=Y 機能で応答することで、独自の agent 文字列をオプションで返すことができます（ただし、サーバーが agent 機能に言及しなかった場合はそうしてはなりません）。X および Y 文字列には、スペースを除く印刷可能な ASCII 文字（つまり、バイト範囲 32 < x < 127）を含めることができ、通常は「package/version」（例：「git/1.8.3.1」）の形式です。agent 文字列は、統計とデバッグを目的とした純粋な情報であり、特定の機能の有無をプログラムで想定するために使用してはなりません。

この機能は、ハッシュアルゴリズムを引数として受け取り、サーバーが指定されたハッシュアルゴリズムをサポートしていることを示します。複数回送信できます。その場合、最初に指定されたものが、ref アドバタイズで使用されるものです。

クライアントによって提供された場合、これは、クライアントが指定されたハッシュアルゴリズムを使用して通信することを意図していることを示します。提供されたアルゴリズムは、サーバーがサポートしているものである必要があります。

この機能が提供されない場合、サポートされている唯一のアルゴリズムは SHA-1 であると想定されます。

このパラメータ化された機能は、どのシンボリック ref がどの ref を指しているかをレシーバーに通知するために使用されます。たとえば、「symref=HEAD:refs/heads/master」は、HEAD が master を指していることをレシーバーに通知します。この機能は、複数のシンボリック ref を表すために繰り返すことができます。

サーバーは、送信される ref の 1 つである場合は、HEAD シンボリック ref に対してこの機能を含める必要があります。

クライアントは、この機能のパラメータを使用して、リポジトリをクローンするときに適切な初期ブランチを選択できます。

この機能は、「deepen」、「shallow」、および「unshallow」コマンドを fetch-pack/upload-pack プロトコルに追加し、クライアントが shallow クローンを要求できるようにします。

この機能は、fetch-pack/upload-pack プロトコルに「deepen-since」コマンドを追加し、クライアントが深さではなく特定の時間でカットされた shallow クローンを要求できるようにします。内部的には、サーバー側で「rev-list --max-age=<タイムスタンプ>」を実行することと同じです。「deepen-since」は「deepen」と一緒に使用することはできません。

この機能は、fetch-pack/upload-pack プロトコルに「deepen-not」コマンドを追加し、クライアントが深さではなく特定のリビジョンでカットされた shallow クローンを要求できるようにします。内部的には、サーバー側で「rev-list --not <rev>」を実行することと同じです。「deepen-not」は「deepen」と一緒に使用することはできませんが、「deepen-since」と一緒に使用することはできます。

クライアントによってこの機能が要求された場合、「deepen」コマンドのセマンティクスが変更されます。「depth」引数は、リモート ref からの深さではなく、現在の shallow 境界からの深さです。

クライアントは「git clone -q」のようなコマンドで起動されており、サイドバンド2を必要としません。基本的にクライアントは「サイドバンドのストリーム2を受信したくないので、送信しないでください。もし送信しても、私はそれを破棄します」と言っています。しかし、サイドバンドチャネル3はエラー応答のために引き続き使用されます。

include-tag 機能は、オブジェクトが指すアノテーション付きタグを送信する場合に使用します。オブジェクトをクライアントにパックし、タグオブジェクトがそのオブジェクトを正確に指している場合、タグオブジェクトもパックします。一般的に、これによりクライアントは、ブランチをフェッチする際に、1つのネットワーク接続ですべての新しいアノテーション付きタグを取得できます。

クライアントは、サーバーがこの機能をアナウンスする場合、常にinclude-tagを送信することがあります。クライアントがinclude-tagを要求するかどうかの決定は、サーバーがrefs/tags/*名前空間でオブジェクトをアナウンスしたかどうかに関わらず、タグデータに対するクライアントの要望のみに関係します。

サーバーは、参照先がパックされており、クライアントがinclude-tagsを要求している場合、タグをパックする必要があります。

クライアントは、サーバーがinclude-tagを無視し、実際にはパックにタグを送信していない場合に備える必要があります。このような場合、クライアントはinclude-tagがクライアントに提供していたであろうタグを取得するために、後続のフェッチを発行する必要があります。

サーバーは、タグが利用可能かどうかに関係なく、サポートしていればinclude-tagを送信する必要があります。

receive-packプロセスは、report-status 機能を受信できます。これは、クライアントがパックファイルのアップロードと参照更新後の結果のレポートを求めていることを示します。プッシュクライアントがこの機能を要求した場合、サーバーは、パックファイルの解凍が成功したかどうか、および各参照が正常に更新されたかどうかを応答します。いずれかが成功しなかった場合は、エラーメッセージを返します。メッセージの例については、gitprotocol-pack[5]を参照してください。

機能report-status-v2 は、 "proc-receive" フックによって書き換えられた参照をサポートするために、新しい "option" ディレクティブを追加することで、機能report-status を拡張します。"proc-receive" フックは、異なる名前、新しいoid、および古いoidで参照を作成または更新する可能性のある疑似参照のコマンドを処理できます。一方、機能report-status はそのような場合に対応できません。詳細については、gitprotocol-pack[5]を参照してください。

サーバーがdelete-refs 機能を返した場合、それは参照更新のターゲット値としてゼロID値を受け入れることができることを意味します。これはクライアントによって返送されるものではなく、単にゼロID値を送信して参照を削除できることをクライアントに通知するものです。

receive-packサーバーがquiet 機能をアナウンスした場合、受信したパックを処理する際に表示される可能性のある、人間が読める進捗出力を抑制することができます。send-packクライアントは、ローカルの進捗レポートも抑制されている場合（例えば、push -q を介した場合、またはstderrがttyに送られない場合）、サーバー側の進捗レポートを抑制するためにquiet 機能で応答する必要があります。

サーバーがatomic 機能を送信した場合、アトミックプッシュを受け入れることができます。プッシュクライアントがこの機能を要求した場合、サーバーは1つのアトミックトランザクションで参照を更新します。すべての参照が更新されるか、どれも更新されません。

サーバーがpush-options 機能を送信した場合、更新コマンドが送信された後、パックファイルがストリーミングされる前にプッシュオプションを受け入れることができます。プッシュクライアントがこの機能を要求した場合、サーバーはこのプッシュリクエストを処理するプリおよびポスト受信フックにオプションを渡します。

upload-packサーバーがこの機能をアナウンスした場合、fetch-packは、サーバーには存在するが、upload-packによってアナウンスされていないオブジェクト名を持つ "want" 行を送信できます。歴史的な理由から、この機能の名前には "sha1" が含まれています。オブジェクト名は、常にobject-format 機能を通じてネゴシエートされたオブジェクト形式を使用して与えられます。

upload-packサーバーがこの機能をアナウンスした場合、fetch-packは、サーバーには存在するが、upload-packによってアナウンスされていないオブジェクト名を持つ "want" 行を送信できます。歴史的な理由から、この機能の名前には "sha1" が含まれています。オブジェクト名は、常にobject-format 機能を通じてネゴシエートされたオブジェクト形式を使用して与えられます。

この機能をアナウンスするreceive-packサーバーは、署名付きのプッシュ証明書を受け入れる意思があり、プッシュ証明書に<nonce>を含めるように要求します。send-packクライアントは、receive-packサーバーがこの機能をアナウンスしない限り、push-certパケットを送信してはなりません。

upload-packサーバーがfilter 機能をアナウンスした場合、fetch-packは "filter" コマンドを送信して、部分的なクローンまたは部分的なフェッチを要求し、サーバーがパックファイルからさまざまなオブジェクトを省略するように要求できます。

サーバーは、複数のリクエストにわたってこのプロセスを識別するために使用できるセッションIDをアナウンスできます。クライアントは、独自のセッションIDをサーバーにアナウンスすることもできます。

セッションIDは、特定のプロセスに対して一意である必要があります。これらはパケットライン内に収まり、印刷不能な文字や空白文字を含んではなりません。現在の実装ではtrace2セッションID（詳細についてはapi-trace2を参照）を使用していますが、これは変更される可能性があり、セッションIDのユーザーはこの事実に基づいてはなりません。

git[1]スイートの一部