gitprotocol-pack - パックファイルのネットワーク転送方法

Git は、ssh://、git://、http://、および file:// トランスポートを介してパックファイル内のデータを転送できます。クライアントからサーバーへのデータプッシュと、サーバーからクライアントへのデータフェッチの2つのプロトコルセットがあります。ssh、git、fileの3つのトランスポートは、同じプロトコルを使用してデータを転送します。httpについては、gitprotocol-http[5]を参照してください。

標準的なGit実装で呼び出されるプロセスは、データフェッチの場合はサーバー側でupload-pack、クライアント側でfetch-packです。データプッシュの場合は、サーバー側でreceive-pack、クライアント側でsend-packです。このプロトコルは、サーバーがクライアントにサーバー上の現在の状態を伝え、その後、互いを完全に更新するために送信する必要のある最小限のデータ量を交渉するために機能します。

以下の説明は、gitprotocol-common[5]で説明されているpkt-line形式に基づいています。文法でPKT-LINE(...)が示されている場合、特に明記されていない限り、通常のpkt-line LFルールが適用されます。送信者はLFを含めるべきですが、受信者は存在しない場合に文句を言うべきではありません。

エラーパケットは、エラー文字列を含む特別なpkt-lineです。

プロトコル全体で、PKT-LINE(...)が期待される場合、エラーパケットを送信できます。クライアントまたはサーバーがこのパケットを送信すると、このプロトコルで定義されたデータ転送プロセスは終了します。

パックファイルプロトコルが開始されるトランスポートは3つあります。Gitトランスポートは、クライアントが通信したいコマンド（ほとんどの場合upload-packですが、Gitサーバーはグローバルに書き込み可能に構成できるため、receive-packの開始も許可されます）を受け取り、それを実行して要求プロセスに接続する単純な、認証されていないサーバーです。

SSHトランスポートでは、クライアントはSSHプロトコルを介してサーバー上でupload-packまたはreceive-packプロセスを実行し、その呼び出されたプロセスとSSH接続を介して通信します。

file://トランスポートは、upload-packまたはreceive-packプロセスをローカルで実行し、パイプを介して通信します。

このプロトコルは、クライアントがサーバーへの最初のメッセージに追加情報を送信できるメカニズムを提供します。これらは「追加パラメータ」と呼ばれ、Git、SSH、およびHTTPプロトコルでサポートされています。

各追加パラメータは、<key>=<value>または<key>の形式を取ります。

このような追加パラメータを受信するサーバーは、認識されないキーをすべて無視する必要があります。現在、認識されている追加パラメータは、値が1または2の「version」だけです。プロトコルバージョン2の詳細については、gitprotocol-v2[5]を参照してください。

Gitトランスポートは、pkt-line形式を使用してワイヤ上でコマンドとリポジトリを送信することから始まり、その後にNULバイトとホスト名パラメータが続き、NULバイトで終了します。

トランスポートは、追加のNULバイトを追加し、1つ以上のNULで終端された文字列を追加することで、追加パラメータを送信できます。

host-parameterは、git-daemonのnameベースの仮想ホスティングに使用されます。%H/%CH形式文字を含むgit daemonの--interpolated-pathオプションを参照してください。

基本的に、GitクライアントがGitプロトコルを介してサーバー側のupload-packプロセスに接続するために実行していることは次のとおりです。

SSHを介してupload-packまたはreceive-packプロセスを開始するには、SSHリモート実行を使用してサーバー上のバイナリを実行します。これは基本的に次の実行と同等です。

サーバーが特定のユーザーに対してSSHを介したGitのプッシュとプルをサポートするには、そのユーザーがログイン時に提供されるSSHシェルを介してそれらのコマンドの1つまたは両方を実行できる必要があります。一部のシステムでは、そのシェルアクセスは、それらの2つのコマンドのみ、またはそのうちの1つのみを実行できるよう制限されています。

ssh://形式のURIでは、URI内で絶対パスであるため、ホスト名（またはポート番号）の後の/は引数として送信され、リモートgit-upload-packによってそのまま読み取られるため、リモートファイルシステム内の絶対パスとして機能します。

"user@host:path"形式のURIでは、ユーザーのホームディレクトリを基準とした相対パスです。Gitクライアントは次を実行するためです。

例外は、~が使用されている場合で、その場合は先頭の/なしで実行します。

protocol.version構成変数の値によっては、GitはGIT_PROTOCOL環境変数にコロン区切りの文字列として追加パラメータを送信しようとします。これは、ssh.variant構成変数がsshコマンドが引数として環境変数の受け渡しをサポートしていることを示している場合のみ実行されます。

ここで覚えておくべき点がいくつかあります。

あるGitリポジトリが別のリポジトリが持つデータを取得したい場合、最初のリポジトリは2番目のリポジトリからフェッチできます。この操作は、サーバーがクライアントが持たないデータを特定し、そのデータをパックファイル形式でクライアントにストリーミングします。

クライアントが最初に接続すると、サーバーはすぐにバージョン番号（「version=1」が追加パラメータとして送信されている場合）、および各参照（すべてのブランチとタグ）とその参照が現在指しているオブジェクト名の一覧を返します。

返された応答は、各参照とその現在の値を記述するpkt-lineストリームです。ストリームは、Cロケール順序に従って名前でソートする必要があります。

HEADが有効な参照の場合、HEADは最初に宣伝された参照として表示される必要があります。HEADが無効な参照の場合、HEADは広告リストにまったく表示されない必要がありますが、他の参照は表示される可能性があります。

ストリームには、最初の参照の後ろのNULの後ろに機能宣言を含める必要があります。参照の展開された値（つまり「ref^{}」）は、存在する場合、参照の直後に表示する必要があります。準拠するサーバーは、それが注釈付きタグの場合、参照を展開する必要があります。

サーバーとクライアントは、obj-idに小文字を使用する必要があり、どちらもobj-idを大文字と小文字を区別しないものとして扱う必要があります。

許可されるサーバー機能と説明の一覧については、protocol-capabilities.txtを参照してください。

参照と機能の検出後、クライアントはflush-pktを送信して接続を終了することにより、パックデータが不要になった場合、サーバーが正常に終了して切断できるようにすることができます。これはls-remoteコマンドで発生し、クライアントが既に最新の状態である場合にも発生する可能性があります。

それ以外の場合は、ネゴシエーションフェーズに入り、クライアントとサーバーは、サーバーに要求するオブジェクト、浅いオブジェクト（存在する場合）、および要求する最大コミット深度（存在する場合）をサーバーに伝えることで、転送に必要な最小限のパックファイルを決定します。クライアントは、サーバーが最初に言ったことができる機能の中から、有効にしたい機能のリストも送信します。

クライアントは、参照検出フェーズから必要なすべてのobj-idをwant行として送信する必要があります。クライアントは、要求本文に少なくとも1つのwantコマンドを送信する必要があります。クライアントは、参照検出によって取得された応答に表示されなかったobj-idをwantコマンドに記述してはなりません。

クライアントは、浅いコピーのみを持っている（つまり、コミットの親を持っていない）すべてのobj-idをshallow行として記述する必要があります。これにより、サーバーはクライアントの履歴の制限を認識できます。

クライアントは、このトランザクションで必要な最大コミット履歴深度をdeepen行としてオプションで要求できます。これは、履歴の先端からのコミット数です。深さが0の場合、深さの要求を行わないことと同じです。クライアントは、この深度を超えたコミットを受信したくなく、それらのコミットを完了するためにのみ必要なオブジェクトも必要としません。結果として親が受信されないコミットは、浅いものとして定義され、サーバーでそのようにマークされます。この情報は、次のステップでクライアントに送信されます。

クライアントは、いくつかのフィルタリング手法のいずれかを使用して、pack-objectsがパックファイルからさまざまなオブジェクトを省略するようにオプションで要求できます。これらは、部分クローンと部分フェッチ操作で使用することを目的としています。フィルタ指定値を満たさないオブジェクトは、want行で明示的に要求されていない限り、省略されます。可能なフィルタ指定値については、rev-listを参照してください。

すべてのwantとshallow（およびオプションのdeepen）が転送されると、クライアントはflush-pktを送信して、リストの送信が完了したことをサーバー側に通知する必要があります。

それ以外の場合、クライアントが正の深度要求を送信した場合、サーバーはどのコミットが浅くなるかを決定し、この情報をクライアントに送信します。クライアントが正の深度を要求しなかった場合、このステップはスキップされます。

クライアントが正のdepthを要求した場合、サーバーは目的のdepthよりも浅いコミットの集合を計算します。コミットの集合は、クライアントのwantsから始まります。

サーバーは、その親が送信されないコミットごとにshallow行を書き込みます。また、クライアントがshallowであると指示したものの、現在要求されたdepthではshallowではなくなった（つまり、その親が送信されるようになった）コミットごとにunshallow行を書き込みます。サーバーは、クライアントがshallowであると指示しなかったものをunshallowとしてマークしてはなりません。

次に、クライアントはhave行を使用して保持しているobj-idのリストを送信し、サーバーはクライアントが必要とするオブジェクトのみを含むパックファイルを作成できます。multi_ackモードでは、標準の実装では一度に最大32個のhave行を送信し、その後flush-pktを送信します。標準の実装では、次の32個をすぐに送信するため、常に32個のブロックが「送信中」になります。

サーバーがhave行を読み取ると、クライアントが保持していると述べたobj-idのうち、サーバーも保持しているものに対してACKを返します。サーバーは、クライアントが選択したackモードに応じて、obj-idに対するACKを異なる方法で返します。

multi_ackモードでは

multi_ack_detailedモードでは

multi_ackとmulti_ack_detailedのどちらも使用しない場合

クライアントは、サーバーが効率的なパックファイルを送信するのに十分な情報を持っていると判断できるだけのACK応答を受け取ると（標準の実装では、残りの`--date-order`キュー内のすべてをサーバーと共通のものとして色付けできるだけのACKを受け取るか、`--date-order`キューが空になることで判断されます）、またはクライアントが諦めたいと判断すると（標準の実装では、クライアントが256個のhave行を送信してもサーバーからACKされないことで判断されます - 共通するものがなく、サーバーはすべてのオブジェクトを送信する必要があることを意味します）、doneコマンドを送信します。doneコマンドは、クライアントがパックファイルデータの受信準備ができていることをサーバーに知らせます。

ただし、256個の制限は、以前のラウンドで少なくとも1つの"ACK %s continue"を受け取った場合にのみ、標準のクライアント実装で有効になります。これは、完全に諦める前に少なくとも1つの共通の祖先が見つかるようにするためです。

クライアントからdone行が読み取られると、サーバーは最終的なACK obj-idを送信するか、NAKを送信します。obj-idは、共通であると判断された最後のコミットのオブジェクト名です。サーバーは、少なくとも1つの共通のベースがあり、multi_ackまたはmulti_ack_detailedが有効になっている場合にのみ、done後にACKを送信します。共通のベースが見つからない場合は、サーバーは常にdone後にNAKを送信します。

ACKまたはNAKの代わりに、サーバーはエラーメッセージを送信する場合があります（たとえば、クライアントから受信したwant行内のオブジェクトを認識できない場合など）。

その後、サーバーはパックファイルデータの送信を開始します。

(have行のない)単純なクローンは次のようになります。

増分更新(フェッチ)レスポンスは次のようになります。

クライアントとサーバーは、クライアントに送信する必要がある最小限のデータ量についてネゴシエーションを完了したので、サーバーは必要なデータをパックファイル形式で構築して送信します。

パックファイル自体の実際の内容については、gitformat-pack[5]を参照してください。

クライアントによってside-bandまたはside-band-64k機能が指定されている場合、サーバーは多重化されたパックファイルデータを送信します。

各パケットは、それに続くデータ量のpacket-line長で始まり、それに続くデータがどのサイドバンドから来ているかを指定する1バイトが続きます。

side-bandモードでは、最大999バイトのデータと1つの制御コードを送信し、合計最大1000バイトをpkt-lineに含めます。side-band-64kモードでは、最大65519バイトのデータと1つの制御コードを送信し、合計最大65520バイトをpkt-lineに含めます。

サイドバンドバイトは1、2、または3になります。サイドバンド1にはパックファイルデータが含まれ、サイドバンド2はクライアントが一般的にstderrに出力する進捗情報に使用され、サイドバンド3はエラー情報に使用されます。

side-band機能が指定されていない場合、サーバーは多重化せずにパックファイルをストリーミングします。

サーバーへのデータのプッシュは、サーバー上のreceive-packプロセスを呼び出します。これにより、クライアントは更新する参照をサーバーに伝え、それらの新しい参照を完成させるためにサーバーが必要とするすべてのデータを送信できます。すべてのデータが受信され検証されると、サーバーは参照をクライアントが指定したものに更新します。

プロトコル自体には認証メカニズムが含まれていません。SSHなどのトランスポートによって、receive-packプロセスが呼び出される前に処理されます。Gitトランスポートを介してreceive-packが構成されている場合、それらのリポジトリは、そのポート(9418)にアクセスできる人であれば誰でも書き込み可能になります。これは、そのトランスポートが認証されていないためです。

参照の検出フェーズは、フェッチプロトコルとほぼ同じ方法で行われます。サーバー上の各参照obj-idと名前は、packet-line形式でクライアントに送信され、flush-pktが続きます。唯一の違いは、機能リストが異なることです。可能な値は、report-status、report-status-v2、delete-refs、ofs-delta、atomic、およびpush-optionsのみです。

クライアントはサーバーの参照が何であるかを知ると、参照更新要求のリストを送信できます。更新するサーバー上の各参照について、サーバー上に現在あるobj-id、クライアントが更新したいobj-id、および参照の名前をリストした行を送信します。

このリストの後にflush-pktが続きます。

サーバーがpush-options機能をアドバタイズしており、クライアントが上記の機能リストの一部としてpush-optionsを指定している場合、クライアントはプッシュオプションを送信し、その後にflush-pktを送信します。

古いGitサーバーとの下位互換性のために、クライアントがプッシュ証明書とプッシュオプションを送信する場合、プッシュ証明書に埋め込まれたプッシュオプションと、プッシュ証明書の後のプッシュオプションの両方を送信する必要があります。（証明書内のプッシュオプションには接頭辞が付きますが、証明書後のプッシュオプションには接頭辞が付かないことに注意してください）。これら2つのリストは、接頭辞を除いて同じである必要があります。

その後、サーバーが新しい参照を完成させるために必要なすべてのオブジェクトを含むパックファイルが送信されます。

受信側がdelete-refsをサポートしていない場合、送信側は削除コマンドを要求してはなりません。

受信側がpush-certをサポートしていない場合、送信側はpush-certコマンドを送信してはなりません。push-certコマンドが送信されると、command-listを送信してはなりません。代わりに、プッシュ証明書に記録されたコマンドが使用されます。

使用されるコマンドがdeleteのみの場合は、パックファイルを送信してはなりません。

createまたはupdateコマンドが使用されている場合、サーバーが既に必要なすべてのオブジェクトを持っている場合でも、パックファイルを送信する必要があります。この場合、クライアントは空のパックファイルを送信する必要があります。これは、クライアントが既存のobj-idを指す新しいブランチまたはタグを作成する場合にのみ発生する可能性があります。

サーバーはパックファイルを受信し、解凍し、更新中の各参照が要求処理中に変更されていないことを検証し（obj-idは古いidと同じです）、更新が許容可能であることを確認するために更新フックを実行します。すべてが問題なければ、サーバーは参照を更新します。

プッシュ証明書は、ヘッダー行のセットで始まります。ヘッダーと空行の後に、プロトコルコマンドが1行ずつ続きます。プッシュ証明書PKT-LINEの末尾のLFは必須です。

現在、次のヘッダーフィールドが定義されています。

GPG署名行は、署名ブロックが始まる前のプッシュ証明書に記録された内容に対する分離署名です。分離署名は、コマンドがプッシャー（署名者でなければならない）によって与えられたことを証明するために使用されます。

送信者からパックデータを受信した後、受信者はreport-statusまたはreport-status-v2機能が有効な場合にレポートを送信します。これは、その更新で発生したことを簡潔にリストしたものです。まず、パックファイルの解凍の状態をunpack okまたはunpack [error]としてリストします。次に、更新しようとした各参照の状態をリストします。各行は、更新が成功した場合はok [refname]、更新が失敗した場合はng [refname] [error]です。

report-status-v2機能は、proc-receiveフックによって書き換えられた参照のレポートをサポートするために、新しいオプション行を追加することでプロトコルを拡張します。proc-receiveフックは、擬似参照に対するコマンドを処理することができ、これにより1つ以上の参照が作成または更新される可能性があり、各参照は異なる名前、異なるnew-oid、および異なるold-oidを持つ可能性があります。

更新は、いくつかの理由で失敗する可能性があります。参照は、参照検出フェーズが最初に送信されて以降に変更されている可能性があり、つまりその間に誰かがプッシュしたということです。プッシュされている参照はノンファストフォワード参照である可能性があり、更新フックまたは設定がそれを許可しないように設定されている可能性などもあります。また、一部の参照は更新される一方で、他の参照は拒否される可能性があります。

クライアント/サーバー間の通信の例を以下に示します。

git[1]スイートの一部