gitprotocol-capabilities - v0 和 v1 協議功能

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

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

客戶端隨後將傳送一個空格分隔的功能列表，它希望生效。客戶端不得請求伺服器未宣告支援的功能。

伺服器在收到不理解的功能時必須診斷並中止。伺服器不得忽略客戶端請求且伺服器已宣告的功能。因此，伺服器不得宣告它不理解的功能。

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 obj-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，客戶端會以 S-R-Q 交錯的方式傳送 c-b-a 鏈。

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

此功能僅應與智慧 HTTP 協議一起使用。如果同時存在 multi_ack_detailed 和 no-done，則傳送者可以在傳送第一個“ACK obj-id ready”訊息後立即傳送 packfile。

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

thin pack 是一種包含 delta，其基物件未包含在 packfile 中（但接收端已知存在）的 packfile。這可以顯著減少網路流量，但要求接收端知道如何透過新增缺失的基物件來“加厚”這些 packfile。

upload-pack 伺服器在能夠生成和傳送 thin pack 時宣告 thin-pack。客戶端在知道如何“加厚”它時請求 thin-pack 功能，通知伺服器它可以接收這樣的 packfile。如果客戶端無法將 thin pack 轉換為獨立的 packfile，則不得請求 thin-pack 功能。

另一方面，receive-pack 預設假定能夠處理 thin pack，但可以透過宣告 no-thin 功能要求客戶端不使用此功能。如果伺服器宣告了 no-thin 功能，客戶端不得傳送 thin pack。

這種不對稱的原因是歷史性的。receive-pack 程式是在 thin pack 發明之後才出現的，因此歷史上 receive-pack 的參考實現一直支援 thin pack。後來新增 no-thin 功能是為了向後相容地允許 receive-pack 停用此功能。

此功能意味著伺服器可以傳送，客戶端可以理解，在 packfile 本身之間穿插多路複用的進度報告和錯誤資訊。

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

任何一種模式都表示 packfile 資料將被分割成最多 1000 位元組（對於 side_band）或 65520 位元組（對於 side_band_64k）的資料包進行流式傳輸。每個資料包由一個 4 位元組的 pkt-line 長度（指示資料包中的資料量）、一個 1 位元組的流程式碼以及實際資料組成。

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

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

此外，對於 side-band 及其最多 1000 位元組的訊息，實際上是 999 位元組的有效負載和 1 位元組的流程式碼。對於 side-band-64k，情況相同，您有最多 65519 位元組的資料和 1 位元組的流程式碼。

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

伺服器可以傳送，客戶端可以理解 PACKv2，其中 delta 透過 packfile 中的位置而不是 obj-id 來引用其基物件。也就是說，它們可以在 packfile 中傳送/讀取 OBJ_OFS_DELTA（又名型別 6）。

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

此功能以雜湊演算法作為引數，表示伺服器支援給定的雜湊演算法。它可以被髮送多次；如果是這樣，第一個給定的是在 ref 廣告中使用的那個。

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

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

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

如果 HEAD 符號引用是傳送的引用之一，則伺服器應包含此功能。

客戶端可以使用此功能的引數來選擇克隆倉庫時的正確初始分支。

此功能為 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”或類似方式啟動，並且不希望接收 side band 2。基本上，客戶端只是說“我不想在 sideband 上接收流 2，所以請不要傳送給我，如果你傳送了，我也會忽略它”。但是，sideband 通道 3 仍然用於錯誤響應。

include-tag 功能是指在傳送物件時，也傳送指向這些物件的註解標籤。如果我們向客戶端打包一個物件，而一個標籤物件恰好指向該物件，那麼我們也會打包該標籤物件。通常，這允許客戶端在獲取分支時，在單個網路連線中獲取所有新的註解標籤。

客戶端總是可以傳送 include-tag，將其硬編碼到請求中，當伺服器宣告此功能時。客戶端是否請求 include-tag 只取決於客戶端對標籤資料的需求，而與伺服器是否在 refs/tags/* 名稱空間中宣告了物件無關。

如果伺服器打包了標籤，並且客戶端請求了 include-tags，則伺服器必須打包這些標籤。

客戶端必須準備好伺服器忽略 include-tag 並且實際上未在 packfile 中傳送標籤的情況。在這種情況下，客戶端應發出後續的 fetch 來獲取 include-tag 本來會提供的標籤。

如果伺服器支援 include-tag，則應傳送它，無論是否有可用標籤。

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

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

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

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

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

如果伺服器傳送 push-options 功能，則它能夠在傳送更新命令之後，但在 packfile 流式傳輸之前，接受 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> 包含在推送證書中。send-pack 客戶端不得傳送 push-cert 資料包，除非 receive-pack 伺服器宣告了此功能。

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

伺服器可以宣告一個會話 ID，用於跨多個請求識別此程序。客戶端也可以將其自己的會話 ID 回傳給伺服器。

會話 ID 應該在給定程序中是唯一的。它們必須適合一個 packet-line，並且不得包含不可列印字元或空格字元。當前實現使用 trace2 會話 ID（有關詳細資訊，請參閱 api-trace2），但這可能會發生變化，會話 ID 的使用者不應依賴此事實。

Git[1] 套件的一部分