Git
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-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> 是其無法原生處理的協定，它會自動使用完整 URL 作為第二個引數叫用 git remote-<transport>。如果直接在命令列上遇到這類 URL，則第一個引數會與第二個引數相同；如果在已設定的遠端中遇到，則第一個引數會是該遠端的名稱。

<transport>::<address> 格式的 URL 會明確指示 Git 使用 <address> 作為第二個引數叫用 git remote-<transport>。如果直接在命令列上遇到這類 URL，則第一個引數會是 <address>；如果在已設定的遠端中遇到，則第一個引數會是該遠端的名稱。

此外，當設定的遠端的 remote.<name>.vcs 設定為 <transport> 時，Git 會明確使用 <name> 作為第一個引數叫用 git remote-<transport>。如果已設定，則第二個引數會是 remote.<name>.url；否則會省略第二個引數。

輸入格式

Git 會在標準輸入上向遠端輔助程式傳送命令清單，每行一個命令。第一個命令永遠是 capabilities 命令，遠端輔助程式必須列印其支援的功能清單 (請參閱下方)，然後列印空白行作為回應。對 capabilities 命令的回應會決定 Git 在命令串流的其餘部分中使用的命令。

命令串流會以空白行終止。在某些情況下 (相關命令的文件中會指出)，此空白行後面會接著某個其他協定 (例如 pack 協定) 中的酬載，而在其他情況下，它則表示輸入結束。

功能

每個遠端輔助程式預期只支援部分命令。輔助程式支援的操作會在對 capabilities 命令的回應中向 Git 宣告 (請參閱下方的命令)。

在以下內容中，我們列出所有已定義的功能，並針對每個功能列出具有該功能的輔助程式必須提供的命令。

推送的功能

connect

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

支援的命令：connect。

stateless-connect

實驗性；僅供內部使用。可以嘗試連線到遠端伺服器，以便使用 Git 的線路協定版本 2 進行通訊。如需詳細資訊，請參閱 stateless-connect 命令的文件。

支援的命令：stateless-connect。

push

可以探索遠端參考，並將本機提交和導致這些提交的歷程記錄推送至新的或現有的遠端參考。

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

export

可以探索遠端參考，並將 fast-import 串流中指定的物件推送至遠端參考。

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

如果輔助程式宣告 connect，Git 會盡可能使用它，並在輔助程式連線時要求時，回復到其他功能 (請參閱命令下的 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 的線路協定版本 2 進行通訊。如需詳細資訊，請參閱 stateless-connect 命令的文件。

支援的命令：stateless-connect。

fetch

可以探索遠端參考，並將從這些參考可存取的物件傳輸到本機物件儲存區。

支援的命令：list、fetch。

import

可以探索遠端參考，並以 fast-import 格式的串流輸出從這些參考可存取的物件。

支援的命令：list、import。

check-connectivity

可以保證當要求複製時，接收到的 pack 是獨立且已連線的。

get

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

如果輔助程式宣告 connect，Git 會盡可能使用它，並在輔助程式連線時要求時，回復到其他功能 (請參閱命令下的 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 和樹狀結構的相關資訊。這需要從 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=verbatim 傳遞給 git-fast-export[1]。如果沒有此功能，Git 將使用 --signed-tags=warn-strip。

object-format

這表示輔助程式能夠使用明確的雜湊演算法擴充功能與遠端端互動。

命令

呼叫者會在輔助程式的標準輸入上提供命令，每行一個命令。

capabilities

列出輔助程式的功能，每行一個功能，並以空白行結尾。每個功能前面可能會加上 *，這表示它們對於使用遠端輔助程式理解的 Git 版本來說是強制性的。任何未知的強制功能都是致命錯誤。

此命令的支援是強制性的。

list

以 "<value> <name> [<attr> …​]" 的格式列出參考，每行一個。該值可以是十六進制 sha1 雜湊值、符號參考的 "@<dest>"、鍵值對的 ":<keyword> <value>"，或是 "?" 表示輔助程式無法取得參考的值。名稱後面會跟隨以空格分隔的屬性列表；無法識別的屬性會被忽略。列表以空白行結尾。

請參閱參考列表屬性以取得目前定義的屬性列表。請參閱參考列表關鍵字以取得目前定義的關鍵字列表。

如果輔助程式具有 "fetch" 或 "import" 功能，則支援此功能。

list for-push

與 list 類似，不同之處在於，只有當呼叫者希望使用產生的參考列表來準備推送命令時才會使用它。同時支援推送和提取的輔助程式可以使用它來區分 list 的輸出將用於哪個操作，從而可能減少需要執行的工作量。

如果輔助程式具有 "push" 或 "export" 功能，則支援此功能。

option <name> <value>

將傳輸輔助程式選項 <name> 設定為 <value>。輸出包含 ok（選項設定成功）、unsupported（無法識別選項）或 error <msg>（支援選項 <name>，但 <value> 對其無效）的單行。選項應在其他命令之前設定，並且可能會影響這些命令的行為。

請參閱選項以取得目前定義的選項列表。

如果輔助程式具有 "option" 功能，則支援此功能。

fetch <sha1> <name>

提取給定的物件，並將必要的物件寫入資料庫。提取命令會分批發送，每行一個命令，並以空白行終止。當同一批次中的所有提取命令都完成時，會輸出單個空白行。只有在 list 的輸出中報告具有 sha1 的物件才能以此方式提取。

或者，可能會輸出 lock <file> 行，指出 $GIT_DIR/objects/pack 下的檔案完整路徑，該檔案會保留一個包，直到可以適當地更新參考。路徑必須以 .keep 結尾。這是一種僅透過提供 keep 元件來命名 <pack,idx,keep> 元組的機制。即使在提取完成之前可能沒有引用其物件，已保留的包也不會被並發重新打包刪除。.keep 檔案將在提取結束時刪除。

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

如果輔助程式具有 "fetch" 功能，則支援此功能。

push +<src>:<dst>

將給定的本地 <src> commit 或分支推送到 <dst> 所述的遠端分支。一個或多個 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 批次，遠端輔助程式應產生一個以 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（不支援智慧型傳輸，回退到啞傳輸）以及僅列印錯誤訊息退出（無法連線，不用嘗試回退）。在終止肯定（空）回應的換行符號之後，服務的輸出開始。訊息（請求和回應）必須包含零個或多個 PKT-LINE，並以刷新資料包終止。然後，回應訊息會在刷新資料包後有一個回應結束資料包，以指示回應結束。用戶端不得期望伺服器在請求-回應對之間儲存任何狀態。連線結束後，遠端輔助程式會退出。

如果輔助程式具有 "stateless-connect" 功能，則支援此功能。

get <uri> <path>

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

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

可能會支援其他命令，這可以從輔助程式報告的功能中確定。

參考列表屬性

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>

加深淺層儲存庫的歷史記錄，排除指定的 ref。多個選項會累加。

option deepen-relative {true|false}

相對於當前邊界加深淺層儲存庫的歷史記錄。僅在與 "option depth" 一起使用時有效。

option followtags {true|false}

如果啟用，當標籤指向的物件在 fetch 命令期間傳輸時，輔助程式應自動提取已註解的標籤物件。如果輔助程式沒有提取標籤，通常會發送第二個 fetch 命令來特別要求該標籤。某些輔助程式可以使用此選項來避免第二個網路連線。

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 簽署推送。

option push-option <string>

傳輸 <string> 作為推送選項。由於推送選項不能包含 LF 或 NUL 字元，因此字串不會被編碼。

option from-promisor {true|false}

表示這些物件正在從承諾者提取。

option no-dependents {true|false}

表示只需要提取需要的物件，不需要提取它們的依賴項。

option atomic {true|false}

在推送時，請求遠端伺服器在單一原子交易中更新 ref。如果成功，所有 ref 都將被更新，否則都不會更新。如果遠端不支援此功能，則推送將會失敗。

option object-format true

表示呼叫者希望從遠端傳回雜湊演算法資訊。此模式用於提取 ref 時。

參見

git-remote[1]

git-remote-ext[1]

git-remote-fd[1]

git-fast-import[1]

GIT

屬於 git[1] 套件的一部分

scroll-to-top