1 Git Protocol Capabilities
2 =========================
4 NOTE: this document describes capabilities for versions 0 and 1 of the pack
5 protocol. For version 2, please refer to the link:protocol-v2.html[protocol-v2]
8 Servers SHOULD support all capabilities defined in this document.
10 On the very first line of the initial server response of either
11 receive-pack and upload-pack the first reference is followed by
12 a NUL byte and then a list of space delimited server capabilities.
13 These allow the server to declare what it can and cannot support
16 Client will then send a space separated list of capabilities it wants
17 to be in effect. The client MUST NOT ask for capabilities the server
18 did not say it supports.
20 Server MUST diagnose and abort if capabilities it does not understand
21 was sent. Server MUST NOT ignore capabilities that client requested
22 and server advertised. As a consequence of these rules, server MUST
23 NOT advertise capabilities it does not understand.
25 The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert'
26 capabilities are sent and recognized by the receive-pack (push to server)
29 The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
30 by both upload-pack and receive-pack protocols. The 'agent' capability
31 may optionally be sent in both protocols.
33 All other capabilities are only recognized by the upload-pack (fetch
39 The 'multi_ack' capability allows the server to return "ACK obj-id
40 continue" as soon as it finds a commit that it can use as a common
41 base, between the client's wants and the client's have set.
43 By sending this early, the server can potentially head off the client
44 from walking any further down that particular branch of the client's
45 repository history. The client may still need to walk down other
46 branches, sending have lines for those, until the server has a
47 complete cut across the DAG, or the client has said "done".
49 Without multi_ack, a client sends have lines in --date-order until
50 the server has found a common base. That means the client will send
51 have lines that are already known by the server to be common, because
52 they overlap in time with another branch that the server hasn't found
55 For example suppose the client has commits in caps that the server
56 doesn't and the server has commits in lower case that the client
57 doesn't, as in the following diagram:
59 +---- u ---------------------- x
62 a -- b -- c -- d -- E -- F
66 If the client wants x,y and starts out by saying have F,S, the server
67 doesn't know what F,S is. Eventually the client says "have d" and
68 the server sends "ACK d continue" to let the client know to stop
69 walking down that line (so don't send c-b-a), but it's not done yet,
70 it needs a base for x. The client keeps going with S-R-Q, until a
71 gets reached, at which point the server has a clear base and it all
74 Without multi_ack the client would have sent that c-b-a chain anyway,
75 interleaved with S-R-Q.
79 This is an extension of multi_ack that permits client to better
80 understand the server's in-memory state. See pack-protocol.txt,
81 section "Packfile Negotiation" for more information.
85 This capability should only be used with the smart HTTP protocol. If
86 multi_ack_detailed and no-done are both present, then the sender is
87 free to immediately send a pack following its first "ACK obj-id ready"
90 Without no-done in the smart HTTP protocol, the server session would
91 end and the client has to make another trip to send "done" before
92 the server can send the pack. no-done removes the last round and
93 thus slightly reduces latency.
98 A thin pack is one with deltas which reference base objects not
99 contained within the pack (but are known to exist at the receiving
100 end). This can reduce the network traffic significantly, but it
101 requires the receiving end to know how to "thicken" these packs by
102 adding the missing bases to the pack.
104 The upload-pack server advertises 'thin-pack' when it can generate
105 and send a thin pack. A client requests the 'thin-pack' capability
106 when it understands how to "thicken" it, notifying the server that
107 it can receive such a pack. A client MUST NOT request the
108 'thin-pack' capability if it cannot turn a thin pack into a
111 Receive-pack, on the other hand, is assumed by default to be able to
112 handle thin packs, but can ask the client not to use the feature by
113 advertising the 'no-thin' capability. A client MUST NOT send a thin
114 pack if the server advertises the 'no-thin' capability.
116 The reasons for this asymmetry are historical. The receive-pack
117 program did not exist until after the invention of thin packs, so
118 historically the reference implementation of receive-pack always
119 understood thin packs. Adding 'no-thin' later allowed receive-pack
120 to disable the feature in a backwards-compatible manner.
123 side-band, side-band-64k
124 ------------------------
126 This capability means that server can send, and client understand multiplexed
127 progress reports and error info interleaved with the packfile itself.
129 These two options are mutually exclusive. A modern client always
130 favors 'side-band-64k'.
132 Either mode indicates that the packfile data will be streamed broken
133 up into packets of up to either 1000 bytes in the case of 'side_band',
134 or 65520 bytes in the case of 'side_band_64k'. Each packet is made up
135 of a leading 4-byte pkt-line length of how much data is in the packet,
136 followed by a 1-byte stream code, followed by the actual data.
138 The stream code can be one of:
141 2 - progress messages
142 3 - fatal error message just before stream aborts
144 The "side-band-64k" capability came about as a way for newer clients
145 that can handle much larger packets to request packets that are
146 actually crammed nearly full, while maintaining backward compatibility
147 for the older clients.
149 Further, with side-band and its up to 1000-byte messages, it's actually
150 999 bytes of payload and 1 byte for the stream code. With side-band-64k,
151 same deal, you have up to 65519 bytes of data and 1 byte for the stream
154 The client MUST send only maximum of one of "side-band" and "side-
155 band-64k". Server MUST diagnose it as an error if client requests
161 Server can send, and client understand PACKv2 with delta referring to
162 its base by position in pack rather than by an obj-id. That is, they can
163 send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
168 The server may optionally send a capability of the form `agent=X` to
169 notify the client that the server is running version `X`. The client may
170 optionally return its own agent string by responding with an `agent=Y`
171 capability (but it MUST NOT do so if the server did not mention the
172 agent capability). The `X` and `Y` strings may contain any printable
173 ASCII characters except space (i.e., the byte range 32 < x < 127), and
174 are typically of the form "package/version" (e.g., "git/1.8.3.1"). The
175 agent strings are purely informative for statistics and debugging
176 purposes, and MUST NOT be used to programmatically assume the presence
177 or absence of particular features.
182 This capability, which takes a hash algorithm as an argument, indicates
183 that the server supports the given hash algorithms. It may be sent
184 multiple times; if so, the first one given is the one used in the ref
187 When provided by the client, this indicates that it intends to use the
188 given hash algorithm to communicate. The algorithm provided must be one
189 that the server supports.
191 If this capability is not provided, it is assumed that the only
192 supported algorithm is SHA-1.
197 This parameterized capability is used to inform the receiver which symbolic ref
198 points to which ref; for example, "symref=HEAD:refs/heads/master" tells the
199 receiver that HEAD points to master. This capability can be repeated to
200 represent multiple symrefs.
202 Servers SHOULD include this capability for the HEAD symref if it is one of the
205 Clients MAY use the parameters from this capability to select the proper initial
206 branch when cloning a repository.
211 This capability adds "deepen", "shallow" and "unshallow" commands to
212 the fetch-pack/upload-pack protocol so clients can request shallow
218 This capability adds "deepen-since" command to fetch-pack/upload-pack
219 protocol so the client can request shallow clones that are cut at a
220 specific time, instead of depth. Internally it's equivalent of doing
221 "rev-list --max-age=<timestamp>" on the server side. "deepen-since"
222 cannot be used with "deepen".
227 This capability adds "deepen-not" command to fetch-pack/upload-pack
228 protocol so the client can request shallow clones that are cut at a
229 specific revision, instead of depth. Internally it's equivalent of
230 doing "rev-list --not <rev>" on the server side. "deepen-not"
231 cannot be used with "deepen", but can be used with "deepen-since".
236 If this capability is requested by the client, the semantics of
237 "deepen" command is changed. The "depth" argument is the depth from
238 the current shallow boundary, instead of the depth from remote refs.
243 The client was started with "git clone -q" or something, and doesn't
244 want that side band 2. Basically the client just says "I do not
245 wish to receive stream 2 on sideband, so do not send it to me, and if
246 you did, I will drop it on the floor anyway". However, the sideband
247 channel 3 is still used for error responses.
252 The 'include-tag' capability is about sending annotated tags if we are
253 sending objects they point to. If we pack an object to the client, and
254 a tag object points exactly at that object, we pack the tag object too.
255 In general this allows a client to get all new annotated tags when it
256 fetches a branch, in a single network connection.
258 Clients MAY always send include-tag, hardcoding it into a request when
259 the server advertises this capability. The decision for a client to
260 request include-tag only has to do with the client's desires for tag
261 data, whether or not a server had advertised objects in the
262 refs/tags/* namespace.
264 Servers MUST pack the tags if their referrant is packed and the client
265 has requested include-tags.
267 Clients MUST be prepared for the case where a server has ignored
268 include-tag and has not actually sent tags in the pack. In such
269 cases the client SHOULD issue a subsequent fetch to acquire the tags
270 that include-tag would have otherwise given the client.
272 The server SHOULD send include-tag, if it supports it, regardless
273 of whether or not there are tags available.
278 The receive-pack process can receive a 'report-status' capability,
279 which tells it that the client wants a report of what happened after
280 a packfile upload and reference update. If the pushing client requests
281 this capability, after unpacking and updating references the server
282 will respond with whether the packfile unpacked successfully and if
283 each reference was updated successfully. If any of those were not
284 successful, it will send back an error message. See pack-protocol.txt
285 for example messages.
290 If the server sends back the 'delete-refs' capability, it means that
291 it is capable of accepting a zero-id value as the target
292 value of a reference update. It is not sent back by the client, it
293 simply informs the client that it can be sent zero-id values
294 to delete references.
299 If the receive-pack server advertises the 'quiet' capability, it is
300 capable of silencing human-readable progress output which otherwise may
301 be shown when processing the received pack. A send-pack client should
302 respond with the 'quiet' capability to suppress server-side progress
303 reporting if the local progress reporting is also being suppressed
304 (e.g., via `push -q`, or if stderr does not go to a tty).
309 If the server sends the 'atomic' capability it is capable of accepting
310 atomic pushes. If the pushing client requests this capability, the server
311 will update the refs in one atomic transaction. Either all refs are
317 If the server sends the 'push-options' capability it is able to accept
318 push options after the update commands have been sent, but before the
319 packfile is streamed. If the pushing client requests this capability,
320 the server will pass the options to the pre- and post- receive hooks
321 that process this push request.
323 allow-tip-sha1-in-want
324 ----------------------
326 If the upload-pack server advertises this capability, fetch-pack may
327 send "want" lines with SHA-1s that exist at the server but are not
328 advertised by upload-pack.
330 allow-reachable-sha1-in-want
331 ----------------------------
333 If the upload-pack server advertises this capability, fetch-pack may
334 send "want" lines with SHA-1s that exist at the server but are not
335 advertised by upload-pack.
340 The receive-pack server that advertises this capability is willing
341 to accept a signed push certificate, and asks the <nonce> to be
342 included in the push certificate. A send-pack client MUST NOT
343 send a push-cert packet unless the receive-pack server advertises
349 If the upload-pack server advertises the 'filter' capability,
350 fetch-pack may send "filter" commands to request a partial clone
351 or partial fetch and request that the server omit various objects
projects / git / blob