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 以及忽略哪些。

一些鍵關注列表本身的屬性。

剩餘的鍵包含一個 <id> 段，它是伺服器為每個可用 bundle 指定的名稱。<id> 必須只包含字母數字和 - 字元。

這是一個使用 Git 配置格式的 bundle 列表示例

此示例使用 bundle.mode=all 以及 bundle.<id>.creationToken 啟發式方法。它還使用 bundle.<id>.filter 選項來呈現兩組並行的 bundle：一組用於完整克隆，另一組用於無 blob 的部分克隆。

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

如果使用者知道他們正在克隆的倉庫的 bundle URI，則可以透過命令列選項手動指定該 URI。但是，Git 主機可能希望在克隆操作期間釋出 bundle URI，以幫助不瞭解該功能的使用者。

此功能唯一需要的是伺服器能夠釋出一個或多個 bundle URI。此釋出採用新協議 v2 能力的形式，專門用於發現 bundle URI。

客戶端可以選擇任意 bundle URI 作為選項，或者透過一些探索性檢查選擇效能最佳的 URI。由 bundle 提供者決定是擁有多個 URI 更可取，還是透過伺服器端基礎設施進行地理分散式部署的單個 URI 更可取。

bundle URI 的主要需求是加快克隆速度。Git 客戶端將按照以下流程與 bundle URI 互動：

請注意，在克隆期間，我們預期將需要所有 bundle，並且可以使用 bundle.<uri>.creationToken 等啟發式方法按時間順序或並行下載 bundle。

如果給定的 bundle URI 是一個具有 bundle.heuristic 值的 bundle 列表，則客戶端可以選擇將該 URI 儲存為它選擇的 bundle URI。然後，客戶端可以在後續的 git fetch 呼叫期間直接導航到該 URI。

下載 bundle URI 時，客戶端可以選擇在決定下載全部內容之前檢查初始內容。這可能提供足夠的資訊來確定 URI 是 bundle 列表還是 bundle。在 bundle 的情況下，客戶端可以檢查 bundle 頭部，以確定所有公佈的提示（tips）是否已在客戶端倉庫中，並取消剩餘的下載。

當客戶端抓取新資料時，它可以決定在從源遠端抓取之前先從 bundle 伺服器抓取。這可以透過命令列選項完成，但更有可能的是使用在克隆期間指定的配置值。

抓取操作遵循相同的過程從 bundle 列表下載 bundle（儘管我們不希望在這裡使用並行下載）。我們期望當精簡 bundle（thin bundle）中所有必需的提交 OID 都已存在於物件資料庫中時，該過程將結束。

當使用 creationToken 啟發式方法時，如果 bundle 的建立令牌不大於已儲存的建立令牌，客戶端可以避免下載任何 bundle。抓取新的 bundle 後，Git 會更新此本地建立令牌。

如果 bundle 提供者沒有提供啟發式方法，那麼客戶端應在下載完整的 bundle 資料之前嘗試檢查 bundle 頭部，以防 bundle 提示（tips）已存在於客戶端倉庫中。

如果 Git 客戶端在根據 bundle URI 或在該位置找到的 bundle 列表下載資訊時發現意外情況，則 Git 可以忽略該資料並繼續，如同沒有提供 bundle URI 一樣。遠端 Git 伺服器是最終的真相來源，而不是 bundle URI。

以下是一些錯誤條件示例

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

bundle URI 功能特意設計為靈活適應 bundle 提供者組織物件資料的不同方式。然而，在這裡描述一個完整的組織模型可能會有所幫助，以便提供者可以從該基礎開始。

此組織示例是 GVFS 快取伺服器（參見本文件末尾部分）所用模型的簡化版本，該模型在加速超大型倉庫的克隆和抓取方面非常有益，儘管使用了 Git 之外的額外軟體。

bundle 提供者在多個地理區域部署伺服器。每個伺服器管理自己的 bundle 集。伺服器可以跟蹤多個 Git 倉庫，並根據模式為每個倉庫提供 bundle 列表。例如，當映象一個位於 https://<domain>/<org>/<repo> 的倉庫時，bundle 伺服器的 bundle 列表可能在 https://<server-url>/<domain>/<org>/<repo> 可用。源 Git 伺服器可以在“any”模式下列出所有這些伺服器。

這個“列表的列表”是靜態的，只有在新增或刪除 bundle 伺服器時才會發生變化。

每個 bundle 伺服器管理自己的 bundle 集。初始 bundle 列表只包含一個 bundle，其中包含從源伺服器克隆倉庫時接收到的所有物件。該列表使用 creationToken 啟發式方法，並根據伺服器的時間戳為該 bundle 生成一個 creationToken。

bundle 伺服器定期執行 bundle 列表的更新，例如每天一次。在此任務期間，伺服器從源伺服器抓取最新內容，並生成一個 bundle，其中包含可從最新源引用（origin refs）訪問的物件，但這些物件未包含在先前計算的 bundle 中。此 bundle 被新增到列表中，並確保 creationToken 嚴格大於先前的最大 creationToken。

當 bundle 列表變得過大，例如超過 30 個 bundle 時，最舊的“N 減去 30”個 bundle 將合併為一個 bundle。此 bundle 的 creationToken 等於合併後的 bundle 中最大的 creationToken。

這裡提供一個 bundle 列表示例，儘管它只有兩個每日 bundle，而不是完整的 30 個列表

為了避免物件資料即使在源伺服器中變得不可訪問後仍然永久儲存和提供，這種 bundle 合併可以更謹慎。不是對舊 bundle 進行絕對合並，而是透過檢視較新的 bundle 並確保它們所需的提交都在這個合併的 bundle 中（或在另一個較新的 bundle 中）來建立 bundle。這允許“過期”在此時間視窗內未被新提交使用的物件資料。這些資料可以通過後續的推送重新引入。

這種資料組織有兩個主要目標。首先，透過從更近的來源下載預計算的物件資料，倉庫的初始克隆變得更快。其次，git fetch 命令可以更快，特別是如果客戶端幾天沒有抓取。但是，如果客戶端 30 天沒有抓取，則 bundle 列表組織將導致重新下載大量物件資料。

使這種組織對頻繁抓取的使用者更有用的一種方法是更頻繁地建立 bundle。例如，可以每小時建立 bundle，然後每天將這些“每小時”bundle 合併為一個“每日”bundle。每日 bundle 在 30 天后合併到最舊的 bundle 中。

如果此倉庫的客戶端期望使用無 blob 的部分克隆，建議使用 blob:none 過濾器重複此 bundle 策略。此無 blob bundle 列表與完整 bundle 保持在同一列表中，但使用 bundle.<id>.filter 鍵來分隔兩組。對於非常大的倉庫，bundle 提供者可能只提供無 blob 的 bundle。

本設計文件作為一份展望性文件獨立提交，目標是在多個補丁系列的過程中實現所有提及的客戶端功能。以下是提交這些功能的潛在大綱：

隨著這些功能的審查，本計劃可能會更新。我們還期望隨著此功能的成熟並在實際場景中得到應用，將發現並實現新的設計。

Git 協議已經具備一項功能，即 Git 伺服器在響應客戶端請求時，可以列出一組 URL 以及 packfile 響應。然後，客戶端需要下載這些位置的 packfile，以便完整理解響應。

此機制由 Gerrit 伺服器（使用 JGit 實現）使用，在降低 CPU 負載和提高使用者克隆效能方面非常有效。

這種機制的一個主要缺點是源伺服器需要準確地知道這些 packfile 中包含什麼，並且 packfile 需要在伺服器響應後的一段時間內對使用者可用。源伺服器與 packfile 資料之間的這種耦合很難管理。

此外，此實現極難與抓取（fetches）配合使用。

GVFS 協議 [2] 是一組 HTTP 端點，在 Git 的部分克隆功能建立之前獨立於 Git 專案設計。此協議的一個特點是“快取伺服器”的概念，它可以與構建機器或開發人員辦公室共置，以傳輸 Git 資料而不會使中心伺服器過載。

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

然而，一個更微妙的需求是 GET /gvfs/prefetch?lastPackTimestamp=<t> 端點。給定一個可選的時間戳，快取伺服器會響應一個預計算 packfile 列表，其中包含在這些時間間隔內引入的提交和樹。

快取伺服器使用以下策略計算這些“預抓取”（prefetch）packfile

當用戶針對具有快取伺服器的倉庫執行 gvfs clone 或 scalar clone 時，客戶端會請求所有預抓取 packfile，這最多是 24 + 30 + 1 個 packfile，僅下載提交和樹。然後客戶端會向源伺服器請求引用，並嘗試檢出該提示引用。（還有一個額外的端點，用於獲取給定提交的所有可到達的樹，以防該提交尚未存在於預抓取 packfile 中。）

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

需要注意的是，客戶端總是聯絡源伺服器以獲取引用公告，因此引用通常“領先”於預抓取的包資料。當 git checkout 或 git log 等命令需要時，缺失的物件會使用 GET gvfs/objects/{oid} 請求按需下載。一些 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 協議