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 协议