簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitremote-helpers 上次更新於 2.51.0

名稱

gitremote-helpers - 與遠端儲存庫互動的輔助程式

概要

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

描述

遠端輔助程式通常不直接被終端使用者使用，但當 Git 需要與 Git 本身不支援的遠端儲存庫互動時，它們會被呼叫。給定的輔助程式將實現此處記錄的功能的一個子集。當 Git 需要與遠端輔助程式互動時，它會將該輔助程式作為獨立程序啟動，將命令傳送到該輔助程式的標準輸入，並期望從其標準輸出獲取結果。由於遠端輔助程式作為 Git 的獨立程序執行，因此無需重新連結 Git 來新增新的輔助程式，也無需將輔助程式與 Git 的實現連結。

每個輔助程式都必須支援“capabilities”命令，Git 使用此命令來確定輔助程式還將接受哪些其他命令。這些其他命令可用於發現和更新遠端引用、在物件資料庫和遠端儲存庫之間傳輸物件以及更新本地物件儲存。

Git 提供了“curl”系列的遠端輔助程式，它們處理各種傳輸協議，例如 git-remote-http、git-remote-https、git-remote-ftp 和 git-remote-ftps。它們實現了 fetch、option 和 push 的功能。

呼叫

遠端輔助程式透過一個或（可選）兩個引數呼叫。第一個引數指定 Git 中的遠端儲存庫，它是已配置的遠端名稱或 URL。第二個引數指定一個 URL，通常形式為 <transport>://<address>，但也可以是任何任意字串。 GIT_DIR 環境變數為遠端輔助程式設定，可用於確定儲存額外資料的位置或從哪個目錄呼叫輔助 Git 命令。

當 Git 遇到 <transport>://<address> 形式的 URL 時，其中 <transport> 是 Git 無法原生處理的協議，它會自動呼叫 git remote-<transport>，並將完整 URL 作為第二個引數。如果直接在命令列中遇到此類 URL，第一個引數與第二個引數相同；如果是在已配置的遠端中遇到，第一個引數是該遠端的名稱。

<transport>::<address> 形式的 URL 會明確指示 Git 呼叫 git remote-<transport>，並將 <address> 作為第二個引數。如果直接在命令列中遇到此類 URL，第一個引數是 <address>；如果是在已配置的遠端中遇到，第一個引數是該遠端的名稱。

此外，當已配置的遠端的 remote.<name>.vcs 設定為 <transport> 時，Git 會顯式呼叫 git remote-<transport>，並將 <name> 作為第一個引數。如果設定了，第二個引數是 remote.<name>.url；否則，第二個引數將被省略。

輸入格式

Git 將命令列表傳送到標準輸入，每行一個命令。第一個命令始終是 capabilities 命令，響應此命令時，遠端輔助程式必須列印其支援的功能列表（如下所述），後跟一個空行。對 capabilities 命令的響應決定了 Git 在命令流的其餘部分中使用哪些命令。

命令流以空行結束。在某些情況下（在相關命令的文件中指示），此空行後會跟其他協議（例如 pack 協議）的有效負載，而在其他情況下，它表示輸入結束。

功能

每個遠端輔助程式都應只支援命令的一個子集。輔助程式支援的操作透過響應 capabilities 命令（參見下文的 COMMANDS）向 Git 宣告。

下面列出了所有已定義的功能，併為每種功能列出了輔助程式必須提供的命令。

推送功能

connect

可以嘗試連線到 git receive-pack（用於推送）、git upload-pack 等，以便使用 Git 的原生 packfile 協議進行通訊。這需要雙向全雙工連線。

支援的命令：connect。

stateless-connect

實驗性功能；僅供內部使用。可以嘗試連線到遠端伺服器，以便使用 Git 的 wire-protocol 版本 2 進行通訊。有關 stateless-connect 命令的更多資訊，請參閱文件。

支援的命令：stateless-connect。

push

可以發現遠端引用並將本地提交及其依賴的歷史推送到新的或現有的遠端引用。

支援的命令：list for-push、push。

export

可以發現遠端引用並將來自 fast-import 流的指定物件推送到遠端引用。

支援的命令：list for-push、export。

如果輔助程式聲明瞭 connect，Git 將在可能的情況下使用它，並在連線時（參見 COMMANDS 下的 connect 命令）如果輔助程式請求則回退到其他功能。在 push 和 export 之間選擇時，Git 優先使用 push。其他前端可能有不同的偏好順序。

no-private-update

在使用 refspec 功能時，git 通常會在成功推送後更新私有引用。當遠端輔助程式宣告 no-private-update 功能時，此更新將被停用。

獲取功能

connect

可以嘗試連線到 git upload-pack（用於獲取）、git receive-pack 等，以便使用 Git 的原生 packfile 協議進行通訊。這需要雙向全雙工連線。

支援的命令：connect。

stateless-connect

實驗性功能；僅供內部使用。可以嘗試連線到遠端伺服器，以便使用 Git 的 wire-protocol 版本 2 進行通訊。有關 stateless-connect 命令的更多資訊，請參閱文件。

支援的命令：stateless-connect。

fetch

可以發現遠端引用並將可從它們到達的物件傳輸到本地物件儲存。

支援的命令：list、fetch。

import

可以發現遠端引用並將可從它們到達的物件以 fast-import 格式的流輸出。

支援的命令：list、import。

check-connectivity

可以保證在請求克隆時，接收到的 pack 檔案是獨立的且已連線。

get

可以使用 get 命令從給定 URI 下載檔案。

如果輔助程式聲明瞭 connect，Git 將在可能的情況下使用它，並在連線時（參見 COMMANDS 下的 connect 命令）如果輔助程式請求則回退到其他功能。在 fetch 和 import 之間選擇時，Git 優先使用 fetch。其他前端可能有不同的偏好順序。

雜項功能

option

用於指定如 verbosity（向 stderr 寫入多少輸出）和 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-blob 和 ls 可供遠端輔助程式使用，以檢索 fast-import 記憶體中已存在的 blob 和 tree 的資訊。這需要一個從 fast-import 到遠端輔助程式的通道。如果它與“import”一起宣告，Git 將建立一個從 fast-import 到遠端輔助程式 stdin 的管道。因此，Git 和 fast-import 都連線到遠端輔助程式的 stdin。由於 Git 可以向遠端輔助程式傳送多個命令，因此要求使用 bidi-import 的輔助程式在將資料傳送到 fast-import 之前緩衝批處理的所有 import 命令。這是為了防止命令和 fast-import 響應在輔助程式的 stdin 上混淆。

export-marks <file>

此功能修改了 export 功能，指示 Git 在完成後將內部 marks 錶轉儲到 <file>。有關詳細資訊，請參閱 git-fast-export[1] 中的 --export-marks=<file>。

import-marks <file>

此功能修改了 export 功能，指示 Git 在處理任何輸入之前載入 <file> 中指定的 marks。有關詳細資訊，請參閱 git-fast-export[1] 中的 --import-marks=<file>。

signed-tags

此功能修改了 export 功能，指示 Git 將 --signed-tags=verbatim 傳遞給 git-fast-export[1]。如果缺少此功能，Git 將使用 --signed-tags=warn-strip。

object-format

這表明輔助程式能夠使用顯式的雜湊演算法擴充套件與遠端端進行互動。

命令

命令由呼叫者透過輔助程式的標準輸入傳送，每行一個。

capabilities

列出輔助程式的功能，每行一個，以空行結尾。每個功能前面可能有一個 *，這表示 Git 使用遠端輔助程式進行理解的版本必須理解這些功能。任何未知的強制功能都是致命錯誤。

支援此命令是強制性的。

list

列出引用，每行一個，格式為“<value> <name> [<attr> …​]”。值可以是十六進位制 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> 對其無效）。選項應在其他命令之前設定，並且可能會影響這些命令的行為。

有關當前定義的選項列表，請參閱 OPTIONS。

如果輔助程式具有“option”功能，則支援此命令。

fetch <sha1> <name>

獲取指定的物件，將必要的物件寫入資料庫。Fetch 命令以批處理方式傳送，每行一個，以空行結束。當同一批次中的所有 fetch 命令完成後，輸出一個空行。只能透過這種方式獲取在 list 命令的輸出中用 sha1 報告的物件。

可選地，可以輸出一行 lock <file>，指示 $GIT_DIR/objects/pack 下用於在引用被適當地更新之前保持 pack 檔案的完整路徑。路徑必須以 .keep 結尾。這是一種透過僅提供 keep 元件來命名 <pack,idx,keep> 元組的機制。即使其物件在 fetch 完成之前可能未被引用，kept pack 也不會被併發的 repack 刪除。fetch 完成時將刪除 .keep 檔案。

如果請求了 check-connectivity 選項，如果克隆是獨立的且已連線，則輔助程式必須輸出 connectivity-ok。

如果輔助程式具有“fetch”功能，則支援此命令。

push +<src>:<dst>

將給定的本地 <src> commit 或 branch 推送到由 <dst> 描述的遠端 branch。一系列一個或多個 push 命令以空行結束（如果只有一個引用要推送，則單個 push 命令後跟一個空行）。例如，以下將是兩個 push 批處理，第一個要求遠端輔助程式將本地引用 master 推送到遠端引用 master 以及本地 HEAD 推送到遠端 branch，第二個要求將引用 foo 推送到引用 bar（由 + 請求強制更新）。

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

在批次的最後一個 push 命令之後、批次終止空行之前，可以輸入零個或多個協議選項。

推送完成後，輸出一行或多行 ok <dst> 或 error <dst> <why>? 以指示每個推送引用的成功或失敗。狀態報告輸出以空行結束。如果 <why> 欄位包含 LF，則可以使用 C 風格字串進行引用。

如果輔助程式具有“push”功能，則支援此命令。

import <name>

生成一個 fast-import 流，該流匯入命名引用的當前值。它還可以匯入其他必要的引用以高效地構建歷史。指令碼寫入輔助程式特定的私有名稱空間。命名引用的值應寫入此名稱空間中的一個位置，該位置是透過將“refspec”功能的 refspec 應用於引用名稱派生而來的。

尤其適用於與外部版本控制系統進行互操作。

與 push 類似，一系列一個或多個 import 命令以空行結束。對於每個 import 批處理，遠端輔助程式應生成一個 fast-import 流，該流以 done 命令結束。

請注意，如果使用了 bidi-import 功能，則必須在開始將資料傳送到 fast-import 之前緩衝完整的批處理序列，以防止命令和 fast-import 響應在輔助程式的 stdin 上混淆。

如果輔助程式具有“import”功能，則支援此命令。

export

指示遠端輔助程式，任何後續輸入都是 fast-import 流（由 git fast-export 生成）的一部分，其中包含應推送到遠端的物件。

尤其適用於與外部版本控制系統進行互操作。

export-marks 和 import-marks 功能（如果已指定）會影響此命令，因為它們會被傳遞給 git fast-export，然後後者將載入/儲存本地物件的 marks 表。這可用於實現增量操作。

如果輔助程式具有“export”功能，則支援此命令。

connect <service>

連線到指定的服務。輔助程式的標準輸入和標準輸出連線到遠端端的指定服務（git 字首包含在服務名稱中，例如獲取使用 git-upload-pack 作為服務）。此命令的有效響應為空行（連線已建立）、fallback（沒有智慧傳輸支援，回退到啞傳輸）以及僅顯示錯誤訊息並退出（無法連線，不要嘗試回退）。在終止正面（空）響應的換行符之後，將開始顯示服務的輸出。連線結束後，遠端輔助程式退出。

如果輔助程式具有“connect”功能，則支援此命令。

stateless-connect <service>

實驗性功能；僅供內部使用。連線到指定的遠端服務，以便使用 Git 的 wire-protocol 版本 2 進行通訊。此命令的有效響應為空行（連線已建立）、fallback（沒有智慧傳輸支援，回退到啞傳輸）以及僅顯示錯誤訊息並退出（無法連線，不要嘗試回退）。在終止正面（空）響應的換行符之後，將開始顯示服務的輸出。訊息（請求和響應）必須由零個或多個 PKT-LINE 組成，並以 flush packet 結束。響應訊息在 flush packet 之後將有一個 response end packet，以指示響應的結束。客戶端不得期望伺服器在請求-響應對之間儲存任何狀態。連線結束後，遠端輔助程式退出。

如果輔助程式具有“stateless-connect”功能，則支援此命令。

get <uri> <path>

將檔案從給定的 <uri> 下載到給定的 <path>。如果 <path>.temp 存在，則 Git 假定 .temp 檔案是先前嘗試的下載的未完成部分，並將從該位置恢復下載。

如果發生致命錯誤，程式會將錯誤訊息寫入 stderr 並退出。呼叫者應預期，如果子程序在未完成當前命令的有效響應的情況下關閉連線，則已打印合適的錯誤訊息。

可能支援其他命令，具體取決於輔助程式報告的功能。

引用列表屬性

list 命令生成一個引用列表，其中每個引用後面可能跟一個屬性列表。以下引用列表屬性已定義。

unchanged

此引用自上次匯入或獲取以來未發生更改，儘管輔助程式不一定能確定是哪個值產生了此結果。

引用列表關鍵字

list 命令可以生成鍵值對列表。以下關鍵字已定義。

object-format

引用使用給定的雜湊演算法。此關鍵字僅在伺服器和客戶端都支援 object-format 擴充套件時使用。

選項

以下選項已定義，並在（在適當的情況下）由 Git 設定，如果遠端輔助程式具有 option 功能。

option verbosity <n>

更改輔助程式顯示的郵件的詳細程度。0 表示 <n>，意味著程序安靜地執行，並且輔助程式僅產生錯誤輸出。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}

如果啟用，輔助程式應自動獲取帶註釋的 tag 物件，前提是 tag 指向的物件在 fetch 命令期間被傳輸。如果輔助程式未獲取 tag，通常會發送第二個 fetch 命令來專門請求該 tag。某些輔助程式可以使用此選項來避免第二次網路連線。

option dry-run {true|false}

如果為 true，則假裝操作成功完成，但實際上不更改任何儲存庫資料。對於大多數輔助程式，這僅適用於 push（如果受支援）。

option servpath <c-style-quoted-path>

設定下一個 connect 請求的服務路徑（--upload-pack、--receive-pack 等）。遠端輔助程式可能支援此選項，但不應依賴於在 connect 請求發生之前設定此選項。

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}

表示這些物件是從 promisor 獲取的。

option no-dependents {true|false}

表示只需要獲取所需的那些物件，而不需要它們的依賴項。

option atomic {true|false}

推送時，請求遠端伺服器在一個原子事務中更新引用。如果成功，所有引用都將被更新；否則，一個都不會。如果遠端端不支援此功能，則推送將失敗。

option object-format true

表示呼叫者希望將雜湊演算法資訊從遠端端傳回。此模式在獲取引用時使用。

另請參閱

git-remote[1]

git-remote-ext[1]

git-remote-fd[1]

git-fast-import[1]

GIT

Git[1] 套件的一部分