セットアップと設定
プロジェクトの取得と作成
基本的なスナップショット
ブランチとマージ
プロジェクトの共有と更新
検査と比較
パッチ適用
デバッグ
メール
外部システム
サーバー管理
- 2.49.1 → 2.50.1 変更なし
-
2.49.0
2025-03-14
- 2.48.1 → 2.48.2 変更なし
-
2.48.0
2025-01-10
- 2.47.2 → 2.47.3 変更なし
-
2.47.1
2024-11-25
- 2.45.1 → 2.47.0 変更なし
-
2.45.0
2024-04-29
- 2.44.1 → 2.44.4 変更なし
-
2.44.0
2024-02-23
- 2.43.1 → 2.43.7 変更なし
-
2.43.0
2023-11-20
- 2.40.1 → 2.42.4 変更なし
-
2.40.0
2023-03-12
- 2.38.1 → 2.39.5 変更なし
-
2.38.0
2022-10-02
説明
このドキュメントでは、Git のワイヤプロトコルバージョン 2 の仕様について説明します。プロトコル v2 は、以下の点で v1 を改善します。
-
複数のサービス名ではなく、単一のサービスで複数のコマンドがサポートされる
-
機能がプロトコルの独自のセクションに移動され、NUL バイトの背後に隠されたり、pkt-line のサイズによって制限されることがなくなり、簡単に拡張可能になる
-
NUL バイトの背後に隠されたその他の情報(例:エージェント文字列を機能として、シンボリック参照は ls-refs を使用して要求できる)を分離する
-
参照広告は、明示的に要求されない限り省略される
-
特定の参照を明示的に要求するための ls-refs コマンド
-
HTTP およびステートレス RPC を念頭に置いて設計されています。明確なフラッシュセマンティクスにより、HTTP リモートヘルパーは単にプロキシとして機能できます。
プロトコル v2 では、通信はコマンド指向です。サーバーに最初に接続するときに、機能のリストがアドバタイズされます。これらの機能の一部は、クライアントが実行を要求できるコマンドです。コマンドが完了すると、クライアントは接続を再利用して、他のコマンドの実行を要求できます。
パケットラインフレーミング
すべての通信は、v1 と同様にパケットラインフレーミングを使用して行われます。詳細については、gitprotocol-pack[5] および gitprotocol-common[5] を参照してください。
プロトコル v2 では、これらの特殊なパケットは次のセマンティクスを持ちます。
-
0000 フラッシュパケット (flush-pkt) - メッセージの終わりを示します。
-
0001 区切りパケット (delim-pkt) - メッセージのセクションを区切ります。
-
0002 応答終了パケット (response-end-pkt) - ステートレス接続の応答の終わりを示します。
初期クライアントリクエスト
一般に、クライアントは、使用しているトランスポートのそれぞれのサイドチャネルを介して version=2
を送信することにより、プロトコル v2 を使用するよう要求できます。これにより、必然的に GIT_PROTOCOL
が設定されます。詳細については、gitprotocol-pack[5] および gitprotocol-http[5]、ならびに git.txt
の GIT_PROTOCOL
定義を参照してください。すべての場合において、サーバーからの応答は機能広告です。
Git トランスポート
git:// トランスポートを使用する場合、"version=2" を追加パラメータとして送信することで、プロトコル v2 の使用を要求できます。
003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0
SSH およびファイルトランスポート
ssh:// または file:// トランスポートを使用する場合、GIT_PROTOCOL 環境変数を明示的に "version=2" を含むように設定する必要があります。サーバーは、この環境変数の通過を許可するように構成する必要がある場合があります。
HTTP トランスポート
http:// または https:// トランスポートを使用する場合、クライアントは gitprotocol-http[5] で説明されている "スマート" info/refs リクエストを行い、Git-Protocol
ヘッダーに "version=2" を指定して v2 の使用を要求します。
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 C: Git-Protocol: version=2
v2 サーバーは次のように応答します。
S: 200 OK S: <Some headers> S: ... S: S: 000eversion 2\n S: <capability-advertisement>
その後のリクエストは、サービス $GIT_URL/git-upload-pack
に直接行われます。(これは git-receive-pack でも同様に機能します)。
git-upload-pack[1] の --http-backend-info-refs
オプションを使用します。
サーバーは、このヘッダーの内容を GIT_PROTOCOL
変数経由で渡すように構成する必要がある場合があります。git-http-backend.txt
の説明を参照してください。
機能広告
プロトコルバージョン 2 を使用して通信することを決定したサーバー (クライアントからの要求に基づいて) は、最初の応答でバージョン文字列を送信し、その後に機能の広告を送信することでクライアントに通知します。各機能は、オプションの値を持つキーです。クライアントは、すべての未知のキーを無視する必要があります。未知の値のセマンティクスは、各キーの定義に委ねられます。一部の機能は、クライアントによって実行を要求できるコマンドを記述します。
capability-advertisement = protocol-version capability-list flush-pkt
protocol-version = PKT-LINE("version 2" LF) capability-list = *capability capability = PKT-LINE(key[=value] LF)
key = 1*(ALPHA | DIGIT | "-_") value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;")
コマンドリクエスト
機能広告を受信した後、クライアントは、特定の機能または引数を使用して、目的のコマンドを選択する要求を発行できます。次に、クライアントがコマンド固有のパラメータまたはクエリを提供できるオプションのセクションがあります。一度に要求できるコマンドは1つだけです。
request = empty-request | command-request empty-request = flush-pkt command-request = command capability-list delim-pkt command-args flush-pkt command = PKT-LINE("command=" key LF) command-args = *command-specific-arg
command-specific-args are packet line framed arguments defined by each individual command.
サーバーは、クライアントのリクエストが有効なコマンドと、アドバタイズされた有効な機能で構成されていることを確認します。リクエストが有効な場合、サーバーはコマンドを実行します。サーバーは、応答を発行する前に、クライアントの完全なリクエストを受信するまで待機する必要があります。応答の形式は、実行されるコマンドによって決定されますが、すべての場合において、flush-pkt は応答の終わりを示します。
コマンドが終了し、クライアントがサーバーから完全な応答を受信した後、クライアントは別のコマンドの実行を要求するか、接続を終了することができます。クライアントは、これ以上リクエストが行われないことを示すために、flush-pkt のみで構成される空のリクエストをオプションで送信できます。
機能
機能には2つの異なるタイプがあります。情報伝達やリクエストの動作変更に使用できる通常の機能と、クライアントが実行したいコアアクション(フェッチ、プッシュなど)であるコマンドです。
プロトコルバージョン2は、デフォルトでステートレスです。これは、すべてのコマンドが単一のラウンドでしか持続せず、クライアントがサーバーによって状態が維持されることを示す機能を要求しない限り、サーバー側の観点からはステートレスでなければならないことを意味します。クライアントは、正しく機能するためにサーバー側での状態管理を要求してはなりません。これにより、状態管理を心配することなく、サーバー側でシンプルなラウンドロビン負荷分散が可能になります。
エージェント
サーバーは、agent
機能に値 X
(形式 agent=X
) を付けてアドバタイズすることで、サーバーがバージョン X
で実行されていることをクライアントに通知できます。クライアントは、オプションで、リクエストに agent
機能に値 Y
(形式 agent=Y
) を含めることで、独自のエージェント文字列をサーバーに送信できます(ただし、サーバーがエージェント機能をアドバタイズしなかった場合は、そうしてはなりません)。X
と Y
の文字列には、スペースを除く任意の印刷可能な ASCII 文字 (つまり、バイト範囲 33 ⇐ x ⇐ 126) を含めることができ、通常は "パッケージ/バージョン-OS" の形式 (例: "git/1.8.3.1-Linux") であり、os
はオペレーティングシステム名 (例: "Linux") です。X
と Y
は GIT_USER_AGENT 環境変数を使用して設定でき、こちらが優先されます。os
は uname
(2
) システムコールまたはそれに相当するものの sysname フィールドを使用して取得されます。エージェント文字列は、統計およびデバッグ目的のための純粋に情報提供のみであり、特定の機能の有無をプログラムで仮定するために使用してはなりません。
ls-refs
ls-refs
は、v2 で参照広告を要求するために使用されるコマンドです。現在の参照広告とは異なり、ls-refs は、サーバーから送信される参照を制限するために使用できる引数を取ります。
基本コマンドでサポートされていない追加機能は、機能広告のコマンドの値として、スペース区切りの機能リストの形式で広告されます: "<command>=<feature-1> <feature-2>"
ls-refs は次の引数を取ります。
symrefs In addition to the object pointed by it, show the underlying ref pointed by it when showing a symbolic ref. peel Show peeled tags. ref-prefix <prefix> When specified, only references having a prefix matching one of the provided prefixes are displayed. Multiple instances may be given, in which case references matching any prefix will be shown. Note that this is purely for optimization; a server MAY show refs not matching the prefix if it chooses, and clients should filter the result themselves.
unborn 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができます。
unborn The server will send information about HEAD even if it is a symref pointing to an unborn branch in the form "unborn HEAD symref-target:<target>".
ls-refs の出力は次のとおりです。
output = *ref flush-pkt obj-id-or-unborn = (obj-id | "unborn") ref = PKT-LINE(obj-id-or-unborn SP refname *(SP ref-attribute) LF) ref-attribute = (symref | peeled) symref = "symref-target:" symref-target peeled = "peeled:" obj-id
フェッチ
fetch
は、v2 でパックファイルを取得するために使用されるコマンドです。参照広告が削除され (ls-refs
コマンドがその役割を果たすため)、メッセージ形式が冗長性を排除し、将来の拡張機能を簡単に追加できるように調整された v1 フェッチの修正版と見なすことができます。
基本コマンドでサポートされていない追加機能は、機能広告のコマンドの値として、スペース区切りの機能リストの形式で広告されます: "<command>=<feature-1> <feature-2>"
fetch
リクエストは次の引数を取ることができます。
want <oid> Indicates to the server an object which the client wants to retrieve. Wants can be anything and are not limited to advertised objects.
have <oid> Indicates to the server an object which the client has locally. This allows the server to make a packfile which only contains the objects that the client needs. Multiple 'have' lines can be supplied.
done Indicates to the server that negotiation should terminate (or not even begin if performing a clone) and that the server should use the information supplied in the request to construct the packfile.
thin-pack Request that a thin pack be sent, which is a pack with deltas which reference base objects not contained within the pack (but are known to exist at the receiving end). This can reduce the network traffic significantly, but it requires the receiving end to know how to "thicken" these packs by adding the missing bases to the pack.
no-progress Request that progress information that would normally be sent on side-band channel 2, during the packfile transfer, should not be sent. However, the side-band channel 3 is still used for error responses.
include-tag Request that annotated tags should be sent if the objects they point to are being sent.
ofs-delta Indicate that the client understands PACKv2 with delta referring to its base by position in pack rather than by an oid. That is, they can read OBJ_OFS_DELTA (aka type 6) in a packfile.
shallow 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができ、以下で説明するように、サーバーの応答に shallow-info セクションが追加される可能性があります。
shallow <oid> A client must notify the server of all commits for which it only has shallow copies (meaning that it doesn't have the parents of a commit) by supplying a 'shallow <oid>' line for each such object so that the server is aware of the limitations of the client's history. This is so that the server is aware that the client may not have all objects reachable from such commits.
deepen <depth> Requests that the fetch/clone should be shallow having a commit depth of <depth> relative to the remote side.
deepen-relative Requests that the semantics of the "deepen" command be changed to indicate that the depth requested is relative to the client's current shallow boundary, instead of relative to the requested commits.
deepen-since <timestamp> Requests that the shallow clone/fetch should be cut at a specific time, instead of depth. Internally it's equivalent to doing "git rev-list --max-age=<timestamp>". Cannot be used with "deepen".
deepen-not <rev> Requests that the shallow clone/fetch should be cut at a specific revision specified by '<rev>', instead of a depth. Internally it's equivalent of doing "git rev-list --not <rev>". Cannot be used with "deepen", but can be used with "deepen-since".
filter 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができます。
filter <filter-spec> Request that various objects from the packfile be omitted using one of several filtering techniques. These are intended for use with partial clone and partial fetch operations. See `rev-list` for possible "filter-spec" values. When communicating with other processes, senders SHOULD translate scaled integers (e.g. "1k") into a fully-expanded form (e.g. "1024") to aid interoperability with older receivers that may not understand newly-invented scaling suffixes. However, receivers SHOULD accept the following suffixes: 'k', 'm', and 'g' for 1024, 1048576, and 1073741824, respectively.
ref-in-want 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができ、以下で説明するように、サーバーの応答に wanted-refs セクションが追加される可能性があります。
want-ref <ref> Indicates to the server that the client wants to retrieve a particular ref, where <ref> is the full name of a ref on the server. It is a protocol error to send want-ref for the same ref more than once.
sideband-all 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができます。
sideband-all Instruct the server to send the whole response multiplexed, not just the packfile section. All non-flush and non-delim PKT-LINE in the response (not only in the packfile section) will then start with a byte indicating its sideband (1, 2, or 3), and the server may send "0005\2" (a PKT-LINE of sideband 2 with no payload) as a keepalive packet.
packfile-uris 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができ、以下で説明するように、サーバーの応答に packfile-uris セクションが追加される可能性があります。サーバーに送信できる packfile-uris
行は最大1つであることに注意してください。
packfile-uris <comma-separated-list-of-protocols> Indicates to the server that the client is willing to receive URIs of any of the given protocols in place of objects in the sent packfile. Before performing the connectivity check, the client should download from all given URIs. Currently, the protocols supported are "http" and "https".
wait-for-done 機能が広告されている場合、次の引数をクライアントのリクエストに含めることができます。
wait-for-done Indicates to the server that it should never send "ready", but should wait for the client to say "done" before sending the packfile.
fetch
の応答は、区切りパケット (0001) で区切られたいくつかのセクションに分かれており、各セクションはそのセクションヘッダーで始まります。ほとんどのセクションは、パックファイルが送信される場合にのみ送信されます。
output = acknowledgements flush-pkt | [acknowledgments delim-pkt] [shallow-info delim-pkt] [wanted-refs delim-pkt] [packfile-uris delim-pkt] packfile flush-pkt
acknowledgments = PKT-LINE("acknowledgments" LF) (nak | *ack) (ready) ready = PKT-LINE("ready" LF) nak = PKT-LINE("NAK" LF) ack = PKT-LINE("ACK" SP obj-id LF)
shallow-info = PKT-LINE("shallow-info" LF) *PKT-LINE((shallow | unshallow) LF) shallow = "shallow" SP obj-id unshallow = "unshallow" SP obj-id
wanted-refs = PKT-LINE("wanted-refs" LF) *PKT-LINE(wanted-ref LF) wanted-ref = obj-id SP refname
packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)
packfile = PKT-LINE("packfile" LF) *PKT-LINE(%x01-03 *%x00-ff)
acknowledgments section * If the client determines that it is finished with negotiations by sending a "done" line (thus requiring the server to send a packfile), the acknowledgments sections MUST be omitted from the server's response.
-
常にセクションヘッダー "acknowledgments" で始まります。
-
サーバーは、送信されたオブジェクト ID のいずれも共通ではなかった場合に "NAK" で応答します。
-
サーバーは、送信されたオブジェクト ID のうち共通するすべてのオブジェクト ID に対して "ACK obj-id" で応答します。
-
応答には、"ACK" 行と "NAK" 行の両方を含めることはできません。
-
サーバーは、許容可能な共通のベースを見つけ、パックファイルを作成して送信する準備ができたことを示す "ready" 行で応答します(これは、同じ応答のパックファイルセクションにあります)。
-
サーバーが適切なカットポイントを見つけ、「ready」行を送信することにした場合、サーバーは(最適化として)応答中に送信するはずだった「ACK」行を省略することを決定できます。これは、サーバーがクライアントに送信するオブジェクトをすでに決定しており、それ以上のネゴシエーションが不要であるためです。
shallow-info section * If the client has requested a shallow fetch/clone, a shallow client requests a fetch or the server is shallow then the server's response may include a shallow-info section. The shallow-info section will be included if (due to one of the above conditions) the server needs to inform the client of any shallow boundaries or adjustments to the clients already existing shallow boundaries.
-
常にセクションヘッダー "shallow-info" で始まります。
-
正の深さが要求された場合、サーバーは、要求された深さよりも深くならないコミットのセットを計算します。
-
サーバーは、続くパックファイルで親が送信されない各コミットに対して "shallow obj-id" 行を送信します。
-
サーバーは、クライアントがシャローであることを示した各コミットに対して "unshallow obj-id" 行を送信します。ただし、フェッチの結果(続くパックファイルで親が送信されるため)シャローではなくなったコミットに対しては送信しません。
-
サーバーは、クライアントがリクエストの一部としてシャローであると示していないものについては、「unshallow」行を送信してはなりません。
wanted-refs section * This section is only included if the client has requested a ref using a 'want-ref' line and if a packfile section is also included in the response.
-
常にセクションヘッダー "wanted-refs" で始まります。
-
サーバーは、want-ref 行を使用して要求された各参照に対して参照リスト ("<oid> <refname>") を送信します。
-
サーバーは、want-ref 行を使用して要求されなかった参照を送信してはなりません。
packfile-uris section * This section is only included if the client sent 'packfile-uris' and the server has at least one such URI to send.
-
常にセクションヘッダー "packfile-uris" で始まります。
-
サーバーが送信する各 URI について、パックの内容のハッシュ (git index-pack の出力) とその後に URI を送信します。
-
ハッシュは 40 文字の 16 進数です。Git が新しいハッシュアルゴリズムにアップグレードされた場合、これを更新する必要があるかもしれません。("pack\t" または "keep\t" の後に index-pack が出力するものと一致する必要があります)。
packfile section * This section is only included if the client has sent 'want' lines in its request and either requested that no more negotiation be done by sending 'done' or if the server has decided it has found a sufficient cut point to produce a packfile.
-
常にセクションヘッダー "packfile" で始まります。
-
パックファイルの転送は、セクションヘッダーの直後に始まります。
-
パックファイルのデータ転送は、プロトコルバージョン 1 の side-band-64k 機能と同じセマンティクスを使用して、常に多重化されます。これは、パックファイルデータストリーム中の各パケットが、先行する 4 バイトの pkt-line 長 (pkt-line 形式の典型的) と、それに続く 1 バイトのストリームコード、そして実際のデータで構成されることを意味します。
The stream code can be one of: 1 - pack data 2 - progress messages 3 - fatal error message just before stream aborts
サーバーオプション
アドバタイズされている場合、任意の数のサーバー固有のオプションをリクエストに含めることができることを示します。これは、各オプションをリクエストの capability-list セクションで "server-option=<option>" 機能行として送信することで行われます。
提供されるオプションには、NUL 文字または LF 文字を含めてはなりません。
オブジェクト形式
サーバーは、object-format
機能に値 X
(形式 object-format=X
) を付けてアドバタイズすることで、サーバーがハッシュアルゴリズム X を使用するオブジェクトを処理できることをクライアントに通知できます。指定されていない場合、サーバーは SHA-1 のみを処理すると仮定されます。クライアントが SHA-1 以外のハッシュアルゴリズムを使用したい場合は、そのオブジェクト形式文字列を指定する必要があります。
session-id=<session-id>
サーバーは、複数のリクエストにわたってこのプロセスを識別するために使用できるセッション ID をアドバタイズできます。クライアントは、独自のセッション ID をサーバーにアドバタイズすることもできます。
セッションIDは、特定のプロセスに対して一意である必要があります。パケットライン内に収まり、非印刷文字や空白文字を含んではなりません。現在の実装ではtrace2セッションIDを使用していますが(詳細についてはapi-trace2を参照)、これは変更される可能性があり、セッションIDのユーザーはこの事実に依存すべきではありません。
object-info
object-info
は、1つまたは複数のオブジェクトに関する情報を取得するコマンドです。主な目的は、クライアントがオブジェクトを完全にフェッチすることなく、この情報に基づいて決定を下せるようにすることです。現在サポートされている情報はオブジェクトサイズのみです。
object-info
リクエストは次の引数を取ります。
size Requests size information to be returned for each listed object id.
oid <oid> Indicates to the server an object which the client wants to obtain information for.
object-info
の応答は、要求されたオブジェクト ID と関連する要求された情報のリストであり、それぞれが単一のスペースで区切られています。
output = info flush-pkt
info = PKT-LINE(attrs) LF) *PKT-LINE(obj-info LF)
attrs = attr | attrs SP attrs
attr = "size"
obj-info = obj-id SP obj-size
bundle-uri
bundle-uri 機能がアドバタイズされている場合、サーバーは「bundle-uri」コマンドをサポートします。
この機能は現在、値なしでアドバタイズされています(つまり、「bundle-uri=somevalue」ではありません)。将来、コマンド全体にわたる拡張機能をサポートするために値が追加される可能性があります。クライアントは、未知の機能値を無視し、サポートする「bundle-uri」ダイアログに進む必要があります。
bundle-uri コマンドは、fetch
の前に発行され、バンドルファイル (「シード」するため、および後続の fetch
コマンドに通知するため) への URI を取得することを意図しています (「git-bundle[1]」を参照)。
クライアントは、他の有効なコマンドの前または後に bundle-uri
を発行できます。クライアントにとって有用であるためには、ls-refs
の後に、fetch
の前に発行されることが想定されますが、ダイアログのいつでも発行できます。
bundle-uri について
この機能の目的は、git-clone[1] 中に非常に大きな PACK をフェッチする一般的なケースを、より小さな増分フェッチに変更することで、一般的なケースにおけるサーバーリソースの消費を最適化することです。
また、uploadpack.packObjectsHook
(「git-config[1]」を参照) と組み合わせて、サーバーがより良いキャッシュを実現することも可能になります。
新しいクローンやフェッチは、最近作成された *.bundle ファイルの先端に対する、より予測可能で一般的なネゴシエーションとなるためです。サーバーは、新しいプッシュが来たときに、uploadpack.packObjectsHook
のためにそのようなネゴシエーションの結果を事前に生成することさえできるかもしれません。
サーバーがこれらのバンドルを利用できる1つの方法は、サーバーが、新しいクローンが既知のバンドルをダウンロードし、そのバンドル(またはバンドル)で見つかった参照チップを使用してリポジトリの現在の状態に追いつくと予想することです。
bundle-uri のプロトコル
bundle-uri
リクエストは引数を取らず、上記のように現在機能値をアドバタイズしていません。どちらも将来追加される可能性があります。
クライアントが command=bundle-uri
リクエストを発行すると、応答は <key>=
<value> の値を持つパケットラインとして提供されるキーと値のペアのリストです。各 <key> は、bundle.*
名前空間からの設定キーとして解釈され、バンドルのリストを構築します。これらのキーは、bundle.
<id>.
サブセクションによってグループ化され、特定の <id> に対応する各キーは、その <id> で定義されたバンドルに属性を提供します。これらのキーの具体的な詳細と、Git クライアントがその値をどのように解釈するかについては、git-config[1] を参照してください。
クライアントは、上記の形式に従って行を解析する必要があります。形式に準拠しない行は破棄されるべきです。そのような場合、ユーザーに警告が表示される場合があります。
bundle-uri クライアントとサーバーの期待
- URI の内容
-
アドバタイズされた URI の内容は、次の2種類のいずれかである必要があります。
アドバタイズされた URI には、
git
bundle
verify
が受け入れるバンドルファイルが含まれている場合があります。つまり、クライアントが使用する1つ以上の参照ヒントを含み、標準の「-」プレフィックスで前提条件(もしあれば)を示す必要があり、該当する場合は「object-format」を示す必要があります。アドバタイズされた URI には、代わりに
git
config
--list
が受け入れるプレーンテキストファイル (--file
オプション付き) が含まれる場合があります。このリストのキーと値のペアは、bundle.*
名前空間にあります (git-config[1] を参照)。 - bundle-uri クライアントのエラー回復
-
クライアントは、何よりもエラー時に gracefully degrade (段階的に機能を低下させる) する必要があります。そのエラーが、バンドル URI に不良なデータや欠落したデータがあるためであろうと、クライアントがバンドルヘッダーとその前提条件の関係を理解して完全に解析するにはあまりにも単純すぎるためであろうと、あるいは他の理由であろうと。
サーバーオペレーターは、たとえば CDN がダウンした場合でも、クローンやフェッチが致命的な障害に遭遇する心配なく、「bundle-uri」を有効にすることに自信を持つべきです。サーバーバンドルが不完全であったり、何らかの形で不良であったりしても、クライアントは、このプロトコル拡張機能を使用しないことを選択した場合とまったく同じように、機能するリポジトリを取得できるはずです。
クライアントとサーバーのやり取りに関するその後のすべての議論は、この点を念頭に置く必要があります。
- bundle-uri サーバーからクライアントへ
-
返されたバンドル URI の順序は重要ではありません。クライアントは、含まれる OID と前提条件を検出するためにヘッダーを解析する必要があります。クライアントは、バンドル自体のコンテンツとそのヘッダーを究極の真実のソースと見なす必要があります。
サーバーは、クローンされるリポジトリと直接関係のないバンドル(偶発的または意図的な「巧妙な」設定による)を返すことさえあり、クライアントがバンドルから必要なデータを選別することを期待するかもしれません。
- bundle-uri クライアントからサーバーへ
-
クライアントは、後続の
fetch
リクエストで、バンドルヘッダーで見つかった参照ヒントを have 行として提供すべきです。クライアントは、何らかの理由でそれが悪いと判断された場合、たとえばバンドルをダウンロードできない場合や、見つかったヒントが気に入らない場合など、バンドルを完全に無視することもできます。 - 広告されたバンドルがそれ以上の交渉を必要としない場合
-
bundle-uri
とls-refs
を発行し、バンドルのヘッダーを取得した後、クライアントが目的の参照ヒントを広告されたバンドルから完全に取得できると判断した場合、クライアントは Git サーバーから切断しても構いません。そのような clone または fetch の結果は、bundle-uri を使用しない場合と区別できないはずです。 - クライアントの早期切断とエラー回復
-
クライアントは、バンドルをダウンロード中に (ヘッダーをストリームして解析済みであっても) 早期に切断する場合があります。そのような場合、クライアントはバンドルのダウンロードと検証の完了に関連するエラーから適切に回復する必要があります。
つまり、クライアントは再接続して fetch コマンドを発行する必要がある場合があり、場合によっては bundle-uri をまったく使用しないようにフォールバックする必要があるかもしれません。
この「MAY」の動作は(「SHOULD」ではなく)、「bundle-uri」をアドバタイズするサーバーは、比較的大規模なリポジトリを提供している可能性が高く、機能している可能性が高い URI を指しているという仮定に基づいて指定されています。クライアントは、たとえば、バンドルのペイロードサイズをヒューリスティックとして見て、早期切断が価値があるかどうかを判断するかもしれません。これにより、完全な「fetch」ダイアログへのフォールバックが必要な場合に備えることができます。
- 広告されたバンドルがさらなる交渉を必要とする場合
-
クライアントは、広告されたバンドルで見つかった OID ヒントを使用して、サーバーから PACK のネゴシエーションを "fetch" コマンドを介して開始すべきです。たとえそれらのバンドルのダウンロードが進行中であっても。
これにより、インタラクティブなサーバーダイアログから積極的に早期切断が可能になります。クライアントは、広告された OID ヒントが関連性があることを盲目的に信頼し、それらを have 行として発行します。次に、クライアントは目的のヒント(通常は "ls-refs" 広告から)を want 行を介して要求します。サーバーは、バンドルからのヒントと要求されたデータ間の期待される差分を持つ(うまくいけば小さな)PACK を計算します。
その後、クライアントがアクティブに維持する必要がある接続は、同時にダウンロードされている静的バンドルのみです。それらと増分 PACK が取得されたら、それらを展開して検証する必要があります。この時点でのエラーは、上記のように適切に回復する必要があります。
bundle-uri プロトコル機能
クライアントは、サーバーから提供された <key>=
<value> ペアからバンドルリストを構築します。これらのペアは、git-config[1] に記載されているように、bundle.*
名前空間の一部です。このセクションでは、これらのキーの一部について説明し、この情報に応じてクライアントが行うアクションを説明します。
特に、bundle.version
キーは整数値を指定します。現時点での許容値は 1
のみですが、クライアントがここで予期しない値を見た場合、クライアントはバンドルリストを無視する必要があります。
bundle.version
が理解されている限り、他の未知のキーはクライアントによって無視されても構いません。サーバーは古いクライアントとの互換性を保証しますが、新しいクライアントは追加のキーをより効果的に使用してダウンロードを最小限に抑えることができるかもしれません。
URI より前のキーと値のペアに対する後方互換性のない追加は、新しい bundle.version
の値、または bundle-uri 機能広告自体での値、および/または将来の新しい bundle-uri
要求引数によって保護されます。
現在実装されていないが将来実装されうるキーと値のペアの例をいくつか示します。
-
"hash=<val>" または "size=<bytes>" を追加して、バンドルファイルの予期されるハッシュまたはサイズをアドバタイズします。
-
1つ以上のバンドルファイルが同じであることをアドバタイズします(例:クライアントがラウンドロビンしたり、N個の可能なファイルの中から1つを選択したりできるようにします)。
-
「oid=<OID>」ショートカットと「prerequisite=<OID>」ショートカット。1つのヒントと前提条件なし、または1つのヒントと1つの前提条件を持つバンドルの一般的なケースを表現するため。
これにより、サーバーが「メイン」ブランチのみを含む「大きなバンドル」、および/またはその増分更新を提供したいという一般的なケースを最適化できます。
そのような応答を受け取ったクライアントは、示された URI のバンドルからヘッダーを取得するのをスキップできると仮定してもよいので、そのバンドルまたはバンドルのヘッダーを検査するために必要なリクエストを自分自身とサーバーから節約できます。
promisor-remote=<pr-infos>
サーバーは、このリポジトリの代わりにプロミサリーリモートとして使用したいクライアントに対して、自身が使用している、または認識しているプロミサリーリモートをアドバタイズできます。この場合、<pr-infos> は次の形式でなければなりません。
pr-infos = pr-info | pr-infos ";" pr-info
pr-info = "name=" pr-name | "name=" pr-name "," "url=" pr-url
ここで、pr-name
はプロミサリーリモートの URL エンコードされた名前であり、pr-url
はそのプロミサリーリモートの URL エンコードされた URL です。
この場合、クライアントがサーバーがアドバタイズした1つ以上のプロミサリーリモートを使用することを決定した場合、クライアントは "promisor-remote=<pr-names>" で応答できます。ここで <pr-names> は次の形式でなければなりません。
pr-names = pr-name | pr-names ";" pr-name
ここで、pr-name
はサーバーがアドバタイズし、クライアントが受け入れたプロミサリーリモートの URL エンコードされた名前です。
この文書のどこでも、pr-name
は有効なリモート名でなければならず、; および , の文字は、pr-name
または pr-url
に出現する場合はエンコードされなければならないことに注意してください。
サーバーがクライアントが使用するのに適したプロミサリーリモートを知らない場合、またはクライアントに自身が使用または知っているプロミサリーリモートを使用させたくない場合は、"promisor-remote" 機能をまったくアドバタイズすべきではありません。
この場合、またはクライアントがサーバーがアドバタイズしたプロミサリーリモートを使用しない場合、クライアントは応答で "promisor-remote" 機能をまったくアドバタイズすべきではありません。
"promisor.advertise" および "promisor.acceptFromServer" 設定オプションは、それぞれサーバー側とクライアント側で、アドバタイズまたは受け入れるものを制御するために使用できます。詳細については、これらの設定オプションのドキュメントを参照してください。
将来、サーバーが git
fetch
または git
clone
に応答する際に、このリポジトリの代わりに、クライアントがプロミサリーリモートとして使用できるより接続性の高いリモートをアドバタイズできるようになると良いでしょう。これにより、クライアントはこれらの他のより接続性の高いリモートからオブジェクトを遅延フェッチできるようになります。これには、サーバーが応答において、クライアントが受け入れたより接続性の高いリモートで利用可能なオブジェクトを省略する必要があります。ただし、これはまだ実装されていません。したがって、今のところ、この「promisor-remote」機能は、サーバーがすでにオブジェクトを借りるために使用しているプロミサリーリモートをアドバタイズする場合にのみ役立ちます。
GIT
git[1]スイートの一部