Git
英語 ▾ トピック ▾ 最新バージョン ▾ gitremote-helpers 最終更新日: 2.45.0

名前

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

概要

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

説明

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

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

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

呼び出し

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

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

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

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

入力形式

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

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

機能

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

次に、定義されているすべての機能をリストし、それぞれについて、その機能を持つヘルパーが提供する必要があるコマンドをリストします。

プッシュの機能

connect

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

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

stateless-connect

実験的。内部使用専用です。Gitのワイヤプロトコルバージョン2を使用してリモートサーバーに接続しようとします。詳細については、stateless-connectコマンドのドキュメントを参照してください。

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

push

リモートrefを発見し、ローカルコミットとそれらに至る履歴を新しいまたは既存のリモートrefにプッシュできます。

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

export

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

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

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

no-private-update

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

フェッチの機能

connect

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

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

stateless-connect

実験的。内部使用専用です。Gitのワイヤプロトコルバージョン2を使用してリモートサーバーに接続しようとします。詳細については、stateless-connectコマンドのドキュメントを参照してください。

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

fetch

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

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

import

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

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

check-connectivity

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

get

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

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

その他の機能

option

verbosity(stderrに書き込む出力量)やdepth(浅いクローンでの履歴の量)などの設定を指定し、他のコマンドの実行方法に影響を与えます。

refspec <refspec>

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

機能 `refspec refs/heads/*:refs/svn/origin/branches/*` をアドバタイズするヘルパーは、`import refs/heads/topic` の要求を受けると、出力ストリームによって `refs/svn/origin/branches/topic` ref を更新することを示しています。

この機能は複数回アドバタイズできます。最初に適用可能な refspec が優先されます。この機能でアドバタイズされる refspec の左辺は、list コマンドによって報告されるすべての ref をカバーする必要があります。refspec 機能がアドバタイズされていない場合、暗黙的に `refspec *:*` が適用されます。

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

bidi-import

これは import 機能を変更します。リモートヘルパーは、fast-import コマンドの cat-blob および ls を使用して、fast-import のメモリに既に存在する blob とツリーに関する情報を取得できます。これには、fast-import からリモートヘルパーへのチャネルが必要です。"import"に加えてアドバタイズされている場合、Git は fast-import からリモートヘルパーの stdin へのパイプを確立します。つまり、Git と fast-import の両方がリモートヘルパーの stdin に接続されます。Git はリモートヘルパーに複数のコマンドを送信できるため、bidi-import を使用するヘルパーは、fast-import にデータを送信する前に、バッチのすべての import コマンドをバッファリングする必要があります。これは、ヘルパーの stdin でコマンドと 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 機能を変更し、git-fast-export[1]--signed-tags=verbatim を渡すよう Git に指示します。この機能がない場合、Git は --signed-tags=warn-strip を使用します。

object-format

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

コマンド

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

capabilities

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

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

list

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

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

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

list for-push

list と似ていますが、呼び出し元が結果の ref リストを使用して push コマンドを準備する場合にのみ使用されます。push と fetch の両方をサポートするヘルパーは、これを使用して list の出力がどの操作に使用されるかを区別し、実行する必要のある作業量を削減できます。

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

option <name> <value>

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

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

ヘルパーに "option" 機能がある場合にサポートされます。

fetch <sha1> <name>

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

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

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

ヘルパーに "fetch" 機能がある場合にサポートされます。

push +<src>:<dst>

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

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

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

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

ヘルパーに "push" 機能がある場合にサポートされます。

import <name>

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

特に、外部バージョン管理システムとの相互運用に役立ちます。

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

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

ヘルパーに "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」(スマートトランスポートのサポートなし、ダムトランスポートにフォールバック)です。エラーメッセージが印刷された状態で終了するだけです(接続できません。フォールバックを試行しないでください)。肯定的な(空の)応答を終了する改行の後、サービスの出力が開始されます。メッセージ(要求と応答の両方)は、ゼロ個以上の PKT-LINE で構成され、フラッシュパケットで終了する必要があります。その後、応答メッセージには、応答の終了を示すフラッシュパケットの後に応答終了パケットが追加されます。クライアントは、サーバーが要求と応答のペアの間の状態を保存することを期待しないでください。接続が終了すると、リモートヘルパーは終了します。

ヘルパーに "stateless-connect" 機能がある場合にサポートされます。

get <uri> <path>

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

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

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

REF LIST ATTRIBUTES

list コマンドは、各 ref の後に属性のリストを付けることができる ref のリストを生成します。次の ref リスト属性が定義されています。

unchanged

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

参照リストキーワード

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

object-format

refは、指定されたハッシュアルゴリズムを使用しています。このキーワードは、サーバーとクライアントの両方が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>

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}

新しいrefが必要な場合に.git/shallowを拡張することを許可します。

option pushcert {true|false}

GPG署名によるpushを行います。

option push-option <string>

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

option from-promisor {true|false}

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

option no-dependents {true|false}

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

option atomic {true|false}

pushする際、リモートサーバーにrefを一括アトミックトランザクションで更新するよう要求します。成功すると、すべてのrefが更新されるか、どれも更新されません。リモート側がこの機能をサポートしていない場合、pushは失敗します。

option object-format true

呼び出し元がリモートからハッシュアルゴリズム情報を返すことを要求することを示します。このモードは、refをフェッチする場合に使用されます。

Git

git[1]スイートの一部

scroll-to-top