命名

gitremote-helpers  - 幫助程序與遠(yuǎn)程存儲(chǔ)庫(kù)進(jìn)行交互

概要

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

描述

遠(yuǎn)程幫助程序通常不是由最終用戶(hù)直接使用，但當(dāng)它需要與遠(yuǎn)程存儲(chǔ)庫(kù)交互時(shí)，它們由 Git 調(diào)用。Git 本身不支持。給定的幫助程序?qū)?shí)現(xiàn)此處記錄的功能的子集。當(dāng) Git 需要使用遠(yuǎn)程助手與存儲(chǔ)庫(kù)進(jìn)行交互時(shí)，它會(huì)將助手作為獨(dú)立進(jìn)程產(chǎn)生，將命令發(fā)送給助手的標(biāo)準(zhǔn)輸入，并期望助手的標(biāo)準(zhǔn)輸出結(jié)果。因?yàn)檫h(yuǎn)程助手作為獨(dú)立于 Git 的進(jìn)程運(yùn)行，所以不需要重新鏈接 Git 來(lái)添加新的助手，也不需要將助手與 Git 的實(shí)現(xiàn)鏈接起來(lái)。

每個(gè)助手必須支持 “capabilities” 命令，Git 使用它來(lái)確定助手將接受的其他命令。這些其他命令可用于發(fā)現(xiàn)和更新遠(yuǎn)程參考，在對(duì)象數(shù)據(jù)庫(kù)和遠(yuǎn)程存儲(chǔ)庫(kù)之間傳輸對(duì)象，并更新本地對(duì)象存儲(chǔ)。

Git 自帶了遠(yuǎn)程助手，是處理各種傳輸協(xié)議，如的“curl”的家庭git-remote-http，git-remote-https，git-remote-ftp和git-remote-ftps。他們實(shí)現(xiàn)fetch，option和push這些功能。

調(diào)用

使用一個(gè)或（可選）兩個(gè)參數(shù)調(diào)用遠(yuǎn)程幫助程序。第一個(gè)參數(shù)和 Git 一樣指定一個(gè)遠(yuǎn)程倉(cāng)庫(kù); 它是配置的遠(yuǎn)程或 URL 的名稱(chēng)。第二個(gè)參數(shù)指定一個(gè) URL ; 它通常是這種形式<transport>://<address>，但任何字符串都是可能的。該GIT_DIR環(huán)境變量是為遠(yuǎn)程助手設(shè)置的，可用于確定在哪里存儲(chǔ)其他數(shù)據(jù)或從哪個(gè)目錄調(diào)用輔助 Git 命令。

當(dāng) Git 遇到一個(gè)表單的 URL  <transport>://<address>，其中<transport>是一個(gè)它本身無(wú)法處理的協(xié)議，它會(huì)自動(dòng)調(diào)用git remote-<transport>完整的 URL 作為第二個(gè)參數(shù)。如果直接在命令行中遇到這樣的 URL ，那么第一個(gè)參數(shù)與第二個(gè)參數(shù)相同，如果在配置的遠(yuǎn)程中遇到，則第一個(gè)參數(shù)是該遠(yuǎn)程的名稱(chēng)。

該表單的 URL  <transport>::<address>明確指示 Git  git remote-<transport>使用<address>第二個(gè)參數(shù)。如果在命令行上直接遇到這樣的 URL ，那么第一個(gè)參數(shù)是<address>，如果在配置的遠(yuǎn)程中遇到，則第一個(gè)參數(shù)是該遠(yuǎn)程的名稱(chēng)。

另外，當(dāng)配置的遠(yuǎn)程已經(jīng)remote.<name>.vcs設(shè)置為<transport>，GIT 中明確地調(diào)用git remote-<transport>與<name>作為第一個(gè)參數(shù)。如果設(shè)置，第二個(gè)參數(shù)是remote.<name>.url; 否則，第二個(gè)參數(shù)被省略。

輸入格式

Git 向標(biāo)準(zhǔn)輸入發(fā)送遠(yuǎn)程助手的命令列表，每行一個(gè)。第一個(gè)命令總是capabilities命令，作為響應(yīng)，遠(yuǎn)程助手必須打印它所支持的功能列表（見(jiàn)下文），后面跟著一個(gè)空行。對(duì) capabilities 命令的響應(yīng)決定了 Git 在其余命令流中使用的命令。

命令流由空行終止。在某些情況下（在相關(guān)命令的文檔中指出），該空行后面是其他協(xié)議中的有效載荷（例如包協(xié)議），而在其他情況下則表示輸入結(jié)束。

功能

預(yù)計(jì)每個(gè)遠(yuǎn)程助手只支持一部分命令。輔助程序支持的操作在對(duì)capabilities命令的響應(yīng)中聲明為 Git （請(qǐng)參見(jiàn)下面的 COMMANDS ）。

在下文中，我們列出了所有已定義的功能，并為每個(gè)列出了具有該功能的助手必須提供的命令。

推動(dòng)能力

connect

可以嘗試使用 git 的本機(jī) packfile 協(xié)議連接git receive-pack（推送）git upload-pack等通信。這需要雙向全雙工連接。

支持的命令：connect。

push

可以發(fā)現(xiàn)遠(yuǎn)程引用，并將本地提交以及引導(dǎo)給它們的歷史推送到新的或現(xiàn)有的遠(yuǎn)程引用。

支持的命令：list for-push，push。

export

可以發(fā)現(xiàn)遠(yuǎn)程引用，并將快速導(dǎo)入流中的指定對(duì)象推送到遠(yuǎn)程引用。

支持的命令：list for-push，export。

如果給connect打廣告，Git 將盡可能使用它，如果助手在連接時(shí)請(qǐng)求，則會(huì)回退到另一個(gè)能力（請(qǐng)參閱connect COMMANDS 下的命令）。當(dāng)選擇push和export，Git 喜歡push。其他前端可能有其他一些優(yōu)先順序。

no-private-update

在使用該refspec功能時(shí)，git 通常會(huì)在成功推送時(shí)更新私有的參考。當(dāng) remote-helper 聲明能力時(shí)，此更新被禁用no-private-update。

提取能力

connect

可以嘗試使用 Git 的本機(jī) packfile 協(xié)議連接git upload-pack（用于讀?。?code>git receive-pack等。這需要雙向全雙工連接。

支持的命令：connect。

fetch

可以發(fā)現(xiàn)遠(yuǎn)程引用并將可從其訪問(wèn)的對(duì)象傳輸?shù)奖镜貙?duì)象存儲(chǔ)區(qū)。

Supported commands: list, fetch.

import

可以發(fā)現(xiàn)遠(yuǎn)程引用并將它們可訪問(wèn)的對(duì)象以快速導(dǎo)入格式輸出為流。

支持的命令：list，import。

check-connectivity

可以保證在請(qǐng)求 clone 時(shí)，收到的包是自包含的并且已連接。

如果 helper 做廣告connect，Git 將盡可能使用它，如果助手在連接時(shí)請(qǐng)求，則會(huì)回退到另一個(gè)能力（請(qǐng)參閱connect COMMANDS 下的命令）。當(dāng)選擇fetch和import，Git 喜歡fetch。其他前端可能有其他一些優(yōu)先順序。

雜項(xiàng)功能

option

用于指定像verbosity（寫(xiě)入 stderr 的輸出量有多少）和depth（對(duì)淺克隆而言需要多少歷史記錄）等影響其他命令執(zhí)行的設(shè)置。

refspec <refspec>

對(duì)于實(shí)現(xiàn)import或者的遠(yuǎn)程助手export，這個(gè)功能允許 refs 被限制到一個(gè)私有名稱(chēng)空間，而不是直接寫(xiě)入 refs / heads 或者 ref / remotes 。建議所有提供此import功能的進(jìn)口商都使用此功能。這是強(qiáng)制性的export。

refspec refs/heads/*:refs/svn/origin/branches/*，當(dāng)它被要求時(shí)import refs/heads/topic，它輸出的流將更新refs/svn/origin/branches/topic參考。

此功能可以被多次建議。第一個(gè)適用的 refspec 優(yōu)先。使用此功能宣傳的 refspecs 的左側(cè)必須覆蓋 list 命令報(bào)告的所有參考。如果沒(méi)有refspec能力被宣傳，那就暗示了refspec *:*。

當(dāng)為分散版本控制系統(tǒng)編寫(xiě) remote-helpers 時(shí)，建議保留一個(gè)本地的版本庫(kù)副本進(jìn)行交互，并讓私有命名空間參考指向這個(gè)本地版本庫(kù)，而 refs / remotes 命名空間用于跟蹤遠(yuǎn)程存儲(chǔ)庫(kù)。

bidi-import

這改變了import能力。快速導(dǎo)入命令cat-blob，ls遠(yuǎn)程助手可以使用該命令來(lái)檢索快速導(dǎo)入內(nèi)存中已存在的斑點(diǎn)和樹(shù)的信息。這需要一個(gè)從快速導(dǎo)入到遠(yuǎn)程助手的通道。如果除了“導(dǎo)入”之外還公布了它，Git 將建立一個(gè)從快速導(dǎo)入到遠(yuǎn)程助手 stdin 的管道。因此，Git 和快速導(dǎo)入都連接到遠(yuǎn)程助手的 stdin 。因?yàn)?Git 可以向遠(yuǎn)程幫助器發(fā)送多個(gè)命令，所以需要使用bidi-import緩沖區(qū)的幫助器import在發(fā)送數(shù)據(jù)到快速導(dǎo)入之前使用緩沖區(qū)的所有命令。這是為了防止在助手的 stdin 上混合命令和快速導(dǎo)入響應(yīng)。

export-marks <file>

這會(huì)修改該export功能，指示 Git 在完成時(shí)將內(nèi)部標(biāo)記表轉(zhuǎn)儲(chǔ)到 <file> 。有關(guān)詳細(xì)信息，請(qǐng)閱讀--export-marks=<file>git-fast-export [1]。

import-marks <file>

這會(huì)修改該export功能，指示 Git 在處理任何輸入之前加載 <file> 中指定的標(biāo)記。有關(guān)詳細(xì)信息，請(qǐng)閱讀--import-marks=<file> git-fast-export [1] 。

signed-tags

這會(huì)修改該export功能，指示 Git 傳遞--signed-tags=verbatim給 git-fast-export [1] 。在沒(méi)有這種能力的情況下，Git 會(huì)使用--signed-tags=warn-strip。

命令

命令由調(diào)用者在助手的標(biāo)準(zhǔn)輸入中給出，每行一個(gè)。

capabilities

列出助手的功能，每行一個(gè)，以空行結(jié)束。每個(gè)功能都可以使用*，這標(biāo)志著它們對(duì)于使用遠(yuǎn)程幫助程序理解的 Git 版本是強(qiáng)制性的。任何未知的強(qiáng)制性能力都是致命的錯(cuò)誤。

對(duì)此命令的支持是強(qiáng)制性的。

list

以 “<value> <name> <attr> ...” 格式列出每行一個(gè)參考。值可以是一個(gè)十六進(jìn)制 sha1 散列，“@ <dest>” 用于 symref或 “？” 以表明助手無(wú)法獲得參考價(jià)值。名稱(chēng)后面有空格分隔的屬性列表; 無(wú)法識(shí)別的屬性被忽略。該列表以空行結(jié)束。

有關(guān)當(dāng)前定義的屬性的列表，請(qǐng)參閱 REF LIST ATTRIBUTES 。

如果助手具有“獲取”或“導(dǎo)入”功能，則受支持。

list for-push

list與之類(lèi)似，只是當(dāng)且僅當(dāng)調(diào)用者想要生成的引用列表準(zhǔn)備推送命令時(shí)才使用它。同時(shí)支持 push 和 fetch 的助手可以使用它來(lái)區(qū)分list將要使用輸出的操作，可能會(huì)減少需要執(zhí)行的工作量。

如果助手具有“推送”或“導(dǎo)出”功能，則支持該功能。

option <name> <value>

將傳輸助手選項(xiàng) <name> 設(shè)置為 <value> 。輸出包含ok（選項(xiàng)成功設(shè)置），unsupported（選項(xiàng)無(wú)法識(shí)別）和error <msg>（選項(xiàng) <name> 支持但 <value> 無(wú)效）之一的單行。選項(xiàng)應(yīng)在其他命令之前設(shè)置，并可能影響這些命令的行為。

請(qǐng)參閱選項(xiàng)以獲取當(dāng)前定義的選項(xiàng)列表。

如果助手具有“選項(xiàng)”功能則支持。

fetch <sha1> <name>

獲取給定的對(duì)象，將必要的對(duì)象寫(xiě)入數(shù)據(jù)庫(kù)。提取命令以批處理形式發(fā)送，每行一個(gè)，以空行結(jié)束。當(dāng)同一批次中的所有提取命令都完成時(shí)，輸出一個(gè)空白行。只有在list sha1 的輸出中報(bào)告的對(duì)象可以通過(guò)這種方式獲取。

也可以輸出一個(gè)lock <file>指示 GIT_DIR / objects / pack 下的文件的行，該文件保持一個(gè)包，直到 ref 可以被適當(dāng)?shù)馗隆?/p>

如果check-connectivity請(qǐng)求了選項(xiàng)，connectivity-ok如果克隆是自包含并連接的，則助手必須輸出。

如果助手具有“獲取”功能，則受支持。

push +<src>:<dst>

將給定的本地 <src> 提交或分支推送到由 <dst> 描述的遠(yuǎn)程分支。一個(gè)或多個(gè)push命令的批處理序列以空行結(jié)束（如果只有一個(gè)引用來(lái)推送，則單個(gè)push命令后面跟著一個(gè)空行）。例如，下面是兩批push，第一批要求 remote-helper 將本地 ref推master送到遠(yuǎn)程 ref master，將本地 ref 推HEAD送到遠(yuǎn)程branch，第二批要求將 ref 推入fooref bar（由該請(qǐng)求強(qiáng)制更新+） 。

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

最后一個(gè)push命令之后，在批次的終止空白行之前可以輸入零個(gè)或多個(gè)協(xié)議選項(xiàng)。

當(dāng)推送完成時(shí)，輸出一個(gè)或多個(gè)ok <dst>或error <dst> <why>?線路以指示每個(gè)推送參考的成功或失敗。狀態(tài)報(bào)告輸出以空行結(jié)束。如果選項(xiàng)字段包含 LF，則可以用 C 風(fēng)格字符串引用該選項(xiàng)字段。

如果助手具有 "push" 功能則支持。

import <name>

生成一個(gè)快速導(dǎo)入的流，導(dǎo)入指定 ref 的當(dāng)前值。它還可以根據(jù)需要額外導(dǎo)入其他參考以高效地構(gòu)建歷史記錄。腳本寫(xiě)入助手特定的私有名稱(chēng)空間。named ref 的值應(yīng)寫(xiě)入此名稱(chēng)空間中的一個(gè)位置，該位置通過(guò)將 refspecs 從 “refspec” 功能應(yīng)用到 ref 的名稱(chēng)而得出。

特別適用于與外部版本控制系統(tǒng)的互操作性。

就像push，一個(gè)或多個(gè)批處理序列import以空行結(jié)束。對(duì)于每一批import，遠(yuǎn)程助手應(yīng)該產(chǎn)生一個(gè)由done命令終止的快速導(dǎo)入流。

請(qǐng)注意，如果使用了bidi-import功能，則在開(kāi)始發(fā)送數(shù)據(jù)以進(jìn)行快速導(dǎo)入之前，必須緩沖完整的批處理序列，以防止在幫助器的 stdin 上混合命令和快速導(dǎo)入響應(yīng)。

如果助手具有 "import" 功能則支持。

export

指示遠(yuǎn)程助手任何后續(xù)輸入都是快速導(dǎo)入流（由生成的git fast-export）的一部分，該流包含應(yīng)推送到遠(yuǎn)程的對(duì)象。

特別適用于與外部版本控制系統(tǒng)的互操作性。

如果指定了這些export-marks和import-marks功能，只要它們被傳遞到git fast-export，就會(huì)影響此命令，然后它會(huì)為本地對(duì)象加載/存儲(chǔ)一個(gè)標(biāo)記表。這可以用于執(zhí)行增量操作。

如果助手具有“導(dǎo)出”功能則支持。

connect <service>

連接到給定的服務(wù)。幫助器的標(biāo)準(zhǔn)輸入和標(biāo)準(zhǔn)輸出連接到指定服務(wù)（git 前綴包含在服務(wù)名稱(chēng)中，例如，git-upload-pack作為服務(wù)提取使用）在遠(yuǎn)程端。對(duì)此命令的有效答復(fù)是空行（已建立連接），fallback（不支持智能傳輸支持，退回到啞傳輸），并且僅在退出時(shí)顯示錯(cuò)誤消息（無(wú)法連接，請(qǐng)勿嘗試退回）。在換行終止正（空）響應(yīng)后，服務(wù)輸出開(kāi)始。連接結(jié)束后，遠(yuǎn)程助手退出。

如果助手具有 "connect" 功能則支持。

如果發(fā)生致命錯(cuò)誤，程序會(huì)將錯(cuò)誤消息寫(xiě)入 stderr 并退出。如果孩子關(guān)閉連接而未完成當(dāng)前命令的有效響應(yīng)，則調(diào)用者應(yīng)該期望已經(jīng)打印出合適的錯(cuò)誤消息。

可以支持附加的命令，這可以從助手報(bào)告的能力中確定。

參考列表屬性

該list命令產(chǎn)生一個(gè) ref 列表，其中每個(gè) ref 可以后跟一個(gè)屬性列表。定義了以下參考列表屬性。

unchanged

該引用自上次導(dǎo)入或提取后不變，但助手不一定能確定產(chǎn)生的值。

選項(xiàng)

如果遠(yuǎn)程助手有option能力，則定義以下選項(xiàng)并在 Git 中設(shè)置（在適當(dāng)?shù)那闆r下）。

option verbosity <n>

更改助手顯示的消息的詳細(xì)程度。<n> 的值為0，意味著進(jìn)程安靜地運(yùn)行，并且助手只產(chǎn)生錯(cuò)誤輸出。1是默認(rèn)的詳細(xì)級(jí)別，更高的值 <n> 對(duì)應(yīng)于在命令行上傳遞的 -v 標(biāo)志的數(shù)量。

option progress {true|false}

啟用（或禁用）傳輸助手在命令期間顯示的進(jìn)度消息。

option depth <depth>

深化淺層知識(shí)庫(kù)的歷史。

'option deepen-since <timestamp>

基于時(shí)間來(lái)加深淺層知識(shí)庫(kù)的歷史。

'option deepen-not <ref>

加深不包括參考文獻(xiàn)的淺儲(chǔ)藏庫(kù)的歷史。多個(gè)選項(xiàng)加起來(lái)。

option deepen-relative {'true|false}

相對(duì)于當(dāng)前的邊界，加深了淺倉(cāng)庫(kù)的歷史。僅在與“選項(xiàng)深度”一起使用時(shí)才有效。

option followtags {true|false}

如果啟用，助手應(yīng)自動(dòng)獲取帶注釋的標(biāo)簽對(duì)象，如果標(biāo)簽指向的對(duì)象在獲取命令期間被傳送。如果標(biāo)簽沒(méi)有被助手獲取，通常會(huì)發(fā)送第二個(gè)獲取命令來(lái)特別要求標(biāo)簽。一些助手可能能夠使用此選項(xiàng)來(lái)避免第二次網(wǎng)絡(luò)連接。

option dry-run{ true| false}：如果為 true ，則假裝操作成功完成，但實(shí)際上并未更改任何存儲(chǔ)庫(kù)數(shù)據(jù)。對(duì)于大多數(shù)幫助者來(lái)說(shuō)，這只適用于push（如果支持的話）。

option servpath <c-style-quoted-path>

為下一次連接設(shè)置服務(wù)路徑（--upload-pack，--receive-pack等）。遠(yuǎn)程幫助程序可能支持此選項(xiàng)，但在連接請(qǐng)求發(fā)生之前不能依賴(lài)此設(shè)置。

option check-connectivity {true|false}

請(qǐng)求助手檢查克隆的連通性。

option force {true|false}

請(qǐng)助手執(zhí)行強(qiáng)制更新。默認(rèn)為false。

option cloning {true|false}

通知助手，這是一個(gè)克隆請(qǐng)求（即當(dāng)前儲(chǔ)存庫(kù)保證為空）。

option update-shallow {true|false}

如果新引用需要，允許擴(kuò)展 .git / shallow 。

option pushcert {true|false}

GPG 標(biāo)志推動(dòng)。

'option push-option <string>

傳輸 <string> 作為推送選項(xiàng)。由于推送選項(xiàng)不能包含 LF 或 NUL 字符，因此字符串不會(huì)被編碼。