?
本文檔使用 PHP中文網(wǎng)手冊 發(fā)布
命名
gitremote-helpers - 幫助程序與遠程存儲庫進行交互
概要
git remote-<transport> <repository> [<URL>]
描述
遠程幫助程序通常不是由最終用戶直接使用，但當它需要與遠程存儲庫交互時，它們由 Git 調(diào)用。Git 本身不支持。給定的幫助程序?qū)崿F(xiàn)此處記錄的功能的子集。當 Git 需要使用遠程助手與存儲庫進行交互時，它會將助手作為獨立進程產(chǎn)生，將命令發(fā)送給助手的標準輸入，并期望助手的標準輸出結(jié)果。因為遠程助手作為獨立于 Git 的進程運行，所以不需要重新鏈接 Git 來添加新的助手，也不需要將助手與 Git 的實現(xiàn)鏈接起來。
每個助手必須支持 “capabilities” 命令，Git 使用它來確定助手將接受的其他命令。這些其他命令可用于發(fā)現(xiàn)和更新遠程參考，在對象數(shù)據(jù)庫和遠程存儲庫之間傳輸對象，并更新本地對象存儲。
Git 自帶了遠程助手，是處理各種傳輸協(xié)議，如的“curl”的家庭git-remote-http，git-remote-https，git-remote-ftp和git-remote-ftps。他們實現(xiàn)fetch，option和push這些功能。
調(diào)用
使用一個或（可選）兩個參數(shù)調(diào)用遠程幫助程序。第一個參數(shù)和 Git 一樣指定一個遠程倉庫; 它是配置的遠程或 URL 的名稱。第二個參數(shù)指定一個 URL ; 它通常是這種形式<transport>://<address>，但任何字符串都是可能的。該GIT_DIR環(huán)境變量是為遠程助手設(shè)置的，可用于確定在哪里存儲其他數(shù)據(jù)或從哪個目錄調(diào)用輔助 Git 命令。
當 Git 遇到一個表單的 URL <transport>://<address>，其中<transport>是一個它本身無法處理的協(xié)議，它會自動調(diào)用git remote-<transport>完整的 URL 作為第二個參數(shù)。如果直接在命令行中遇到這樣的 URL ，那么第一個參數(shù)與第二個參數(shù)相同，如果在配置的遠程中遇到，則第一個參數(shù)是該遠程的名稱。
該表單的 URL <transport>::<address>明確指示 Git git remote-<transport>使用<address>第二個參數(shù)。如果在命令行上直接遇到這樣的 URL ，那么第一個參數(shù)是<address>，如果在配置的遠程中遇到，則第一個參數(shù)是該遠程的名稱。
另外，當配置的遠程已經(jīng)remote.<name>.vcs設(shè)置為<transport>，GIT 中明確地調(diào)用git remote-<transport>與<name>作為第一個參數(shù)。如果設(shè)置，第二個參數(shù)是remote.<name>.url; 否則，第二個參數(shù)被省略。
輸入格式
Git 向標準輸入發(fā)送遠程助手的命令列表，每行一個。第一個命令總是capabilities命令，作為響應(yīng)，遠程助手必須打印它所支持的功能列表（見下文），后面跟著一個空行。對 capabilities 命令的響應(yīng)決定了 Git 在其余命令流中使用的命令。
命令流由空行終止。在某些情況下（在相關(guān)命令的文檔中指出），該空行后面是其他協(xié)議中的有效載荷（例如包協(xié)議），而在其他情況下則表示輸入結(jié)束。
功能
預(yù)計每個遠程助手只支持一部分命令。輔助程序支持的操作在對capabilities命令的響應(yīng)中聲明為 Git （請參見下面的 COMMANDS ）。
在下文中，我們列出了所有已定義的功能，并為每個列出了具有該功能的助手必須提供的命令。
推動能力
connect
可以嘗試使用 git 的本機 packfile 協(xié)議連接git receive-pack（推送）git upload-pack等通信。這需要雙向全雙工連接。
支持的命令：connect。
push
可以發(fā)現(xiàn)遠程引用，并將本地提交以及引導(dǎo)給它們的歷史推送到新的或現(xiàn)有的遠程引用。
支持的命令：list for-push，push。
export
可以發(fā)現(xiàn)遠程引用，并將快速導(dǎo)入流中的指定對象推送到遠程引用。
支持的命令：list for-push，export。
如果給connect打廣告，Git 將盡可能使用它，如果助手在連接時請求，則會回退到另一個能力（請參閱connect COMMANDS 下的命令）。當選擇push和export，Git 喜歡push。其他前端可能有其他一些優(yōu)先順序。
no-private-update
在使用該refspec功能時，git 通常會在成功推送時更新私有的參考。當 remote-helper 聲明能力時，此更新被禁用no-private-update。
提取能力
connect
可以嘗試使用 Git 的本機 packfile 協(xié)議連接git upload-pack（用于讀?。?code>git receive-pack等。這需要雙向全雙工連接。
支持的命令：connect。
fetch
可以發(fā)現(xiàn)遠程引用并將可從其訪問的對象傳輸?shù)奖镜貙ο蟠鎯^(qū)。
Supported commands: list, fetch.
import
可以發(fā)現(xiàn)遠程引用并將它們可訪問的對象以快速導(dǎo)入格式輸出為流。
支持的命令：list，import。
check-connectivity
可以保證在請求 clone 時，收到的包是自包含的并且已連接。
如果 helper 做廣告connect，Git 將盡可能使用它，如果助手在連接時請求，則會回退到另一個能力（請參閱connect COMMANDS 下的命令）。當選擇fetch和import，Git 喜歡fetch。其他前端可能有其他一些優(yōu)先順序。
雜項功能
option
用于指定像verbosity（寫入 stderr 的輸出量有多少）和depth（對淺克隆而言需要多少歷史記錄）等影響其他命令執(zhí)行的設(shè)置。
refspec <refspec>
對于實現(xiàn)import或者的遠程助手export，這個功能允許 refs 被限制到一個私有名稱空間，而不是直接寫入 refs / heads 或者 ref / remotes 。建議所有提供此import功能的進口商都使用此功能。這是強制性的export。
refspec refs/heads/*:refs/svn/origin/branches/*，當它被要求時import refs/heads/topic，它輸出的流將更新refs/svn/origin/branches/topic參考。
此功能可以被多次建議。第一個適用的 refspec 優(yōu)先。使用此功能宣傳的 refspecs 的左側(cè)必須覆蓋 list 命令報告的所有參考。如果沒有refspec能力被宣傳，那就暗示了refspec *:*。
當為分散版本控制系統(tǒng)編寫 remote-helpers 時，建議保留一個本地的版本庫副本進行交互，并讓私有命名空間參考指向這個本地版本庫，而 refs / remotes 命名空間用于跟蹤遠程存儲庫。
bidi-import
這改變了import能力?？焖賹?dǎo)入命令cat-blob，ls遠程助手可以使用該命令來檢索快速導(dǎo)入內(nèi)存中已存在的斑點和樹的信息。這需要一個從快速導(dǎo)入到遠程助手的通道。如果除了“導(dǎo)入”之外還公布了它，Git 將建立一個從快速導(dǎo)入到遠程助手 stdin 的管道。因此，Git 和快速導(dǎo)入都連接到遠程助手的 stdin 。因為 Git 可以向遠程幫助器發(fā)送多個命令，所以需要使用bidi-import緩沖區(qū)的幫助器import在發(fā)送數(shù)據(jù)到快速導(dǎo)入之前使用緩沖區(qū)的所有命令。這是為了防止在助手的 stdin 上混合命令和快速導(dǎo)入響應(yīng)。
export-marks <file>
這會修改該export功能，指示 Git 在完成時將內(nèi)部標記表轉(zhuǎn)儲到 <file> 。有關(guān)詳細信息，請閱讀--export-marks=<file>git-fast-export [1]。
import-marks <file>
這會修改該export功能，指示 Git 在處理任何輸入之前加載 <file> 中指定的標記。有關(guān)詳細信息，請閱讀--import-marks=<file> git-fast-export [1] 。
signed-tags
這會修改該export功能，指示 Git 傳遞--signed-tags=verbatim給 git-fast-export [1] 。在沒有這種能力的情況下，Git 會使用--signed-tags=warn-strip。
命令
命令由調(diào)用者在助手的標準輸入中給出，每行一個。
capabilities
列出助手的功能，每行一個，以空行結(jié)束。每個功能都可以使用*，這標志著它們對于使用遠程幫助程序理解的 Git 版本是強制性的。任何未知的強制性能力都是致命的錯誤。
對此命令的支持是強制性的。
list
以 “<value> <name> <attr> ...” 格式列出每行一個參考。值可以是一個十六進制 sha1 散列，“@ <dest>” 用于 symref或 “？” 以表明助手無法獲得參考價值。名稱后面有空格分隔的屬性列表; 無法識別的屬性被忽略。該列表以空行結(jié)束。
有關(guān)當前定義的屬性的列表，請參閱 REF LIST ATTRIBUTES 。
如果助手具有“獲取”或“導(dǎo)入”功能，則受支持。
list for-push
list與之類似，只是當且僅當調(diào)用者想要生成的引用列表準備推送命令時才使用它。同時支持 push 和 fetch 的助手可以使用它來區(qū)分list將要使用輸出的操作，可能會減少需要執(zhí)行的工作量。
如果助手具有“推送”或“導(dǎo)出”功能，則支持該功能。
option <name> <value>
將傳輸助手選項 <name> 設(shè)置為 <value> 。輸出包含ok（選項成功設(shè)置），unsupported（選項無法識別）和error <msg>（選項 <name> 支持但 <value> 無效）之一的單行。選項應(yīng)在其他命令之前設(shè)置，并可能影響這些命令的行為。
請參閱選項以獲取當前定義的選項列表。
如果助手具有“選項”功能則支持。
fetch <sha1> <name>
獲取給定的對象，將必要的對象寫入數(shù)據(jù)庫。提取命令以批處理形式發(fā)送，每行一個，以空行結(jié)束。當同一批次中的所有提取命令都完成時，輸出一個空白行。只有在list sha1 的輸出中報告的對象可以通過這種方式獲取。
也可以輸出一個lock <file>指示 GIT_DIR / objects / pack 下的文件的行，該文件保持一個包，直到 ref 可以被適當?shù)馗隆?/p>
如果check-connectivity請求了選項，connectivity-ok如果克隆是自包含并連接的，則助手必須輸出。
如果助手具有“獲取”功能，則受支持。
push +<src>:<dst>
將給定的本地 <src> 提交或分支推送到由 <dst> 描述的遠程分支。一個或多個push命令的批處理序列以空行結(jié)束（如果只有一個引用來推送，則單個push命令后面跟著一個空行）。例如，下面是兩批push，第一批要求 remote-helper 將本地 ref推master送到遠程 ref master，將本地 ref 推HEAD送到遠程branch，第二批要求將 ref 推入fooref bar（由該請求強制更新+） 。
push refs/heads/master:refs/heads/master push HEAD:refs/heads/branch \n push +refs/heads/foo:refs/heads/bar \n
最后一個push命令之后，在批次的終止空白行之前可以輸入零個或多個協(xié)議選項。
當推送完成時，輸出一個或多個ok <dst>或error <dst> <why>?線路以指示每個推送參考的成功或失敗。狀態(tài)報告輸出以空行結(jié)束。如果選項字段包含 LF，則可以用 C 風格字符串引用該選項字段。
如果助手具有 "push" 功能則支持。
import <name>
生成一個快速導(dǎo)入的流，導(dǎo)入指定 ref 的當前值。它還可以根據(jù)需要額外導(dǎo)入其他參考以高效地構(gòu)建歷史記錄。腳本寫入助手特定的私有名稱空間。named ref 的值應(yīng)寫入此名稱空間中的一個位置，該位置通過將 refspecs 從 “refspec” 功能應(yīng)用到 ref 的名稱而得出。
特別適用于與外部版本控制系統(tǒng)的互操作性。
就像push，一個或多個批處理序列import以空行結(jié)束。對于每一批import，遠程助手應(yīng)該產(chǎn)生一個由done命令終止的快速導(dǎo)入流。
請注意，如果使用了bidi-import功能，則在開始發(fā)送數(shù)據(jù)以進行快速導(dǎo)入之前，必須緩沖完整的批處理序列，以防止在幫助器的 stdin 上混合命令和快速導(dǎo)入響應(yīng)。
如果助手具有 "import" 功能則支持。
export
指示遠程助手任何后續(xù)輸入都是快速導(dǎo)入流（由生成的git fast-export）的一部分，該流包含應(yīng)推送到遠程的對象。
特別適用于與外部版本控制系統(tǒng)的互操作性。
如果指定了這些export-marks和import-marks功能，只要它們被傳遞到git fast-export，就會影響此命令，然后它會為本地對象加載/存儲一個標記表。這可以用于執(zhí)行增量操作。
如果助手具有“導(dǎo)出”功能則支持。
connect <service>
連接到給定的服務(wù)。幫助器的標準輸入和標準輸出連接到指定服務(wù)（git 前綴包含在服務(wù)名稱中，例如，git-upload-pack作為服務(wù)提取使用）在遠程端。對此命令的有效答復(fù)是空行（已建立連接），fallback（不支持智能傳輸支持，退回到啞傳輸），并且僅在退出時顯示錯誤消息（無法連接，請勿嘗試退回）。在換行終止正（空）響應(yīng)后，服務(wù)輸出開始。連接結(jié)束后，遠程助手退出。
如果助手具有 "connect" 功能則支持。
如果發(fā)生致命錯誤，程序會將錯誤消息寫入 stderr 并退出。如果孩子關(guān)閉連接而未完成當前命令的有效響應(yīng)，則調(diào)用者應(yīng)該期望已經(jīng)打印出合適的錯誤消息。
可以支持附加的命令，這可以從助手報告的能力中確定。
參考列表屬性
該list命令產(chǎn)生一個 ref 列表，其中每個 ref 可以后跟一個屬性列表。定義了以下參考列表屬性。
unchanged
該引用自上次導(dǎo)入或提取后不變，但助手不一定能確定產(chǎn)生的值。
選項
如果遠程助手有option能力，則定義以下選項并在 Git 中設(shè)置（在適當?shù)那闆r下）。
option verbosity <n>
更改助手顯示的消息的詳細程度。<n> 的值為0，意味著進程安靜地運行，并且助手只產(chǎn)生錯誤輸出。1是默認的詳細級別，更高的值 <n> 對應(yīng)于在命令行上傳遞的 -v 標志的數(shù)量。
option progress {true|false}
啟用（或禁用）傳輸助手在命令期間顯示的進度消息。
option depth <depth>
深化淺層知識庫的歷史。
'option deepen-since <timestamp>
基于時間來加深淺層知識庫的歷史。
'option deepen-not <ref>
加深不包括參考文獻的淺儲藏庫的歷史。多個選項加起來。
option deepen-relative {'true|false}
相對于當前的邊界，加深了淺倉庫的歷史。僅在與“選項深度”一起使用時才有效。
option followtags {true|false}
如果啟用，助手應(yīng)自動獲取帶注釋的標簽對象，如果標簽指向的對象在獲取命令期間被傳送。如果標簽沒有被助手獲取，通常會發(fā)送第二個獲取命令來特別要求標簽。一些助手可能能夠使用此選項來避免第二次網(wǎng)絡(luò)連接。
option dry-run{ true| false}：如果為 true ，則假裝操作成功完成，但實際上并未更改任何存儲庫數(shù)據(jù)。對于大多數(shù)幫助者來說，這只適用于push（如果支持的話）。
option servpath <c-style-quoted-path>
為下一次連接設(shè)置服務(wù)路徑（--upload-pack，--receive-pack等）。遠程幫助程序可能支持此選項，但在連接請求發(fā)生之前不能依賴此設(shè)置。
option check-connectivity {true|false}
請求助手檢查克隆的連通性。
option force {true|false}
請助手執(zhí)行強制更新。默認為false。
option cloning {true|false}
通知助手，這是一個克隆請求（即當前儲存庫保證為空）。
option update-shallow {true|false}
如果新引用需要，允許擴展 .git / shallow 。
option pushcert {true|false}
GPG 標志推動。
'option push-option <string>
傳輸 <string> 作為推送選項。由于推送選項不能包含 LF 或 NUL 字符，因此字符串不會被編碼。