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 功能允许服务器在找到一个可以用作客户端想要和客户端已设置之间的公共基的提交时，立即返回“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，客户端无论如何都会发送 c-b-a 链，与 S-R-Q 交织在一起。

这是 multi_ack 的扩展，允许客户端更好地理解服务器的内存状态。有关更多信息，请参阅 gitprotocol-pack[5] 中的“Packfile 协商”部分。

此功能应仅与智能 HTTP 协议一起使用。如果 multi_ack_detailed 和 no-done 都存在，则发送方可以在其第一个“ACK obj-id ready”消息后立即发送包。

在智能 HTTP 协议中，如果没有 no-done，服务器会话将结束，客户端必须进行另一次访问以发送“done”，然后服务器才能发送包。no-done 消除了最后一轮，从而稍微减少了延迟。

瘦包是指其增量引用未包含在包中（但已知存在于接收端）的基础对象的包。这可以显着减少网络流量，但它需要接收端知道如何通过向包中添加缺少的基础来“加厚”这些包。

upload-pack 服务器在能够生成和发送瘦包时会通告 thin-pack。客户端在理解如何“加厚”它时会请求 thin-pack 功能，通知服务器它可以接收此类包。如果客户端无法将瘦包转换为自包含包，则**不得**请求 thin-pack 功能。

另一方面，receive-pack 默认情况下假定能够处理瘦包，但可以通过通告 no-thin 功能来要求客户端不要使用此功能。如果服务器通告了 no-thin 功能，则客户端**不得**发送瘦包。

这种不对称的原因是历史性的。receive-pack 程序在发明瘦包之后才出现，因此历史上 receive-pack 的参考实现始终理解瘦包。后来添加 no-thin 允许 receive-pack 以向后兼容的方式禁用此功能。

此功能意味着服务器可以发送，并且客户端可以理解，与包文件本身交织在一起的多路复用进度报告和错误信息。

这两个选项是互斥的。现代客户端始终偏好 side-band-64k。

这两种模式都表示包文件数据将被流式传输，分成最多 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 中的增量引用其基通过包中的位置而不是通过 obj-id。也就是说，它们可以在包文件中发送/读取 OBJ_OFS_DELTA（也称为类型 6）。

服务器可以可选地发送 agent=X 形式的功能，以通知客户端服务器正在运行版本 X。客户端可以通过响应 agent=Y 功能来可选地返回其自己的 agent 字符串（但如果服务器没有提及 agent 功能，则**不得**这样做）。X 和 Y 字符串可以包含除空格之外的任何可打印的 ASCII 字符（即字节范围 32 < x < 127），并且通常采用“包/版本”的形式（例如，“git/1.8.3.1”）。agent 字符串仅用于统计和调试目的，**不得**用于以编程方式假设特定功能的存在或不存在。

此功能以哈希算法作为参数，表示服务器支持给定的哈希算法。它可以多次发送；如果是这样，则使用给定的第一个算法作为引用广告中使用的算法。

当客户端提供时，这表示它打算使用给定的哈希算法进行通信。提供的算法必须是服务器支持的算法。

如果没有提供此功能，则假定唯一支持的算法是 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" 或类似方式启动，并且不希望有侧带 2。基本上，客户端只是说“我不希望接收侧带上的流 2，所以不要发送给我，如果你发送了，我无论如何都会丢弃它”。但是，侧带通道 3 仍然用于错误响应。

include-tag 功能与发送带注释的标签有关，如果我们发送它们指向的对象。如果我们将对象打包到客户端，并且标签对象恰好指向该对象，我们也会打包标签对象。通常，这允许客户端在获取分支时通过单个网络连接获取所有新的带注释的标签。

客户端可以始终发送 include-tag，在服务器宣传此功能时将其硬编码到请求中。客户端请求 include-tag 的决定仅与客户端对标签数据的需求有关，无论服务器是否在 refs/tags/* 命名空间中宣传了对象。

如果其引用已打包且客户端已请求 include-tags，则服务器必须打包标签。

客户端必须准备好处理服务器忽略了 include-tag 并且实际上没有在包中发送标签的情况。在这种情况下，客户端应该发出后续获取以获取 include-tag 本来会提供的标签。

如果服务器支持 include-tag，则服务器应该发送它，无论是否有标签可用。

receive-pack 进程可以接收 report-status 功能，该功能告诉它客户端希望在包文件上传和引用更新后获得报告。如果推送客户端请求此功能，则服务器在解包和更新引用后将响应包文件是否成功解包以及每个引用是否成功更新。如果任何一个不成功，它将发送错误消息。有关示例消息，请参见 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 功能，则它能够使处理接收到的包时可能显示的人类可读进度输出静音。如果本地进度报告也被抑制（例如，通过 push -q 或如果 stderr 不输出到 tty），则 send-pack 客户端应使用 quiet 功能来抑制服务器端的进度报告。

如果服务器发送 atomic 功能，则表示它能够接受原子推送。如果推送客户端请求此功能，则服务器将以原子事务的方式更新引用。所有引用都将更新或都不更新。

如果服务器发送 push-options 功能，则它能够在发送更新命令后但在流式传输包文件之前接受推送选项。如果推送客户端请求此功能，则服务器会将选项传递给处理此推送请求的 pre- 和 post-receive 钩子。

如果 upload-pack 服务器宣传此功能，则 fetch-pack 可以发送包含服务器上存在但未由 upload-pack 宣传的对象名称的 "want" 行。由于历史原因，此功能的名称包含 "sha1"。对象名称始终使用通过 object-format 功能协商的对象格式给出。

如果 upload-pack 服务器宣传此功能，则 fetch-pack 可以发送包含服务器上存在但未由 upload-pack 宣传的对象名称的 "want" 行。由于历史原因，此功能的名称包含 "sha1"。对象名称始终使用通过 object-format 功能协商的对象格式给出。

宣传此功能的 receive-pack 服务器愿意接受签名的推送证书，并要求将 <nonce> 包含在推送证书中。除非 receive-pack 服务器宣传此功能，否则 send-pack 客户端绝对不能发送 push-cert 数据包。

如果 upload-pack 服务器宣传 filter 功能，则 fetch-pack 可以发送 "filter" 命令来请求部分克隆或部分获取，并请求服务器从包文件中省略各种对象。

服务器可以宣传一个会话 ID，该 ID 可用于跨多个请求识别此进程。客户端也可以将自己的会话 ID 宣传回服务器。

会话 ID 应对于给定进程唯一。它们必须适合数据包行，并且不得包含不可打印或空白字符。当前实现使用 trace2 会话 ID（有关详细信息，请参见 api-trace2），但这可能会更改，会话 ID 的用户不应依赖此事实。

是 git[1] 套件的一部分