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

名前

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

概要

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

説明

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

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

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

呼び出し

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

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

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

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

入力形式

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

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

機能

各リモートヘルパーは、コマンドのサブセットのみをサポートすることが期待されています。ヘルパーがサポートする操作は、capabilitiesコマンドへの応答(以下のコマンドを参照)で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は可能な限りそれを使用し、ヘルパーが接続時に要求した場合(コマンドの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

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

ヘルパーがconnectをアドバタイズする場合、Gitは可能な限りそれを使用し、ヘルパーが接続時に要求した場合(コマンドのconnectコマンドを参照)は別の機能にフォールバックします。fetchimportのどちらかを選択する場合、Gitはfetchを優先します。他のフロントエンドでは、優先順位が異なる場合があります。

その他の機能

option

他のコマンドの実行方法に影響を与える設定、例えばverbosity(stderrに出力する量)やdepth(シャロークローンの場合に望ましい履歴の量)などを指定するためのもの。

refspec <refspec>

importまたはexportを実装するリモートヘルパーの場合、この機能により、refs/headsまたはrefs/remotesに直接書き込むのではなく、refsをプライベート名前空間に制約できます。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機能を変更し、完了時にGitに内部マークテーブルを<file>にダンプするように指示します。詳細については、git-fast-export[1]--export-marks=<file>を参照してください。

import-marks <file>

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

signed-tags

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

object-format

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

コマンド

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

capabilities

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

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

list

参照を1行に1つずつ、"<value> <name> [<attr> …​]" の形式でリストします。値は16進数のsha1ハッシュ、シンボリック参照の場合は "@<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>は有効ではない)のいずれかを含む1行を出力します。オプションは他のコマンドの前に設定する必要があり、それらのコマンドの動作に影響を与える可能性があります。

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

"option" 機能を持つヘルパーがサポートします。

fetch <sha1> <name>

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

オプションで、$GIT_DIR/objects/packの下にあるファイルの完全パスを示すlock <file>行を出力する場合があります。これは、参照が適切に更新されるまでパックを保持しています。パスは.keepで終わる必要があります。これは、保持コンポーネントのみを指定して<pack,idx,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" 機能からの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ファイルが以前の試行からの部分的なダウンロードであるとみなし、その位置からダウンロードを再開します。

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

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

参照リスト属性

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

unchanged

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

参照リストキーワード

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

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