日本語 ▾ トピック ▾ 最新バージョン ▾ gitremote-helpers は 2.45.0 で最終更新されました

名前

gitremote-helpers - リモートリポジトリと対話するためのヘルパープログラム

概要

git remote-<transport> <repository> [<URL>]

説明

リモートヘルパープログラムは通常、エンドユーザーが直接使用することはありませんが、Gitがネイティブでサポートしていないリモートリポジトリと対話する必要がある場合にGitによって呼び出されます。特定のヘルパーは、ここに記載されている機能の一部を実装します。Gitがリモートヘルパーを使用してリポジトリと対話する必要がある場合、ヘルパーを独立したプロセスとして起動し、ヘルパーの標準入力にコマンドを送信し、ヘルパーの標準出力から結果を期待します。リモートヘルパーはGitとは独立したプロセスとして実行されるため、新しいヘルパーを追加するためにGitを再リンクする必要はなく、ヘルパーをGitの実装とリンクする必要もありません。

すべてのヘルパーは"capabilities"コマンドをサポートしている必要があります。Gitはこのコマンドを使用して、ヘルパーが受け入れる他のコマンドを決定します。これらの他のコマンドは、リモートリファレンスの発見と更新、オブジェクトデータベースとリモートリポジトリ間のオブジェクト転送、およびローカルオブジェクトストアの更新に使用できます。

Gitには、git-remote-httpgit-remote-httpsgit-remote-ftpgit-remote-ftpsなどのさまざまなトランスポートプロトコルを処理する"curl"ファミリーのリモートヘルパーが付属しています。これらは、fetchoptionpush の機能(capability)を実装しています。

起動

リモートヘルパープログラムは、1つまたは(オプションで)2つの引数で起動されます。最初の引数はGitの場合と同様にリモートリポジトリを指定します。これは、設定済みのリモートの名前、またはURLのいずれかです。2番目の引数はURLを指定します。通常は<transport>://<address>の形式ですが、任意の文字列も可能です。GIT_DIR環境変数はリモートヘルパー用に設定されており、追加データをどこに保存するか、またはどのディレクトリから補助Gitコマンドを呼び出すかを決定するために使用できます。

Gitが<transport>://<address>の形式のURLを検出した場合(ここで<transport>はGitがネイティブに処理できないプロトコル)、自動的にgit remote-<transport>を呼び出し、完全なURLを2番目の引数として渡します。このようなURLがコマンドラインで直接検出された場合、最初の引数は2番目の引数と同じになり、設定済みのリモートで検出された場合は、最初の引数はそのリモートの名前になります。

<transport>::<address>の形式のURLは、Gitに対し、<address>を2番目の引数としてgit remote-<transport>を明示的に呼び出すよう指示します。このようなURLがコマンドラインで直接検出された場合、最初の引数は<address>となり、設定済みのリモートで検出された場合は、最初の引数はそのリモートの名前になります。

さらに、設定済みのリモートのremote.<name>.vcs<transport>に設定されている場合、Gitは<name>を最初の引数としてgit remote-<transport>を明示的に呼び出します。設定されている場合、2番目の引数はremote.<name>.urlになります。そうでない場合、2番目の引数は省略されます。

入力形式

Gitは、リモートヘルパーに標準入力でコマンドのリストを1行に1つずつ送信します。最初のコマンドは常にcapabilitiesコマンドであり、これに応答してリモートヘルパーはサポートする機能のリスト(以下参照)を空白行に続けて出力する必要があります。capabilitiesコマンドへの応答は、コマンドストリームの残りの部分でGitが使用するコマンドを決定します。

コマンドストリームは空白行で終了します。場合によっては(関連コマンドのドキュメントに示されています)、この空白行の後には別のプロトコル(例:パックプロトコル)のペイロードが続きますが、他の場合は入力の終わりを示します。

機能

各リモートヘルパーは、コマンドのサブセットのみをサポートすることが期待されています。ヘルパーがサポートする操作は、capabilitiesコマンドへの応答(以下のCOMMANDSを参照)でGitに宣言されます。

以下に、定義されているすべての機能と、その機能を持つヘルパーが提供しなければならないコマンドを一覧表示します。

プッシュの機能

connect

Gitのネイティブパックファイルプロトコルを使用して通信するために、git receive-pack(プッシュ用)、git upload-packなどに接続を試みることができます。これは双方向の全二重接続を必要とします。

サポートされるコマンド: connect

stateless-connect

実験的機能; 内部でのみ使用。Gitのワイヤプロトコルバージョン2を使用して通信するために、リモートサーバーへの接続を試みることができます。詳細については、stateless-connectコマンドのドキュメントを参照してください。

サポートされるコマンド: stateless-connect

push

リモートリファレンスを発見し、ローカルコミットとそれに続く履歴を新規または既存のリモートリファレンスにプッシュできます。

サポートされるコマンド: list for-push, push

export

リモートリファレンスを発見し、fast-importストリームから指定されたオブジェクトをリモートリファレンスにプッシュできます。

サポートされるコマンド: list for-push, export

ヘルパーがconnectを宣伝する場合、Gitは可能であればそれを使用し、接続時にヘルパーが要求した場合(COMMANDSのconnectコマンドを参照)は別の機能にフォールバックします。pushexportの選択においては、Gitはpushを優先します。他のフロントエンドでは、別の優先順位を持つ場合があります。

no-private-update

refspec機能を使用する場合、gitは通常、プッシュ成功時にプライベートリファレンスを更新します。リモートヘルパーがno-private-update機能を宣言すると、この更新は無効になります。

フェッチの機能

connect

Gitのネイティブパックファイルプロトコルを使用して通信するために、git upload-pack(フェッチ用)、git receive-packなどに接続を試みることができます。これは双方向の全二重接続を必要とします。

サポートされるコマンド: connect

stateless-connect

実験的機能; 内部でのみ使用。Gitのワイヤプロトコルバージョン2を使用して通信するために、リモートサーバーへの接続を試みることができます。詳細については、stateless-connectコマンドのドキュメントを参照してください。

サポートされるコマンド: stateless-connect

fetch

リモートリファレンスを発見し、それらから到達可能なオブジェクトをローカルオブジェクトストアに転送できます。

サポートされるコマンド: list, fetch

import

リモートリファレンスを発見し、それらから到達可能なオブジェクトをfast-import形式のストリームとして出力できます。

サポートされるコマンド: list, import

check-connectivity

クローンが要求されたとき、受信したパックが自己完結型であり、接続されていることを保証できます。

get

指定されたURIからファイルをダウンロードするために、getコマンドを使用できます。

ヘルパーがconnectを宣伝する場合、Gitは可能であればそれを使用し、接続時にヘルパーが要求した場合(COMMANDSのconnectコマンドを参照)は別の機能にフォールバックします。fetchimportの選択においては、Gitはfetchを優先します。他のフロントエンドでは、別の優先順位を持つ場合があります。

その他の機能

option

他のコマンドの実行方法に影響を与えるverbosity(標準エラー出力に書き込む出力の量)やdepth(シャロークローンの場合に必要とされる履歴の量)などの設定を指定するために使用します。

refspec <refspec>

importまたはexportを実装するリモートヘルパーの場合、この機能により、refs/headsまたはrefs/remotesに直接書き込むのではなく、リファレンスをプライベート名前空間に制約することができます。import機能を提供するすべてのインポーターがこれを使用することを推奨します。exportには必須です。

refspec refs/heads/*:refs/svn/origin/branches/*の機能を宣伝するヘルパーは、import refs/heads/topicを要求されたときに、出力するストリームがrefs/svn/origin/branches/topicリファレンスを更新することを意味します。

この機能は複数回宣伝できます。最初に適用可能なrefspecが優先されます。この機能で宣伝されるrefspecの左側は、listコマンドによって報告されるすべてのリファレンスをカバーしている必要があります。refspec機能が宣伝されていない場合、暗黙的にrefspec *:*が存在します。

分散型バージョン管理システム用のリモートヘルパーを作成する際には、対話するためのリポジトリのローカルコピーを保持し、プライベート名前空間のリファレンスをこのローカルリポジトリにポイントさせ、refs/remotes名前空間はリモートリポジトリを追跡するために使用することを推奨します。

bidi-import

これはimport機能を変更します。fast-importコマンドのcat-bloblsは、リモートヘルパーがfast-importのメモリ内に既に存在するブロブやツリーに関する情報を取得するために使用できます。これにはfast-importからリモートヘルパーへのチャネルが必要です。もし"import"に加えてこれが宣伝された場合、Gitはfast-importからリモートヘルパーの標準入力へのパイプを確立します。したがって、Gitとfast-importの両方がリモートヘルパーの標準入力に接続されます。Gitはリモートヘルパーに複数のコマンドを送信できるため、bidi-importを使用するヘルパーは、fast-importにデータを送信する前に、バッチ内のすべてのimportコマンドをバッファリングする必要があります。これは、ヘルパーの標準入力でコマンドとfast-import応答が混ざるのを防ぐためです。

export-marks <file>

これはexport機能を変更し、完了時に内部マークテーブルを<file>にダンプするようにGitに指示します。詳細については、git-fast-export[1]--export-marks=<file>を参照してください。

import-marks <file>

これはexport機能を変更し、任意の入力を処理する前に<file>で指定されたマークをロードするようにGitに指示します。詳細については、git-fast-export[1]--import-marks=<file>を参照してください。

signed-tags

これはexport機能を変更し、--signed-tags=verbatimgit-fast-export[1]に渡すようにGitに指示します。この機能がない場合、Gitは--signed-tags=warn-stripを使用します。

object-format

これは、ヘルパーが明示的なハッシュアルゴリズム拡張を使用してリモート側と対話できることを示します。

コマンド

コマンドは、呼び出し元からヘルパーの標準入力に1行に1つずつ与えられます。

capabilities

ヘルパーの機能を1行に1つずつリストし、空白行で終了します。各機能には*を付けることができ、これはリモートヘルパーを使用するGitのバージョンにとって必須であることを示します。不明な必須機能は致命的なエラーとなります。

このコマンドのサポートは必須です。

list

リファレンスを1行に1つずつ、"<value> <name> [<attr> …​]"の形式でリストします。値は16進数のSHA-1ハッシュ、シンボリックリファレンスの場合は"@<dest>"、キーと値のペアの場合は":<keyword> <value>"、またはヘルパーがリファレンスの値を取得できなかった場合は"?"となります。名前の後にはスペース区切りの属性リストが続きます。認識されない属性は無視されます。リストは空白行で終了します。

現在定義されている属性のリストについては、REF LIST ATTRIBUTESを参照してください。現在定義されているキーワードのリストについては、REF LIST KEYWORDSを参照してください。

ヘルパーが"fetch"または"import"機能を備えている場合にサポートされます。

list for-push

listに似ていますが、呼び出し元がプッシュコマンドを準備するために結果のリファレンスリストを必要とする場合にのみ使用されます。プッシュとフェッチの両方をサポートするヘルパーは、listの出力がどちらの操作に使用されるかを区別するためにこれを使用でき、実行する必要のある作業量を削減できる可能性があります。

ヘルパーが"push"または"export"機能を備えている場合にサポートされます。

option <name> <value>

トランスポートヘルパーオプション<name>を<value>に設定します。ok(オプションが正常に設定された)、unsupported(オプションが認識されない)、またはerror <msg>(オプション<name>はサポートされているが、<value>が有効ではない)のいずれかを含む単一行を出力します。オプションは他のコマンドの前に設定する必要があり、それらのコマンドの動作に影響を与える可能性があります。

現在定義されているオプションのリストについては、OPTIONSを参照してください。

ヘルパーが"option"機能を備えている場合にサポートされます。

fetch <sha1> <name>

指定されたオブジェクトをフェッチし、必要なオブジェクトをデータベースに書き込みます。フェッチコマンドはバッチで、1行に1つずつ、空白行で終了します。同じバッチ内のすべてのフェッチコマンドが完了すると、単一の空白行を出力します。この方法でフェッチできるのは、listの出力でSHA-1で報告されたオブジェクトのみです。

オプションで、$GIT_DIR/objects/pack以下のファイルへの完全パスを示すlock <file>行を出力する場合があります。これは、リファレンスが適切に更新されるまでパックを保持するファイルです。パスは.keepで終わる必要があります。これは、キープコンポーネントのみを指定することで<パック、インデックス、キープ>の組に名前を付けるメカニズムです。保持されたパックは、フェッチが完了するまでそのオブジェクトが参照されない場合でも、競合する再パックによって削除されることはありません。.keepファイルはフェッチの終了時に削除されます。

オプションcheck-connectivityが要求された場合、クローンが自己完結型で接続されている場合、ヘルパーはconnectivity-okを出力する必要があります。

ヘルパーが"fetch"機能を備えている場合にサポートされます。

push +<src>:<dst>

指定されたローカルの<src>コミットまたはブランチを、<dst>で記述されたリモートブランチにプッシュします。1つ以上のpushコマンドのバッチシーケンスは空白行で終了します(プッシュするリファレンスが1つしかない場合は、単一のpushコマンドの後に空白行が続きます)。例えば、以下の例は2つのpushバッチであり、最初のバッチはリモートヘルパーにローカルのmasterリファレンスをリモートのmasterリファレンスに、ローカルのHEADをリモートのbranchにプッシュするよう要求し、2番目のバッチはfooリファレンスをbarリファレンスにプッシュするよう要求しています(+による強制更新要求)。

push refs/heads/master:refs/heads/master
push HEAD:refs/heads/branch
\n
push +refs/heads/foo:refs/heads/bar
\n

最後のpushコマンドの後、バッチの終了を示す空白行の前に、0個以上のプロトコルオプションを入力できます。

プッシュが完了すると、プッシュされた各リファレンスの成功または失敗を示す1つ以上のok <dst>またはerror <dst> <why>?行が出力されます。ステータスレポートの出力は空白行で終了します。オプションフィールド<why>にLFが含まれている場合、Cスタイルの文字列で引用符で囲むことができます。

ヘルパーが"push"機能を備えている場合にサポートされます。

import <name>

指定されたリファレンスの現在の値をインポートするfast-importストリームを生成します。また、履歴を効率的に構築するために必要に応じて他のリファレンスもインポートする場合があります。スクリプトはヘルパー固有のプライベート名前空間に書き込みます。指定されたリファレンスの値は、"refspec"機能のリファレンス仕様をリファレンスの名前に適用することで導出される、この名前空間内の場所に書き込まれる必要があります。

外部のバージョン管理システムとの相互運用に特に便利です。

pushと同様に、1つ以上のimportのバッチシーケンスは空白行で終了します。importの各バッチについて、リモートヘルパーはdoneコマンドで終了するfast-importストリームを生成する必要があります。

bidi-import機能が使用される場合、ヘルパーの標準入力でコマンドとfast-import応答が混ざるのを防ぐため、fast-importにデータを送信を開始する前に完全なバッチシーケンスをバッファリングする必要があることに注意してください。

ヘルパーが"import"機能を備えている場合にサポートされます。

export

リモートヘルパーに対し、以降の入力が、リモートにプッシュされるべきオブジェクトを含むfast-importストリーム(git fast-exportによって生成される)の一部であることを指示します。

外部のバージョン管理システムとの相互運用に特に便利です。

export-marksおよびimport-marks機能が指定されている場合、それらはgit fast-exportに渡され、その結果、ローカルオブジェクトのマークテーブルをロード/保存するため、このコマンドに影響を与えます。これは、増分操作を実装するために使用できます。

ヘルパーが"export"機能を備えている場合にサポートされます。

connect <service>

指定されたサービスに接続します。ヘルパーの標準入力と標準出力は、リモート側の指定されたサービス(サービス名にはgitプレフィックスが含まれるため、例えばフェッチではサービスとしてgit-upload-packを使用します)に接続されます。このコマンドに対する有効な応答は、空行(接続確立)、fallback(スマートトランスポートのサポートなし、ダンプトランスポートにフォールバック)、またはエラーメッセージを出力して終了する(接続できない、フォールバックを試みる価値なし)です。肯定的な(空の)応答を終了する改行の後、サービスの出力が開始されます。接続が終了すると、リモートヘルパーは終了します。

ヘルパーが"connect"機能を備えている場合にサポートされます。

stateless-connect <service>

実験的機能; 内部でのみ使用。Gitのワイヤプロトコルバージョン2を使用して通信するために、指定されたリモートサービスに接続します。このコマンドに対する有効な応答は、空行(接続確立)、fallback(スマートトランスポートのサポートなし、ダンプトランスポートにフォールバック)、またはエラーメッセージを出力して終了する(接続できない、フォールバックを試みる価値なし)です。肯定的な(空の)応答を終了する改行の後、サービスの出力が開始されます。メッセージ(要求と応答の両方)は、0個以上のPKT-LINEで構成され、フラッシュパケットで終了する必要があります。応答メッセージには、フラッシュパケットの後に応答終了パケットがあり、応答の終わりを示します。クライアントは、要求と応答のペアの間にサーバーが状態を保存することを期待してはなりません。接続が終了すると、リモートヘルパーは終了します。

ヘルパーが"stateless-connect"機能を備えている場合にサポートされます。

get <uri> <path>

指定された<uri>から指定された<path>にファイルをダウンロードします。<path>.tempが存在する場合、Gitは.tempファイルが以前の試行からの部分的なダウンロードであるとみなし、その位置からダウンロードを再開します。

致命的なエラーが発生した場合、プログラムはエラーメッセージを標準エラー出力に書き込み、終了します。子プロセスが現在のコマンドに対する有効な応答を完了せずに接続を閉じた場合、呼び出し元は適切なエラーメッセージが出力されたと期待すべきです。

ヘルパーが報告する機能から判断されるように、追加のコマンドがサポートされる場合があります。

参照リスト属性

listコマンドは、各リファレンスに属性リストが続く可能性があるリファレンスのリストを生成します。以下の参照リスト属性が定義されています。

unchanged

このリファレンスは、最後のインポートまたはフェッチ以降変更されていませんが、ヘルパーがそれが生成した値を必ずしも判断できるわけではありません。

参照リストキーワード

listコマンドは、キーと値のペアのリストを生成する場合があります。以下のキーが定義されています。

object-format

リファレンスは指定されたハッシュアルゴリズムを使用しています。このキーワードは、サーバーとクライアントの両方がobject-format拡張をサポートしている場合にのみ使用されます。

オプション

以下のオプションは、リモートヘルパーがoption機能を備えている場合、Gitによって定義され、(適切な状況で)設定されます。

option verbosity <n>

ヘルパーによって表示されるメッセージの詳細度を変更します。<n>の値が0の場合、プロセスは静かに動作し、ヘルパーはエラー出力のみを生成します。1がデフォルトの詳細度レベルであり、<n>のより高い値はコマンドラインで渡された-vフラグの数に対応します。

option progress {true|false}

コマンド実行中にトランスポートヘルパーによって表示される進捗メッセージを有効(または無効)にします。

option depth <depth>

シャローリポジトリの履歴を深くします。

option deepen-since <timestamp>

シャローリポジトリの履歴を時間に基づいて深くします。

option deepen-not <ref>

指定したリファレンスを除外してシャローリポジトリの履歴を深くします。複数のオプションは累積されます。

option deepen-relative {true|false}

現在の境界に対してシャローリポジトリの履歴を深くします。"option depth"と組み合わせて使用した場合にのみ有効です。

option followtags {true|false}

有効にすると、ヘルパーは、タグが指すオブジェクトがフェッチコマンド中に転送された場合、アノテートされたタグオブジェクトを自動的にフェッチする必要があります。ヘルパーによってタグがフェッチされない場合、通常、そのタグを具体的に要求するために2番目のフェッチコマンドが送信されます。一部のヘルパーは、このオプションを使用して2回目のネットワーク接続を回避できる場合があります。

option dry-run {true|false}: trueの場合、操作が正常に完了したふりをしますが、実際にはリポジトリデータを変更しません。ほとんどのヘルパーでは、これはサポートされている場合のみpushに適用されます。

option servpath <c-style-quoted-path>

次回の接続のためにサービスパス(--upload-pack、--receive-packなど)を設定します。リモートヘルパーはこのオプションをサポートする場合がありますが、接続要求が発生する前にこのオプションが設定されていることに依存してはなりません。

option check-connectivity {true|false}

クローンの接続性を確認するようヘルパーに要求します。

option force {true|false}

ヘルパーに強制更新を実行するよう要求します。デフォルトはfalseです。

option cloning {true|false}

これがクローン要求であることをヘルパーに通知します(つまり、現在のリポジトリは空であることが保証されます)。

option update-shallow {true|false}

新しいリファレンスが必要とする場合、.git/shallowを拡張することを許可します。

option pushcert {true|false}

プッシュをGPG署名します。

option push-option <string>

<string>をプッシュオプションとして送信します。プッシュオプションにはLFまたはNUL文字を含めることができないため、文字列はエンコードされません。

option from-promisor {true|false}

これらのオブジェクトがプロミサーからフェッチされていることを示します。

option no-dependents {true|false}

必要なオブジェクトのみをフェッチする必要があり、その依存オブジェクトはフェッチする必要がないことを示します。

option atomic {true|false}

プッシュ時、リモートサーバーに対し、単一のアトミックトランザクションでリファレンスを更新するよう要求します。成功した場合、すべてのリファレンスが更新されるか、何も更新されません。リモート側がこの機能をサポートしない場合、プッシュは失敗します。

option object-format true

呼び出し元がハッシュアルゴリズム情報をリモートから返してほしいことを示します。このモードはリファレンスをフェッチする際に使用されます。

Git

git[1]スイートの一部

scroll-to-top