gitprotocol-capabilities - 協議 v0 和 v1 功能

伺服器應該（SHOULD）支援本文件中定義的所有功能。

在 receive-pack 和 upload-pack 的初始伺服器響應的第一行，第一個引用之後是一個空位元組（NUL byte），然後是一個以空格分隔的伺服器功能列表。這些功能允許伺服器向客戶端宣告它能或不能支援什麼。

客戶端隨後將傳送一個以空格分隔的功能列表，以表明其希望生效的功能。客戶端絕不能（MUST NOT）請求伺服器未宣告支援的功能。

如果客戶端傳送了伺服器不理解的功能，伺服器必須（MUST）診斷並中止。伺服器絕不能（MUST NOT）忽略客戶端請求且伺服器已宣告的功能。根據這些規則，伺服器絕不能（MUST NOT）宣告它不理解的功能。

atomic、report-status、report-status-v2、delete-refs、quiet 和 push-cert 功能由 receive-pack（推送到伺服器）程序傳送和識別。

ofs-delta 和 side-band-64k 功能由 upload-pack 和 receive-pack 協議傳送和識別。agent 和 session-id 功能可在兩種協議中選擇性地傳送。

所有其他功能僅由 upload-pack（從伺服器獲取）程序識別。

multi_ack 功能允許伺服器在找到一個可用作客戶端的 want 集合和 have 集合之間公共基礎的提交時，立即返回“ACK 物件 ID continue”。

透過提早傳送此資訊，伺服器可以潛在地阻止客戶端在該特定分支的儲存庫歷史中進一步遍歷。客戶端可能仍需要遍歷其他分支，為它們傳送 have 行，直到伺服器在 DAG 中完全截斷或客戶端傳送“done”。

沒有 multi_ack，客戶端會按 --date-order 傳送 have 行，直到伺服器找到一個公共基礎。這意味著客戶端將傳送伺服器已知為公共的 have 行，因為它們在時間上與伺服器尚未找到公共基礎的另一個分支重疊。

例如，假設客戶端擁有伺服器沒有的大寫提交，而伺服器擁有客戶端沒有的小寫提交，如下圖所示

如果客戶端想要 x,y 並開始說 have F,S，伺服器不知道 F,S 是什麼。最終客戶端說“have d”，伺服器傳送“ACK d continue”以告知客戶端停止遍歷該行（所以不要傳送 c-b-a），但尚未完成，它需要 x 的基礎。客戶端繼續使用 S-R-Q，直到達到 a，此時伺服器有了一個清晰的基礎，所有都結束了。

沒有 multi_ack，客戶端無論如何都會發送該 c-b-a 鏈，並與 S-R-Q 交錯。

這是 multi_ack 的擴充套件，允許客戶端更好地理解伺服器的記憶體狀態。有關更多資訊，請參閱 gitprotocol-pack[5] 的“Packfile Negotiation”部分。

此功能僅應與智慧 HTTP 協議一起使用。如果 multi_ack_detailed 和 no-done 都存在，則傳送方可以在其第一個“ACK 物件 ID ready”訊息之後立即傳送一個包。

在智慧 HTTP 協議中，如果沒有 no-done，伺服器會話將結束，客戶端必須再進行一次往返才能傳送“done”，然後伺服器才能傳送包。no-done 消除了最後一次往返，從而略微減少了延遲。

瘦包（thin pack）是指包含引用包中未包含（但已知存在於接收端）基礎物件的增量資料的包。這可以顯著減少網路流量，但它要求接收端知道如何透過將缺失的基礎新增到包中來“加厚”這些包。

當 upload-pack 伺服器能夠生成和傳送瘦包時，它會宣告 thin-pack 功能。客戶端在理解如何“加厚”瘦包時請求 thin-pack 功能，從而通知伺服器它可以接收此類包。如果客戶端無法將瘦包轉換為自包含包，則絕不能（MUST NOT）請求 thin-pack 功能。

另一方面，receive-pack 預設假定能夠處理瘦包，但可以透過宣告 no-thin 功能來要求客戶端不要使用該功能。如果伺服器宣告 no-thin 功能，客戶端絕不能（MUST NOT）傳送瘦包。

這種不對稱的原因是歷史性的。receive-pack 程式直到瘦包發明後才出現，因此從歷史上看，receive-pack 的參考實現始終理解瘦包。後來新增 no-thin 允許 receive-pack 以向後相容的方式停用該功能。

此功能意味著伺服器可以傳送，並且客戶端可以理解，與包檔案本身交錯的多路複用進度報告和錯誤資訊。

這兩個選項是互斥的。現代客戶端總是傾向於使用 side-band-64k。

兩種模式都表明包檔案資料將被分割成資料包流式傳輸，在 side_band 的情況下，每個資料包最多 1000 位元組，在 side_band_64k 的情況下，每個資料包最多 65520 位元組。每個資料包由一個前導的 4 位元組 pkt-line 長度（表示資料包中包含的資料量）、一個 1 位元組流程式碼，以及實際資料組成。

流程式碼可以是以下之一：

“side-band-64k”功能是為了讓能夠處理更大資料包的新客戶端請求實際幾乎填滿的資料包，同時保持對舊客戶端的向後相容性而產生的。

此外，對於 side-band 及其最大 1000 位元組的訊息，實際有效載荷為 999 位元組，流程式碼為 1 位元組。對於 side-band-64k，同樣如此，你最多有 65519 位元組的資料和 1 位元組的流程式碼。

客戶端必須（MUST）只發送“side-band”和“side-band-64k”中的一個。如果客戶端同時請求兩者，伺服器必須（MUST）將其診斷為錯誤。

伺服器可以傳送，並且客戶端可以理解 PACKv2，其中增量透過其在包中的位置而不是透過物件 ID 來引用其基礎。也就是說，它們可以在包檔案中傳送/讀取 OBJ_OFS_DELTA（即型別 6）。

伺服器可以選擇性地傳送形式為 agent=X 的功能，以通知客戶端伺服器正在執行版本 X。客戶端可以選擇性地透過響應 agent=Y 功能來返回自己的代理字串（但如果伺服器未提及 agent 功能，則絕不能（MUST NOT）這樣做）。X 和 Y 字串可以包含除空格之外的任何可列印 ASCII 字元（即，位元組範圍 32 < x < 127），通常形式為“package/version”（例如，“git/1.8.3.1”）。代理字串純粹用於統計和除錯目的，絕不能（MUST NOT）用於程式性地假定特定功能的存在或缺失。

此功能以雜湊演算法作為引數，表示伺服器支援給定的雜湊演算法。它可以傳送多次；如果是這樣，第一個給定的雜湊演算法將用於引用公告中。

當客戶端提供時，這表示它打算使用給定的雜湊演算法進行通訊。提供的演算法必須是伺服器支援的演算法。

如果未提供此功能，則假定唯一支援的演算法是 SHA-1。

此引數化功能用於告知接收方哪個符號引用指向哪個引用；例如，“symref=HEAD:refs/heads/master”告訴接收方 HEAD 指向 master。此功能可以重複以表示多個符號引用。

如果 HEAD 符號引用是正在傳送的引用之一，伺服器應該（SHOULD）包含此功能。

客戶端可以（MAY）使用此功能中的引數在克隆儲存庫時選擇適當的初始分支。

此功能向 fetch-pack/upload-pack 協議添加了“deepen”、“shallow”和“unshallow”命令，以便客戶端可以請求淺克隆。

此功能向 fetch-pack/upload-pack 協議添加了“deepen-since”命令，以便客戶端可以請求在特定時間而不是在特定深度截斷的淺克隆。在內部，它等同於在伺服器端執行“rev-list --max-age=<timestamp>”。“deepen-since”不能與“deepen”一起使用。

此功能向 fetch-pack/upload-pack 協議添加了“deepen-not”命令，以便客戶端可以請求在特定修訂版本而不是在特定深度截斷的淺克隆。在內部，它等同於在伺服器端執行“rev-list --not <rev>”。“deepen-not”不能與“deepen”一起使用，但可以與“deepen-since”一起使用。

如果客戶端請求此功能，則“deepen”命令的語義會發生變化。“depth”引數表示從當前淺邊界的深度，而不是從遠端引用開始的深度。

客戶端以“git clone -q”或類似方式啟動，並且不希望使用側帶 2。基本上客戶端只是說“我不希望在側帶上接收流 2，所以不要傳送給我，如果你傳送了，我也會直接丟棄”。然而，側帶通道 3 仍然用於錯誤響應。

include-tag 功能涉及在傳送物件時傳送註釋標籤，如果這些標籤指向該物件。如果我們將一個物件打包給客戶端，並且一個標籤物件恰好指向該物件，我們也會打包該標籤物件。通常，這允許客戶端在獲取分支時，透過單個網路連接獲取所有新的註釋標籤。

客戶端可以（MAY）始終傳送 include-tag，在伺服器宣告此功能時將其硬編碼到請求中。客戶端是否請求 include-tag 的決定僅與客戶端對標籤資料的需求有關，而與伺服器是否已在 refs/tags/* 名稱空間中宣告物件無關。

如果標籤所引用的物件已被打包且客戶端已請求 include-tags，伺服器必須（MUST）打包這些標籤。

客戶端必須（MUST）為伺服器忽略 include-tag 且未實際在包中傳送標籤的情況做好準備。在這種情況下，客戶端應該（SHOULD）發出後續的獲取操作以獲取 include-tag 本應提供給客戶端的標籤。

如果伺服器支援 include-tag，它應該（SHOULD）傳送此功能，無論是否有可用標籤。

receive-pack 程序可以接收 report-status 功能，該功能告知它客戶端需要一個在包檔案上傳和引用更新後發生情況的報告。如果推送客戶端請求此功能，伺服器在解包和更新引用後將響應包檔案是否成功解包以及每個引用是否成功更新。如果其中任何一個不成功，它將返回錯誤訊息。有關示例訊息，請參閱 gitprotocol-pack[5]。

report-status-v2 功能透過新增新的“option”指令擴充套件了 report-status 功能，以支援“proc-receive”鉤子重寫的引用。“proc-receive”鉤子可以處理偽引用的命令，這可能會建立或更新一個具有不同名稱、新物件 ID 和舊物件 ID 的引用。而 report-status 功能無法報告此類情況。有關詳細資訊，請參閱 gitprotocol-pack[5]。

如果伺服器返回 delete-refs 功能，則表示它能夠接受零 ID 值作為引用更新的目標值。此功能並非由客戶端返回，它只是通知客戶端可以傳送零 ID 值來刪除引用。

如果 receive-pack 伺服器宣告 quiet 功能，則它能夠抑制在處理接收到的包時可能顯示的人類可讀進度輸出。如果本地進度報告也被抑制（例如，透過 push -q，或者如果 stderr 未輸出到 tty），send-pack 客戶端應該（SHOULD）響應 quiet 功能以抑制伺服器端進度報告。

如果伺服器傳送 atomic 功能，則表示它能夠接受原子推送。如果推送客戶端請求此功能，伺服器將以一個原子事務更新所有引用。要麼所有引用都更新，要麼都不更新。

如果伺服器傳送 push-options 功能，則表示它能夠在更新命令傳送之後但在包檔案流式傳輸之前接受推送選項。如果推送客戶端請求此功能，伺服器會將這些選項傳遞給處理此推送請求的 pre- 和 post-receive 鉤子。

如果 upload-pack 伺服器宣告此功能，fetch-pack 可以傳送帶有物件名稱的“want”行，這些物件名稱存在於伺服器上但未由 upload-pack 宣告。出於歷史原因，此功能的名稱包含“sha1”。物件名稱總是使用透過 object-format 功能協商的物件格式給出。

如果 upload-pack 伺服器宣告此功能，fetch-pack 可以傳送帶有物件名稱的“want”行，這些物件名稱存在於伺服器上但未由 upload-pack 宣告。出於歷史原因，此功能的名稱包含“sha1”。物件名稱總是使用透過 object-format 功能協商的物件格式給出。

宣告此功能的 receive-pack 伺服器願意接受簽名推送證書，並要求將 <nonce> 包含在推送證書中。除非 receive-pack 伺服器宣告此功能，send-pack 客戶端絕不能（MUST NOT）傳送 push-cert 資料包。

如果 upload-pack 伺服器宣告 filter 功能，fetch-pack 可以傳送“filter”命令來請求部分克隆或部分獲取，並請求伺服器從包檔案中省略各種物件。

伺服器可以宣告一個會話 ID，該 ID 可用於在多個請求中識別此程序。客戶端也可以向伺服器宣告自己的會話 ID。

會話 ID 對於給定程序應該是唯一的。它們必須符合 pkt-line 格式，並且不能包含不可列印或空白字元。當前實現使用 trace2 會話 ID（詳見 api-trace2），但這可能會改變，會話 ID 的使用者不應依賴此事實。

Git[1] 套件的一部分