簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitremote-helpers 最後更新於 2.45.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 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 命令的響應中宣告給 Git（見下面的 COMMANDS）。

在下文中，我們列出了所有定義的功能，併為每個功能列出了具有該功能的輔助程式必須提供的命令。

推送功能

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 將盡可能使用它；如果輔助程式在連線時請求回退（參見 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 的線協議版本 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 命令。這是為了防止在輔助程式的 stdin 上混合命令和 fast-import 響應。

export-marks <file>

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

import-marks <file>

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

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 雜湊值，symref 的“@<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>

抓取給定物件，將必要的物件寫入資料庫。抓取命令以批處理方式傳送，每行一個，以空行終止。當同一批次中的所有抓取命令完成後，輸出一個空行。只有在 list 輸出中報告了 SHA1 的物件才能以這種方式抓取。

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

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

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

push +<src>:<dst>

將給定的本地 <src> 提交或分支推送到 <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 響應在輔助程式的 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 組成，以 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 擴充套件時使用。

選項

如果遠端輔助程式具有 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}

如果啟用，輔助程式應在抓取命令期間傳輸標籤指向的物件時，自動抓取帶註釋的標籤物件。如果輔助程式未抓取標籤，通常會發送第二個抓取命令以專門請求該標籤。一些輔助程式可能能夠使用此選項來避免第二次網路連線。

option dry-run {true|false}：如果為 true，則假裝操作成功完成，但實際上不更改任何倉庫資料。對於大多數輔助程式，這僅適用於 push（如果支援）。

option servpath <c-style-quoted-path>

為下一次連線設定服務路徑（--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] 套件的一部分

scroll-to-top