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

サーバーは、このドキュメントで定義されているすべての機能をサポートすべきです (SHOULD)。

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

クライアントは、その後、有効にしたい機能のスペース区切りのリストを送信します。クライアントは、サーバーがサポートしていると宣言していない機能を要求してはなりません (MUST NOT)。

サーバーは、理解できない機能が送信された場合、診断して中断しなければなりません (MUST)。サーバーは、クライアントが要求し、サーバーが宣伝した機能を無視してはなりません (MUST NOT)。これらの規則の結果として、サーバーは理解できない機能を宣伝してはなりません (MUST NOT)。

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

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

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

たとえば、以下の図のように、クライアントが大文字でサーバーが持っていないコミットを持ち、サーバーが小文字でクライアントが持っていないコミットを持っているとします。

クライアントが x,y を望み、F,S を持っていると宣言することから始めた場合、サーバーは 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] の「Packfile Negotiation」セクションを参照してください。

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

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

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

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

一方、receive-pack はデフォルトでシンパックを処理できると想定されていますが、no-thin 機能を宣伝することでクライアントにその機能を使用しないよう求めることができます。サーバーが no-thin 機能を宣伝する場合、クライアントはシンパックを送信してはなりません (MUST NOT)。

この非対称性の理由は歴史的なものです。receive-pack プログラムはシンパックの発明後に登場したため、歴史的に receive-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」のいずれか一方のみを送信しなければなりません (MUST)。クライアントが両方を要求した場合、サーバーはそれをエラーとして診断しなければなりません (MUST)。

サーバーは、obj-id ではなくパック内の位置でベースを参照するデルタを持つ PACKv2 を送信でき、クライアントはそれを理解できます。つまり、パックファイル内で OBJ_OFS_DELTA (タイプ6としても知られる) を送受信できます。

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

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

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

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

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

サーバーは、HEAD シンボリック参照が送信される参照の1つである場合、この機能を含めるべきです (SHOULD)。

クライアントは、リポジトリをクローンする際に、この機能のパラメーターを使用して適切な初期ブランチを選択する場合があります (MAY)。

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

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

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

クライアントがこの機能を要求した場合、「deepen」コマンドのセマンティクスが変更されます。「depth」引数は、リモート参照からの深さではなく、現在のシャロー境界からの深さとなります。

クライアントは「git clone -q」などと同様に起動され、サイドバンド2を望んでいません。基本的には、クライアントは「サイドバンドでストリーム2を受信したくないので、送らないでください。もし送ったとしても、私はそれを捨てます」と言っています。しかし、サイドバンドチャネル3はエラー応答のためにまだ使用されます。

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

クライアントは、サーバーがこの機能を宣伝している場合、要求にハードコーディングして常に include-tag を送信する場合があります (MAY)。クライアントが include-tag を要求するかどうかの決定は、サーバーが refs/tags/* 名前空間にオブジェクトを宣伝しているかどうかに関わらず、タグデータに対するクライアントの要望のみに関係します。

サーバーは、参照オブジェクトがパックされており、クライアントが include-tags を要求している場合、タグをパックしなければなりません (MUST)。

クライアントは、サーバーが include-tag を無視し、実際にパック内にタグを送信しなかった場合に備えなければなりません (MUST)。そのような場合、クライアントは、include-tag が提供するはずだったタグを取得するために、後続のフェッチを発行すべきです (SHOULD)。

サーバーは、サポートしている場合、タグが利用可能であるかどうかにかかわらず、include-tag を送信すべきです (SHOULD)。

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

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

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

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

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

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

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 パケットを送信してはなりません (MUST NOT)。

upload-pack サーバーが filter 機能を宣伝する場合、fetch-pack は部分的なクローンまたは部分的なフェッチを要求し、サーバーがパックファイルから様々なオブジェクトを除外するよう要求するために「filter」コマンドを送信する場合があります。

サーバーは、複数のリクエスト間でこのプロセスを識別するために使用できるセッションIDを宣伝する場合があります。クライアントも独自のセッションIDをサーバーに宣伝する場合があります。

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

git[1] スイートの一部