设置和配置
获取和创建项目
基本快照
分支与合并
共享和更新项目
检查和比较
打补丁
调试
电子邮件
外部系统
服务器管理
指南
管理
底层命令
- 2.49.1 → 2.50.1 无更改
-
2.49.0
2025-03-14
- 2.48.1 → 2.48.2 无更改
-
2.48.0
2025-01-10
- 2.47.2 → 2.47.3 无变更
-
2.47.1
2024-11-25
- 2.45.1 → 2.47.0 无变更
-
2.45.0
2024-04-29
- 2.44.1 → 2.44.4 无更改
-
2.44.0
2024-02-23
- 2.43.1 → 2.43.7 无更改
-
2.43.0
2023-11-20
- 2.40.1 → 2.42.4 无更改
-
2.40.0
2023-03-12
- 2.38.1 → 2.39.5 无更改
-
2.38.0
2022-10-02
描述
本文档提供了 Git 有线协议版本 2 的规范。协议 v2 将通过以下方式改进 v1:
-
支持单个服务中的多个命令,而非多个服务名称
-
通过将功能移至协议的独立部分,不再隐藏在 NUL 字节后面并受 pkt-line 大小限制,从而易于扩展
-
分离隐藏在 NUL 字节后面的其他信息(例如,代理字符串作为功能,并且可以使用 ls-refs 请求符号引用)
-
除非明确请求,否则将省略引用通告
-
ls-refs 命令可明确请求某些引用
-
设计时考虑了 http 和无状态 RPC。通过清晰的刷新语义,http 远程助手可以简单地充当代理
在协议 v2 中,通信是面向命令的。初次联系服务器时,会通告功能列表。其中一些功能将是客户端可以请求执行的命令。命令完成后,客户端可以重用连接并请求执行其他命令。
数据包行分帧
所有通信都使用数据包行分帧完成,与 v1 中相同。有关更多信息,请参阅 gitprotocol-pack[5] 和 gitprotocol-common[5]。
在协议 v2 中,这些特殊数据包将具有以下语义:
-
0000 刷新数据包(flush-pkt)- 指示消息结束
-
0001 分隔符数据包(delim-pkt)- 分隔消息的各个部分
-
0002 响应结束数据包(response-end-pkt)- 指示无状态连接的响应结束
初始客户端请求
通常,客户端可以通过在使用中的传输的相应旁路通道发送 version=2
来请求使用协议 v2,这不可避免地会设置 GIT_PROTOCOL
。更多信息可在 gitprotocol-pack[5] 和 gitprotocol-http[5] 以及 git.txt
中的 GIT_PROTOCOL
定义中找到。在所有情况下,服务器的响应都是能力通告。
Git 传输
当使用 git:// 传输时,您可以通过发送 "version=2" 作为额外参数来请求使用协议 v2。
003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0
HTTP 传输
当使用 http:// 或 https:// 传输时,客户端会发出 gitprotocol-http[5] 中描述的“智能”info/refs 请求,并通过在 Git-Protocol
头中提供 "version=2" 来请求使用 v2。
C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 C: Git-Protocol: version=2
v2 服务器将回复:
S: 200 OK S: <Some headers> S: ... S: S: 000eversion 2\n S: <capability-advertisement>
随后的请求将直接发送到服务 $GIT_URL/git-upload-pack
。(这对于 git-receive-pack 同样适用)。
使用 git-upload-pack[1] 的 --http-backend-info-refs
选项。
服务器可能需要配置以通过 GIT_PROTOCOL
变量传递此头的内容。请参阅 git-http-backend.txt
中的讨论。
能力通告
服务器根据客户端的请求,决定使用协议版本 2 进行通信时,会在其初始响应中发送一个版本字符串,后跟其能力通告。每个能力都是一个键,带有一个可选的值。客户端必须忽略所有未知键。未知值的语义留待每个键的定义。某些能力将描述客户端可以请求执行的命令。
capability-advertisement = protocol-version capability-list flush-pkt
protocol-version = PKT-LINE("version 2" LF) capability-list = *capability capability = PKT-LINE(key[=value] LF)
key = 1*(ALPHA | DIGIT | "-_") value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;")
命令请求
收到能力通告后,客户端可以发出请求,选择所需命令及其特定功能或参数。然后是一个可选部分,客户端可以在其中提供任何命令特定的参数或查询。一次只能请求一个命令。
request = empty-request | command-request empty-request = flush-pkt command-request = command capability-list delim-pkt command-args flush-pkt command = PKT-LINE("command=" key LF) command-args = *command-specific-arg
command-specific-args are packet line framed arguments defined by each individual command.
服务器随后将检查以确保客户端的请求由有效的命令以及所通告的有效功能组成。如果请求有效,服务器将执行该命令。服务器在发出响应之前,必须等到收到客户端的整个请求。响应的格式由正在执行的命令决定,但在所有情况下,刷新数据包都表示响应的结束。
当命令完成,且客户端已从服务器接收到整个响应后,客户端可以请求执行另一个命令,也可以终止连接。客户端可以选择发送一个仅包含刷新数据包的空请求,以指示不再发出任何请求。
能力
能力有两种不同的类型:普通能力,可用于传达信息或改变请求的行为;以及命令,这是客户端要执行的核心操作(抓取、推送等)。
协议版本 2 默认是无状态的。这意味着所有命令必须只持续一轮,并且从服务器端看是无状态的,除非客户端请求了一个表明服务器应维护状态的能力。客户端在正确运行的前提下,不得要求服务器端进行状态管理。这允许服务器端进行简单的轮询负载均衡,而无需担心状态管理。
代理
服务器可以通告带有值 X
(形式为 agent=X
)的 agent
能力,以通知客户端服务器正在运行版本 X
。客户端可以选择通过在其对服务器的请求中包含带有值 Y
(形式为 agent=Y
)的 agent
能力来发送其自己的代理字符串(但如果服务器未通告 agent 能力,则不得这样做)。X
和 Y
字符串可以包含除空格以外的任何可打印 ASCII 字符(即,字节范围 33 ≤ x ≤ 126),通常采用“包/版本-操作系统”的形式(例如,“git/1.8.3.1-Linux”),其中 os
是操作系统名称(例如,“Linux”)。X
和 Y
可以使用 GIT_USER_AGENT 环境变量配置,并且它具有优先级。os
是通过 uname
(2
) 系统调用的 sysname 字段或其等效方法检索的。代理字符串纯粹用于统计和调试目的,不得用于以编程方式假定特定功能的存在或缺失。
ls-refs
ls-refs
是 v2 中用于请求引用通告的命令。与当前引用通告不同,ls-refs 接受可用于限制服务器发送的引用的参数。
基本命令中不支持的其他功能将以空格分隔的功能列表形式作为命令的值在能力通告中通告:"<命令>=<功能-1> <功能-2>"。
ls-refs 接受以下参数:
symrefs In addition to the object pointed by it, show the underlying ref pointed by it when showing a symbolic ref. peel Show peeled tags. ref-prefix <prefix> When specified, only references having a prefix matching one of the provided prefixes are displayed. Multiple instances may be given, in which case references matching any prefix will be shown. Note that this is purely for optimization; a server MAY show refs not matching the prefix if it chooses, and clients should filter the result themselves.
如果通告了 unborn 功能,则可以在客户端请求中包含以下参数。
unborn The server will send information about HEAD even if it is a symref pointing to an unborn branch in the form "unborn HEAD symref-target:<target>".
ls-refs 的输出如下:
output = *ref flush-pkt obj-id-or-unborn = (obj-id | "unborn") ref = PKT-LINE(obj-id-or-unborn SP refname *(SP ref-attribute) LF) ref-attribute = (symref | peeled) symref = "symref-target:" symref-target peeled = "peeled:" obj-id
fetch
fetch
是 v2 中用于抓取 packfile 的命令。可以将其视为 v1 fetch 的修改版本,其中去除了引用通告(因为 ls-refs
命令承担了该角色),并调整了消息格式以消除冗余并允许轻松添加未来的扩展。
基本命令中不支持的其他功能将以空格分隔的功能列表形式作为命令的值在能力通告中通告:"<命令>=<功能-1> <功能-2>"。
一个 fetch
请求可以接受以下参数:
want <oid> Indicates to the server an object which the client wants to retrieve. Wants can be anything and are not limited to advertised objects.
have <oid> Indicates to the server an object which the client has locally. This allows the server to make a packfile which only contains the objects that the client needs. Multiple 'have' lines can be supplied.
done Indicates to the server that negotiation should terminate (or not even begin if performing a clone) and that the server should use the information supplied in the request to construct the packfile.
thin-pack Request that a thin pack be sent, which is a pack with deltas which reference base objects not contained within the pack (but are known to exist at the receiving end). This can reduce the network traffic significantly, but it requires the receiving end to know how to "thicken" these packs by adding the missing bases to the pack.
no-progress Request that progress information that would normally be sent on side-band channel 2, during the packfile transfer, should not be sent. However, the side-band channel 3 is still used for error responses.
include-tag Request that annotated tags should be sent if the objects they point to are being sent.
ofs-delta Indicate that the client understands PACKv2 with delta referring to its base by position in pack rather than by an oid. That is, they can read OBJ_OFS_DELTA (aka type 6) in a packfile.
如果通告了 shallow 功能,以下参数可以包含在客户端请求中,并且可能在服务器响应中添加 shallow-info 部分,如下所述。
shallow <oid> A client must notify the server of all commits for which it only has shallow copies (meaning that it doesn't have the parents of a commit) by supplying a 'shallow <oid>' line for each such object so that the server is aware of the limitations of the client's history. This is so that the server is aware that the client may not have all objects reachable from such commits.
deepen <depth> Requests that the fetch/clone should be shallow having a commit depth of <depth> relative to the remote side.
deepen-relative Requests that the semantics of the "deepen" command be changed to indicate that the depth requested is relative to the client's current shallow boundary, instead of relative to the requested commits.
deepen-since <timestamp> Requests that the shallow clone/fetch should be cut at a specific time, instead of depth. Internally it's equivalent to doing "git rev-list --max-age=<timestamp>". Cannot be used with "deepen".
deepen-not <rev> Requests that the shallow clone/fetch should be cut at a specific revision specified by '<rev>', instead of a depth. Internally it's equivalent of doing "git rev-list --not <rev>". Cannot be used with "deepen", but can be used with "deepen-since".
如果通告了 filter 功能,则客户端请求中可以包含以下参数:
filter <filter-spec> Request that various objects from the packfile be omitted using one of several filtering techniques. These are intended for use with partial clone and partial fetch operations. See `rev-list` for possible "filter-spec" values. When communicating with other processes, senders SHOULD translate scaled integers (e.g. "1k") into a fully-expanded form (e.g. "1024") to aid interoperability with older receivers that may not understand newly-invented scaling suffixes. However, receivers SHOULD accept the following suffixes: 'k', 'm', and 'g' for 1024, 1048576, and 1073741824, respectively.
如果通告了 ref-in-want 功能,则以下参数可以包含在客户端请求中,并且可能在服务器响应中添加 wanted-refs 部分,如下所述。
want-ref <ref> Indicates to the server that the client wants to retrieve a particular ref, where <ref> is the full name of a ref on the server. It is a protocol error to send want-ref for the same ref more than once.
如果通告了 sideband-all 功能,则以下参数可以包含在客户端请求中:
sideband-all Instruct the server to send the whole response multiplexed, not just the packfile section. All non-flush and non-delim PKT-LINE in the response (not only in the packfile section) will then start with a byte indicating its sideband (1, 2, or 3), and the server may send "0005\2" (a PKT-LINE of sideband 2 with no payload) as a keepalive packet.
如果通告了 packfile-uris 功能,则以下参数可以包含在客户端请求中,并且可能在服务器响应中添加 packfile-uris 部分,如下所述。请注意,最多只能向服务器发送一条 packfile-uris
行。
packfile-uris <comma-separated-list-of-protocols> Indicates to the server that the client is willing to receive URIs of any of the given protocols in place of objects in the sent packfile. Before performing the connectivity check, the client should download from all given URIs. Currently, the protocols supported are "http" and "https".
如果通告了 wait-for-done 功能,则客户端请求中可以包含以下参数。
wait-for-done Indicates to the server that it should never send "ready", but should wait for the client to say "done" before sending the packfile.
fetch
的响应分为多个部分,由分隔符数据包(0001)分隔,每个部分以其节标题开头。大多数部分仅在发送 packfile 时发送。
output = acknowledgements flush-pkt | [acknowledgments delim-pkt] [shallow-info delim-pkt] [wanted-refs delim-pkt] [packfile-uris delim-pkt] packfile flush-pkt
acknowledgments = PKT-LINE("acknowledgments" LF) (nak | *ack) (ready) ready = PKT-LINE("ready" LF) nak = PKT-LINE("NAK" LF) ack = PKT-LINE("ACK" SP obj-id LF)
shallow-info = PKT-LINE("shallow-info" LF) *PKT-LINE((shallow | unshallow) LF) shallow = "shallow" SP obj-id unshallow = "unshallow" SP obj-id
wanted-refs = PKT-LINE("wanted-refs" LF) *PKT-LINE(wanted-ref LF) wanted-ref = obj-id SP refname
packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)
packfile = PKT-LINE("packfile" LF) *PKT-LINE(%x01-03 *%x00-ff)
acknowledgments section * If the client determines that it is finished with negotiations by sending a "done" line (thus requiring the server to send a packfile), the acknowledgments sections MUST be omitted from the server's response.
-
总是以节标题 "acknowledgments" 开头。
-
如果没有一行发送的对象 ID 是共同的,服务器将回复 "NAK"。
-
服务器将对所有发送的共同对象 ID 的 have 行回复 "ACK obj-id"。
-
响应不能同时包含 "ACK" 行和 "NAK" 行。
-
服务器将回复一行 "ready",表示服务器已找到可接受的公共基础,并准备生成和发送一个 packfile(该 packfile 将在同一响应的 packfile 部分中找到)
-
如果服务器找到了合适的切入点并决定发送“ready”行,则服务器可以决定(作为优化)省略其响应中本应发送的任何“ACK”行。这是因为服务器已经确定了它计划发送给客户端的对象,并且不再需要进一步的协商。
shallow-info section * If the client has requested a shallow fetch/clone, a shallow client requests a fetch or the server is shallow then the server's response may include a shallow-info section. The shallow-info section will be included if (due to one of the above conditions) the server needs to inform the client of any shallow boundaries or adjustments to the clients already existing shallow boundaries.
-
总是以节标题 "shallow-info" 开头。
-
如果请求了正深度,服务器将计算深度不大于所需深度的提交集合。
-
服务器为每个其父级不会在后续的 packfile 中发送的提交发送一个“shallow obj-id”行。
-
服务器为每个客户端已指示为浅但由于抓取而不再浅的提交(由于其父级已在后续的 packfile 中发送)发送一个“unshallow obj-id”行。
-
服务器不得发送任何客户端未在其请求中指出是浅的“unshallow”行。
wanted-refs section * This section is only included if the client has requested a ref using a 'want-ref' line and if a packfile section is also included in the response.
-
总是以节标题 "wanted-refs" 开头。
-
服务器将为每个使用 want-ref 行请求的引用发送一个引用列表(“<oid> <refname>”)。
-
服务器不得发送任何未使用 want-ref 行请求的引用。
packfile-uris section * This section is only included if the client sent 'packfile-uris' and the server has at least one such URI to send.
-
总是以节标题 "packfile-uris" 开头。
-
对于服务器发送的每个 URI,它会发送包内容的哈希值(由 git index-pack 输出),后跟 URI。
-
哈希值是 40 个十六进制字符长。当 Git 升级到新的哈希算法时,这可能需要更新。(它应该与 index-pack 在“pack\t”或“keep\t”之后输出的内容匹配。)
packfile section * This section is only included if the client has sent 'want' lines in its request and either requested that no more negotiation be done by sending 'done' or if the server has decided it has found a sufficient cut point to produce a packfile.
-
总是以节标题 "packfile" 开头。
-
packfile 的传输紧随节标题之后开始。
-
packfile 的数据传输总是多路复用的,使用与协议版本 1 中 side-band-64k 能力相同的语义。这意味着在 packfile 数据流期间,每个数据包都由一个前导的 4 字节 pkt-line 长度(典型的 pkt-line 格式)组成,后跟一个 1 字节的流代码,再后跟实际数据。
The stream code can be one of: 1 - pack data 2 - progress messages 3 - fatal error message just before stream aborts
server-option
如果已通告,则表示可以在请求中包含任意数量的服务器特定选项。这通过在请求的能力列表部分中将每个选项作为“server-option=<option>”能力行发送来完成。
提供的选项不得包含 NUL 或 LF 字符。
object-format
服务器可以通告带有值 X
(形式为 object-format=X
)的 object-format
能力,以通知客户端服务器能够处理使用哈希算法 X 的对象。如果未指定,则假定服务器只处理 SHA-1。如果客户端想使用除 SHA-1 以外的哈希算法,它应该指定其 object-format 字符串。
session-id=<session-id>
服务器可以通告一个会话 ID,该 ID 可用于在多个请求中标识此进程。客户端也可以将其自己的会话 ID 回传给服务器。
会话 ID 对于给定进程应该是唯一的。它们必须适应数据包行,并且不得包含不可打印或空白字符。当前的实现使用 trace2 会话 ID(详情请参阅 api-trace2),但这可能会改变,会话 ID 的使用者不应依赖此事实。
object-info
object-info
是检索一个或多个对象信息的命令。其主要目的是允许客户端根据这些信息做出决策,而无需完全抓取对象。目前仅支持对象大小信息。
一个 object-info
请求接受以下参数:
size Requests size information to be returned for each listed object id.
oid <oid> Indicates to the server an object which the client wants to obtain information for.
object-info
的响应是所请求对象 ID 及其相关请求信息的列表,每个之间用一个空格分隔。
output = info flush-pkt
info = PKT-LINE(attrs) LF) *PKT-LINE(obj-info LF)
attrs = attr | attrs SP attrs
attr = "size"
obj-info = obj-id SP obj-size
bundle-uri
如果通告了 bundle-uri 能力,则服务器支持“bundle-uri”命令。
该能力目前没有通告任何值(即不是 "bundle-uri=somevalue"),未来可能会添加一个值以支持命令范围的扩展。客户端必须忽略任何未知的能力值,并继续执行其支持的“bundle-uri”对话。
bundle-uri 命令旨在在 fetch
之前发出,以获取捆绑文件(参见 git-bundle[1])的 URI,从而“播种”并通知后续的 fetch
命令。
客户端可以在任何其他有效命令之前或之后发出 bundle-uri
。为了对客户端有用,它预计将在 ls-refs
之后和 fetch
之前发出,但可以在对话中的任何时间发出。
bundle-uri 的讨论
此功能的目的是通过将 git-clone[1] 期间抓取非常大的 PACK 的常见情况转换为较小的增量抓取来优化服务器资源消耗的常见情况。
它还允许服务器结合 uploadpack.packObjectsHook
(参见 git-config[1])实现更好的缓存。
通过让新的克隆或抓取成为对最新生成的 *.bundle 文件(或文件)的更可预测和常见的协商。服务器甚至可以在新的推送进来时预先生成此类协商的结果,以供 uploadpack.packObjectsHook
使用。
服务器可以利用这些捆绑包的一种方式是,服务器会预料到新的克隆将下载一个已知捆绑包,然后使用该捆绑包(或捆绑包)中找到的引用提示来追赶存储库的当前状态。
bundle-uri 协议
一个 bundle-uri
请求不带任何参数,如上所述,目前不通告能力值。两者都可能在未来添加。
当客户端发出 command=bundle-uri
请求时,响应是一个键值对列表,以数据包行形式提供,值为 <key>=
<value>。每个 <key> 都应解释为 bundle.*
命名空间中的配置键,以构建一个捆绑包列表。这些键按 bundle.
<id>.
小节分组,其中每个与给定 <id> 对应的键都为该 <id> 定义的捆绑包贡献属性。有关这些键的具体细节以及 Git 客户端如何解释其值,请参阅 git-config[1]。
客户端必须按照上述格式解析行,不符合格式的行应该被丢弃。在这种情况下,可以警告用户。
bundle-uri 客户端和服务器期望
- URI 内容
-
通告的 URI 内容必须是以下两种类型之一。
通告的 URI 可能包含一个
git
bundle
verify
会接受的 bundle 文件。即,它们必须包含一个或多个供客户端使用的引用提示,必须使用标准“-”前缀指示先决条件(如果有),并且必须指示其“object-format”(如果适用)。通告的 URI 也可以包含一个
git
config
--list
会接受的纯文本文件(带--file
选项)。此列表中的键值对位于bundle.*
命名空间中(参见 git-config[1])。 - bundle-uri 客户端错误恢复
-
客户端必须最重要的是优雅地处理错误,无论该错误是由于捆绑 URI 中缺少/数据错误,还是因为客户端太笨而无法理解并完全解析捆绑标头及其先决条件关系,或其他原因。
服务器运营商应该放心地开启“bundle-uri”,并且不必担心,例如,如果其 CDN 出现故障,克隆或抓取会遇到硬性故障。即使服务器捆绑包不完整或存在某种问题,客户端仍应以正常运行的存储库结束,就像它选择不使用此协议扩展一样。
所有后续关于客户端和服务器交互的讨论都必须牢记这一点。
- bundle-uri 服务器到客户端
-
返回的捆绑 URI 的顺序不重要。客户端必须解析其头部以发现其中包含的 OID 和先决条件。客户端必须将捆绑包本身及其头部的内容视为最终的真相来源。
服务器甚至可以返回与正在克隆的存储库没有任何直接关系的捆绑包(无论是偶然还是故意“巧妙”配置),并期望客户端整理出他们希望从捆绑包中获取哪些数据(如果有)。
- bundle-uri 客户端到服务器
-
客户端应在随后的
fetch
请求中提供捆绑标头中找到的引用提示作为 have 行。客户端也可以完全忽略捆绑包,如果认为这样做出于某种原因更糟糕,例如如果捆绑包无法下载,它不喜欢它找到的提示等。 - 当通告的捆绑包不需要进一步协商时
-
如果在发出
bundle-uri
和ls-refs
后,并获取捆绑包的头部信息,客户端发现其想要的引用提示可以完全从通告的捆绑包中检索,则客户端可以断开与 Git 服务器的连接。这样一次 clone 或 fetch 的结果应与不使用 bundle-uri 获得的状态没有区别。 - 早期客户端断开连接和错误恢复
-
客户端在仍在下载捆绑包时(已流式传输并解析其标头)可以执行早期断开连接。在这种情况下,客户端必须优雅地从与完成捆绑包下载和验证相关的任何错误中恢复。
即,客户端可能需要重新连接并发出 fetch 命令,并可能完全回退到不使用 bundle-uri。
这种“可以”行为被如此指定(而不是“应该”),是基于以下假设:通告捆绑 URI 的服务器更有可能提供一个相对较大的存储库,并且指向有良好机会正常工作的 URI。客户端可以,例如,将捆绑包的有效载荷大小作为启发式方法,以查看是否值得提前断开连接,如果需要回退到完整的“fetch”对话框的话。
- 当通告的捆绑包需要进一步协商时
-
客户端应通过“fetch”命令,使用通告捆绑包中找到的 OID 提示,开始与服务器协商 PACK,即使它仍在下载这些捆绑包。
这允许从任何交互式服务器对话中积极地早期断开连接。客户端盲目地相信通告的 OID 提示是相关的,并将其作为 have 行发出,然后它通过 want 行请求任何它想要的提示(通常来自“ls-refs”通告)。服务器将计算一个(希望很小)的 PACK,其中包含捆绑包中的提示与所请求数据之间的预期差异。
客户端随后需要保持活跃的唯一连接是到并发下载的静态捆绑包,当这些捆绑包和增量 PACK 被检索后,应进行解压和验证。此时发生的任何错误都应得到优雅恢复,请参见上文。
bundle-uri 协议功能
客户端根据服务器提供的 <key>=
<value> 对构建捆绑包列表。这些对属于 git-config[1] 中记录的 bundle.*
命名空间。在本节中,我们将讨论其中一些键,并描述客户端将根据这些信息执行的操作。
特别是,bundle.version
键指定一个整数值。目前唯一接受的值是 1
,但如果客户端在此处看到意外值,则客户端必须忽略捆绑包列表。
只要 bundle.version
被理解,所有其他未知键都可以被客户端忽略。服务器将保证与旧客户端的兼容性,尽管新客户端可能能够更好地使用额外的键来最小化下载。
任何向后不兼容的预 URI 键值添加都将通过新的 bundle.version
值或 bundle-uri 能力通告本身中的值,和/或通过新的未来 bundle-uri
请求参数进行保护。
一些目前未实现但将来可能实现的示例键值对包括:
-
添加 "hash=<val>" 或 "size=<bytes>" 以通告捆绑文件的预期哈希或大小。
-
通告一个或多个捆绑文件是相同的(例如,让客户端轮询或以其他方式选择 N 个可能文件中的一个)。
-
“oid=<OID>”快捷方式和“prerequisite=<OID>”快捷方式。用于表达具有一个提示且没有先决条件,或一个提示和一个先决条件的常见捆绑包情况。
这将允许优化服务器的常见情况,即提供一个只包含其“主”分支的“大捆绑包”,和/或其增量更新。
收到此类响应的客户端可以假定它们可以跳过从指定 URI 的捆绑包中检索头部,从而节省自身和服务器检查该捆绑包或捆绑包头部所需的请求。
promisor-remote=<pr-infos>
服务器可以向客户端通告它正在使用或知道的一些承诺者远程仓库,客户端可能希望将它们用作其承诺者远程仓库,而不是此存储库。在这种情况下,<pr-infos> 应采用以下形式:
pr-infos = pr-info | pr-infos ";" pr-info
pr-info = "name=" pr-name | "name=" pr-name "," "url=" pr-url
其中 pr-name
是一个承诺者远程仓库的 URL 编码名称,pr-url
是该承诺者远程仓库的 URL 编码 URL。
在这种情况下,如果客户端决定使用服务器通告的一个或多个承诺者远程仓库,它可以回复 "promisor-remote=<pr-names>",其中 <pr-names> 应采用以下形式:
pr-names = pr-name | pr-names ";" pr-name
其中 pr-name
是服务器通告且客户端接受的承诺者远程的 URL 编码名称。
请注意,本文档中所有地方,pr-name
必须是有效的远程名称,并且如果字符 ; 和 , 出现在 pr-name
或 pr-url
中,则必须进行编码。
如果服务器不知道任何可能对客户端有用的承诺者远程仓库,或者更希望客户端不使用它正在使用或知道的任何承诺者远程仓库,则它根本不应该通告“promisor-remote”能力。
在这种情况下,或者如果客户端不希望使用服务器通告的任何承诺者远程仓库,客户端不应该在其回复中通告“promisor-remote”能力。
“promisor.advertise”和“promisor.acceptFromServer”配置选项可用于服务器和客户端,分别控制它们通告或接受的内容。有关这些配置选项的更多信息,请参阅其文档。
请注意,未来如果服务器在响应 git
fetch
或 git
clone
时,能够使用“promisor-remote”协议功能来通告与客户端连接更佳的远程仓库作为承诺者远程仓库,而不是当前的存储库,那将是很好的。这样客户端就可以从这些连接更佳的远程仓库延迟抓取对象。这将要求服务器在其响应中省略在客户端已接受的连接更佳的远程仓库上可用的对象。然而,这尚未实现。因此,目前“promisor-remote”功能仅在服务器通告其已用于借用对象的一些承诺者远程仓库时才有用。