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 機能により、サーバーは、クライアントの wanted セットと client’s 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 がないと、クライアントは c-b-a チェーンを S-R-Q と交互に送信していました。

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

この機能は、スマート HTTP プロトコルでのみ使用すべきです (SHOULD)。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 機能で応答することにより、独自のエージェント文字列を返すことができます (ただし、サーバーが agent 機能を言及しなかった場合は、そうしてはなりません (MUST NOT))。X および Y 文字列には、スペースを除く任意の印字可能な ASCII 文字 (つまり、バイト範囲 32 < x < 127) を含めることができ、通常は「package/version」の形式 (例: 「git/1.8.3.1」) です。エージェント文字列は、統計およびデバッグ目的でのみ情報提供であり、特定の機能の有無をプログラムで想定するために使用してはなりません (MUST NOT)。

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

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

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

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

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

クライアントは、この機能からのパラメータを使用して、リポジトリのクローン作成時に適切な初期ブランチを選択してもよいです (MAY)。

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

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

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

サーバーが 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 サーバーは、署名されたプッシュ証明書を受け入れることをいとわず、プッシュ証明書に を含めるように要求します。send-pack クライアントは、receive-pack サーバーがこの機能をアドバタイズしない限り、push-cert パケットを送信してはなりません (MUST NOT)。

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

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

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

git[1]スイートの一部