Bundle URI 標準旨在具有足夠的彈性以滿足多種工作負載。Bundle 提供者與 Git 用戶端在建立與取用 bundle URI 時有多種選擇。

每個儲存庫皆不相同，每個 Git 伺服器也有不同的需求。希望 bundle URI 功能足夠靈活以滿足所有需求。若不然，該功能亦可透過其版本機制進行擴充。

若要提供 bundle 伺服器的伺服器端實作，不需要 Git 協定的其他部分。這允許伺服器維護人員使用 CDN 等靜態內容解決方案來提供 bundle 檔案。

在當前 bundle URI 功能的範疇內，所有 URI 預期皆為 HTTP(S) URL，內容透過對該 URL 發送 GET 請求下載至本地檔案。伺服器可以對這些請求加入驗證需求，旨在觸發已設定的憑證輔助程式以進行安全存取。（未來擴充可能會使用 "file://" URI 或 SSH URI。）

假設伺服器回傳 200 OK，則會檢查該 URL 的內容。首先，Git 嘗試將該檔案解析為版本 2 或以上的 bundle 檔案。如果該檔案不是 bundle，則會將其解析為 Git 設定檔格式的純文字檔。該設定檔中的鍵值對預期會描述一個 bundle URI 列表。如果這些解析嘗試皆不成功，Git 將向使用者報告錯誤，指出提供的 bundle URI 包含錯誤資料。

伺服器提供的任何其他資料皆視為錯誤。

Git 伺服器可以使用一組 key=value 對來公告 bundle URI。Bundle URI 也可以提供一個 Git 設定格式的純文字檔，其中包含相同的 key=value 對。在這兩種情況下，我們皆視其為 bundle 列表。這些鍵值對指定了 bundle 的相關資訊，用戶端可據此決定要下載哪些 bundle 以及忽略哪些 bundle。

有幾個鍵專注於列表本身的屬性。

其餘鍵包含一個 <id> 區段，這是伺服器為每個可用 bundle 指定的名稱。<id> 必須僅包含英數字元與 - 字元。

以下是一個使用 Git 設定格式的 bundle 列表範例

此範例同時使用了 bundle.mode=all 以及 bundle.<id>.creationToken 啟發式參數。它還使用了 bundle.<id>.filter 選項來提供兩組平行的 bundle：一組用於完整 clone，另一組用於不含 blob 的部分 clone。

假設此 bundle 列表位於 URI https://bundles.example.com/git/git/，因此這兩個不含 blob 的 bundle 具有以下完整展開的 URI

如果使用者知道他們要 clone 的儲存庫的 bundle URI，他們可以透過命令列選項手動指定該 URI。然而，Git 主機可能希望在 clone 操作期間公告 bundle URI，以幫助尚未察覺此功能的使用者。

此功能唯一的要求是伺服器可以公告一個或多個 bundle URI。此公告採取專用於發現 bundle URI 的新 protocol v2 功能的形式。

用戶端可以選擇任意 bundle URI 作為選項，或者透過某些探索性檢查選擇效能最好的 URI。由 bundle 提供者決定是否提供多個 URI 優於由伺服器端基礎設施進行地理分散的單一 URI。

Bundle URI 的主要需求是加速 clone。Git 用戶端將依照以下流程與 bundle URI 互動

請注意，在 clone 期間，我們預期所有 bundle 都是必要的，且像 bundle.<uri>.creationToken 這樣的啟發式參數可用於按時間順序或平行下載 bundle。

如果給定的 bundle URI 是一個帶有 bundle.heuristic 值的 bundle 列表，則用戶端可以選擇將該 URI 儲存為其選定的 bundle URI。用戶端之後在呼叫 git fetch 時可以直接導向該 URI。

下載 bundle URI 時，用戶端可以選擇在承諾下載全部內容之前檢查初始內容。這可能提供足夠的資訊來判斷 URI 是 bundle 列表還是 bundle。若是 bundle，用戶端可以檢查 bundle 標頭，判斷所有公告的尖端 (tips) 是否已在用戶端儲存庫中，並取消剩餘的下載。

當用戶端 fetch 新資料時，它可以決定在從原始遠端 fetch 之前先從 bundle 伺服器 fetch。這可以透過命令列選項完成，但使用像 clone 時指定的設定值可能更有用。

Fetch 操作遵循相同的程序從 bundle 列表下載 bundle（儘管我們在這裡 不 希望使用平行下載）。我們預期當 thin bundle 中的所有必要 commit OID 都已存在於物件資料庫中時，該程序就會結束。

當使用 creationToken 啟發式參數時，若 bundle 的建立權杖不大於已儲存的建立權杖，用戶端可以避免下載任何 bundle。在 fetch 新 bundle 後，Git 會更新此本地建立權杖。

如果 bundle 提供者沒有提供啟發式參數，則用戶端應嘗試在下載完整 bundle 資料之前檢查 bundle 標頭，以防 bundle 的尖端已經存在於用戶端儲存庫中。

如果 Git 用戶端在根據 bundle URI 或位於該位置的 bundle 列表下載資訊時發現意外情況，Git 可以忽略該資料並繼續，就好像未被給定 bundle URI 一樣。遠端 Git 伺服器是最終的真理來源，而非 bundle URI。

以下是一些錯誤狀況範例

還有一些情況可能會被視為浪費，但並非錯誤狀況

Bundle URI 功能被刻意設計為對 bundle 提供者想要組織物件資料的不同方式具有彈性。然而，在此描述一個完整的組織模型可能對提供者有所幫助，使其能以此為基礎開始。

此範例組織是 GVFS 快取伺服器（參見本文末尾附近章節）所使用模型的一種簡化，儘管它使用了 Git 之外的額外軟體，但對於加速大型儲存庫的 clone 與 fetch 非常有益。

Bundle 提供者跨多個地理區域佈署伺服器。每個伺服器管理自己的 bundle 集。伺服器可以追蹤多個 Git 儲存庫，但會根據模式為每個儲存庫提供 bundle 列表。例如，在鏡像 https://<domain>/<org>/<repo> 的儲存庫時，bundle 伺服器可以在 https://<server-url>/<domain>/<org>/<repo> 提供其 bundle 列表。原始 Git 伺服器可以在 "any" 模式下列出所有這些伺服器

此「列表的列表」是靜態的，僅在新增或刪除 bundle 伺服器時才會變更。

每個 bundle 伺服器管理自己的 bundle 集。初始 bundle 列表僅包含單一 bundle，其中包含從原始伺服器 clone 儲存庫所收到的所有物件。該列表使用 creationToken 啟發式參數，並根據伺服器的時間戳記為 bundle 建立 creationToken。

Bundle 伺服器執行定期排程的 bundle 列表更新，例如每天一次。在此任務期間，伺服器從原始伺服器 fetch 最新內容，並產生一個包含可從最新原始 ref 到達、但先前計算的 bundle 中未包含的物件之 bundle。此 bundle 會被加入列表中，並確保 creationToken 嚴格大於先前的最大 creationToken。

當 bundle 列表變得過大，例如超過 30 個 bundle 時，最舊的「N 減 30」個 bundle 會被合併為單一 bundle。此 bundle 的 creationToken 等於合併 bundle 中的最大 creationToken。

此處提供一個範例 bundle 列表，儘管它只有兩個每日 bundle 而非完整的 30 個列表

為了避免儘管物件資料在原始伺服器中已不可達，卻仍永久儲存與提供，此 bundle 合併可以更謹慎。與其取舊 bundle 的絕對聯集，不如透過檢查較新的 bundle 並確保其必要 commit 皆存在於此合併 bundle（或另一個較新的 bundle 中）來建立 bundle。這允許「過期」在此時間窗口內未被新 commit 使用的物件資料。該資料可透過稍後的 push 重新引入。

此資料組織的意圖有兩個主要目標。首先，透過從更近的來源下載預先計算的物件資料，使儲存庫的初始 clone 變快。其次，git fetch 指令可以變快，特別是如果用戶端幾天沒有 fetch。然而，如果用戶端 30 天沒有 fetch，則 bundle 列表組織將導致重新下載大量物件資料。

使此組織對於頻繁 fetch 的使用者更有用的一種方法是更頻繁地建立 bundle。例如，可以每小時建立 bundle，然後每天將這些「每小時」bundle 合併為「每日」bundle。每日 bundle 會在 30 天後合併到最舊的 bundle 中。

建議此 bundle 策略針對 blob:none 過濾器重複執行，如果該儲存庫的用戶端預期使用不含 blob 的部分 clone。此不含 blob 的 bundle 列表與完整 bundle 位於同一個列表中，但使用 bundle.<id>.filter 鍵來區分兩組。對於非常大的儲存庫，bundle 提供者可能希望 僅 提供不含 blob 的 bundle。

本設計文件作為願景文件獨立提交，目標是在幾個修補程式系列中實作所有提及的用戶端功能。以下是提交這些功能的潛在大綱

隨著這些功能的審查，此計畫可能會更新。我們也預期隨著此功能的成熟並在現實場景中使用，新的設計將會被發現並實作。

Git 協定已經有一種功能，即 Git 伺服器在服務用戶端請求時，可以列出一組 URL 以及 packfile 回應。用戶端隨後預期會下載位於這些位置的 packfile，以便對回應有完整的理解。

此機制由 Gerrit 伺服器（使用 JGit 實作）使用，在減少 CPU 負載與提升 clone 的使用者效能方面效果顯著。

此機制的一個主要缺點是原始伺服器需要 完全 知道這些 packfile 中有什麼，且 packfile 需要在伺服器回應後的一段時間內對使用者可用。這種原始伺服器與 packfile 資料之間的耦合很難管理。

此外，此實作要與 fetch 一起工作極為困難。

GVFS 協定 [2] 是一組在 Git 的部分 clone 建立之前，獨立於 Git 專案設計的 HTTP 端點。此協定的一項功能是「快取伺服器」的概念，它可以與建置機器或開發人員辦公室部署在同處，以傳輸 Git 資料而不使中央伺服器過載。

VFS for Git 最著名的是 GET /gvfs/objects/{oid} 端點，它允許按需下載物件。這是該產品檔案系統虛擬化的關鍵部分。

然而，一個更微妙的需求是 GET /gvfs/prefetch?lastPackTimestamp=<t> 端點。給定一個可選的時間戳記，快取伺服器會以包含在這些時間間隔內引入的 commit 與 tree 的預先計算 packfile 列表進行回應。

快取伺服器使用以下策略計算這些「預提取」(prefetch) packfile

當使用者對擁有快取伺服器的儲存庫執行 gvfs clone 或 scalar clone 時，用戶端會請求所有預提取 packfile，最多為 24 + 30 + 1 個 packfile，僅下載 commit 與 tree。用戶端隨後向原始伺服器發送對參考的請求，並嘗試檢出該尖端參考。（有一個額外的端點有助於從給定 commit 取得所有可達的 tree，以防該 commit 還不在預提取 packfile 中。）

在 git fetch 期間，一個 hook 使用先前下載的預提取 packfile 中的最近時間戳記請求預提取端點。僅下載帶有較晚時間戳記的 packfile 列表。大多數使用者每小時 fetch 一次，因此他們最多只會得到一個每小時的預提取 pack。機器關機或超過 30 天未 fetch 的使用者可能會重新下載所有預提取 packfile。這種情況很少見。

值得注意的是，用戶端總是聯繫原始伺服器進行參考公告，因此參考通常會比預提取的 pack 資料「超前」。缺少的物件會在需要時使用 GET gvfs/objects/{oid} 請求按需下載（例如由 git checkout 或 git log 指令需要時）。一些 Git 最佳化會停用會導致這些按需下載過於頻繁的檢查。

[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/ 一個早期的 bundle URI 功能 RFC。

[2] https://github.com/microsoft/VFSForGit/blob/master/Protocol.md GVFS 協定