gitprotocol-v2(5) Manual Page

git:// 転送(transport)を使用する場合、 追加のパラメーターとして "version=2" を送信することにより、 プロトコルv2の使用を要求できます:

ssh:// 転送または file:// 転送のどちらかを使用する場合、 GIT_PROTOCOL 環境変数を明示的に設定して version=2 を含める必要があります。 この環境変数が渡されるようにサーバーを構成する必要がある場合があります。

http:// 転送または https:// 転送を使用する場合、 クライアントは gitprotocol-http(5) で説明されているように「smart」な info/refs リクエストを作成し、 Git-Protocol ヘッダー内で「version=2」を指定してv2を使用するように要求します。

v2サーバーは以下のように応答します:

その後の要求は、サービス $GIT_URL/git-upload-pack に対して直接行われます。(これはgit-receive-packでも同じように機能します)。

--http-backend-info-refs オプションを使用して git-upload-pack(1) を実行します。

The server may need to be configured to pass this header’s contents via the GIT_PROTOCOL variable. See the discussion in git-http-backend(1).

The server can advertise the agent capability with a value X (in the form agent=X) to notify the client that the server is running version X. The client may optionally send its own agent string by including the agent capability with a value Y (in the form agent=Y) in its request to the server (but it MUST NOT do so if the server did not advertise the agent capability). The X and Y strings may contain any printable ASCII characters except space (i.e., the byte range 33 ⇐ x ⇐ 126), and are typically of the form "package/version-os" (e.g., "git/1.8.3.1-Linux") where os is the operating system name (e.g., "Linux"). X and Y can be configured using the GIT_USER_AGENT environment variable and it takes priority. The os is retrieved using the sysname field of the uname(2) system call or its equivalent. The agent strings are purely informative for statistics and debugging purposes, and MUST NOT be used to programmatically assume the presence or absence of particular features.

ls-refs は、v2で参照広告を要求するために使用されるコマンドです。現在の参照広告とは異なり、ls-refsは、サーバーから送信される参照を制限するために使用できる引数を取ります。

基本コマンドでサポートされていない追加の機能は、 機能広告のコマンドの値として、 スペースで区切られた機能のリストの形式で広告されます: "<command>=<feature-1> <feature-2>"

ls-refsは以下の引数を取ります:

「unborn」機能が広告される場合、以下の引数をクライアントの要求に含めることができます。

ls-refsの出力は以下のとおりです:

fetch は、v2でパックファイルをフェッチするために使用されるコマンドです。 これは、v1 fetch の修正バージョンと見なすことができ、(ls-refs コマンドがその役割を果たしているため、)参照広告(ref-advertisement)が削除され、メッセージ形式が調整されて冗長性が排除され、将来の拡張機能を簡単に追加できるようになっています。

基本コマンドでサポートされていない追加の機能は、 機能広告のコマンドの値として、 スペースで区切られた機能のリストの形式で広告されます: "<command>=<feature-1> <feature-2>"

fetch リクエストは、以下の引数を取ることができます:

「shallow」機能が広告される場合、以下で説明するように、以下の引数をクライアント要求に含めることができ、サーバーの応答に「shallow-info」セクションを追加する可能性があります。

filter 機能が広告される場合、以下の引数をクライアントの要求に含めることができます:

「ref-in-want」機能が広告される場合、以下で説明するように、以下の引数をクライアントの要求に含めることができ、サーバーの応答に「wanted-refs」セクションを追加する可能性があります。

sideband-all 機能が広告される場合、以下の引数をクライアントの要求に含めることができます:

「packfile-uris」機能が広告される場合、 以下で説明するように、 以下の引数をクライアントの要求に含めることができ、 サーバーの応答に「packfile-uris」セクションを追加する可能性があります。 注意: サーバーに送信可能な「Packfile-uris」行は 1 行だけであることに注意してください。

wait-for-done 機能が広告される場合、以下の引数をクライアントの要求に含めることができます。

fetch の応答は、区切り文字パケット(0001)で区切られたいくつかのセクションに分割され、各セクションはセクションヘッダーで始まります。ほとんどのセクションは、パックファイルが送信されたときにのみ送信されます。

広告されている場合は、サーバー固有のオプションをいくつでもリクエストに含めることができることを示します。これは、リクエストの機能リストセクションで「server-option=<option>」機能行として各オプションを送信することによって行われます。

提供されるオプションには、NULまたはLF文字を含めることはできません。

サーバーは、値 X (object-format=X 形式)を使用して object-format 機能を広告し、サーバーがハッシュアルゴリズムXを使用してオブジェクトを処理できることをクライアントに通知できます。 指定しない場合、サーバーはSHA-1のみを処理すると見なされます。 クライアントがSHA-1以外のハッシュアルゴリズムを使用する場合は、object-formatの文字列を指定する必要があります。

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

セッションIDは、特定のプロセスに固有である必要があります。それらはパケット行内に収まる必要があり、印刷不可能な文字や空白文字を含めることはできません。 現在の実装ではtrace2セッションID(詳細は api-trace2 参照)を使用していますが、これは変更される可能性があるため、セッションIDのユーザーはこの事実に依存しないでください。

object-info は、1つまたは複数のオブジェクトに関する情報を取得するためのコマンドです。 その主な目的は、クライアントがオブジェクトを完全にフェッチすることなく、この情報に基づいて決定を下せるようにすることです。 現在サポートされている情報はオブジェクトサイズのみです。

object-info リクエストは以下の引数を取ります:

object-info の応答は、要求されたオブジェクトIDと関連する要求された情報のリストであり、それぞれが1つのスペースで区切られています。

bundle-uri 機能が広告されている場合、サーバーは bundle-uri コマンドをサポートします。

現在、この機能は値なし(つまり、 bundle-uri=ほげほげ 形式ではありません)で広告されていますが、コマンド全体の拡張機能をサポートするために、将来値が追加される可能性があります。クライアントは不明な機能値を無視し、サポートする bundle-uri 対話を続行しなければなりません。

bundle-uri コマンドは、種(seed)にするためのバンドル・ファイルの URI を取得し、 後続の fetch コマンドに通知するために、 fetch の前に発行されることを目的としています。

クライアントは、他の有効なコマンドの前後に bundle-uri を発行できます。クライアントにとって役立つように、 ls-refs の後でかつ fetch の前に発行されることが期待されますが、対話内のいつでも発行できます。

The server may advertise some promisor remotes it is using or knows about to a client which may want to use them as its promisor remotes, instead of this repository. In this case <pr-info> should be of the form:

where all the field-name and field-value in a given pr-fields are field names and values related to a single promisor remote. A given field-name MUST NOT appear more than once in given pr-fields.

The server MUST advertise at least the "name" and "url" field names along with the associated field values, which are the name of a valid remote and its URL, in each pr-fields. The "name" and "url" fields MUST appear first in each pr-fields, in that order.

After these mandatory fields, the server MAY advertise the following optional fields in any order:

No other fields are defined by the protocol at this time. Field names are case-sensitive and MUST be transmitted exactly as specified above. Clients MUST ignore fields they don’t recognize to allow for future protocol extensions.

For now, the client can only use information transmitted through these fields to decide if it accepts the advertised promisor remote. In the future that information might be used for other purposes though.

Field values MUST be urlencoded.

If the client decides to use one or more promisor remotes the server advertised, it can reply with "promisor-remote=<pr-names>" where <pr-names> should be of the form:

where pr-name is the urlencoded name of a promisor remote the server advertised and the client accepts.

Note that, everywhere in this document, the ; and , characters MUST be encoded if they appear in pr-name or field-value.

If the server doesn’t know any promisor remote that could be good for a client to use, or prefers a client not to use any promisor remote it uses or knows about, it shouldn’t advertise the "promisor-remote" capability at all.

In this case, or if the client doesn’t want to use any promisor remote the server advertised, the client shouldn’t advertise the "promisor-remote" capability at all in its reply.

On the server side, the "promisor.advertise" and "promisor.sendFields" configuration options can be used to control what it advertises. On the client side, the "promisor.acceptFromServer" configuration option can be used to control what it accepts. See the documentation of these configuration options for more information.

Note that in the future it would be nice if the "promisor-remote" protocol capability could be used by the server, when responding to git fetch or git clone, to advertise better-connected remotes that the client can use as promisor remotes, instead of this repository, so that the client can lazily fetch objects from these other better-connected remotes. This would require the server to omit in its response the objects available on the better-connected remotes that the client has accepted. This hasn’t been implemented yet though. So for now this "promisor-remote" capability is useful only when the server advertises some promisor remotes it already uses to borrow objects from.