]>
Commit | Line | Data |
---|---|---|
b31222cf SC |
1 | Git Protocol Capabilities |
2 | ========================= | |
3 | ||
90503a24 JS |
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] | |
6 | doc. | |
7 | ||
b31222cf SC |
8 | Servers SHOULD support all capabilities defined in this document. |
9 | ||
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 | |
14 | to the client. | |
15 | ||
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. | |
19 | ||
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. | |
24 | ||
b913075c JX |
25 | The 'atomic', 'report-status', 'report-status-v2', 'delete-refs', 'quiet', |
26 | and 'push-cert' capabilities are sent and recognized by the receive-pack | |
27 | (push to server) process. | |
b31222cf | 28 | |
9354b9a4 | 29 | The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized |
af608260 JK |
30 | by both upload-pack and receive-pack protocols. The 'agent' capability |
31 | may optionally be sent in both protocols. | |
b31222cf SC |
32 | |
33 | All other capabilities are only recognized by the upload-pack (fetch | |
34 | from server) process. | |
35 | ||
36 | multi_ack | |
37 | --------- | |
38 | ||
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. | |
42 | ||
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". | |
48 | ||
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 | |
53 | a common base on yet. | |
54 | ||
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: | |
58 | ||
59 | +---- u ---------------------- x | |
60 | / +----- y | |
61 | / / | |
62 | a -- b -- c -- d -- E -- F | |
63 | \ | |
64 | +--- Q -- R -- S | |
65 | ||
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 | |
6a5d0b0a | 69 | walking down that line (so don't send c-b-a), but it's not done yet, |
b31222cf SC |
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 | |
72 | ends. | |
73 | ||
74 | Without multi_ack the client would have sent that c-b-a chain anyway, | |
75 | interleaved with S-R-Q. | |
76 | ||
087e347f NTND |
77 | multi_ack_detailed |
78 | ------------------ | |
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. | |
82 | ||
c9cd60f6 NTND |
83 | no-done |
84 | ------- | |
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" | |
88 | message. | |
89 | ||
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. | |
94 | ||
b31222cf SC |
95 | thin-pack |
96 | --------- | |
97 | ||
1ba98a79 CMN |
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. | |
103 | ||
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 | |
109 | self-contained pack. | |
110 | ||
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. | |
115 | ||
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. | |
b31222cf SC |
121 | |
122 | ||
123 | side-band, side-band-64k | |
124 | ------------------------ | |
125 | ||
126 | This capability means that server can send, and client understand multiplexed | |
127 | progress reports and error info interleaved with the packfile itself. | |
128 | ||
129 | These two options are mutually exclusive. A modern client always | |
130 | favors 'side-band-64k'. | |
131 | ||
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. | |
137 | ||
138 | The stream code can be one of: | |
139 | ||
140 | 1 - pack data | |
141 | 2 - progress messages | |
142 | 3 - fatal error message just before stream aborts | |
143 | ||
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. | |
148 | ||
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 | |
152 | code. | |
153 | ||
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 | |
156 | both. | |
157 | ||
158 | ofs-delta | |
159 | --------- | |
160 | ||
5d1e3415 | 161 | Server can send, and client understand PACKv2 with delta referring to |
b31222cf SC |
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. | |
164 | ||
af608260 JK |
165 | agent |
166 | ----- | |
167 | ||
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 | |
f745acb0 | 176 | purposes, and MUST NOT be used to programmatically assume the presence |
af608260 JK |
177 | or absence of particular features. |
178 | ||
b8615c3c | 179 | object-format |
180 | ------------- | |
181 | ||
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 | |
185 | advertisement. | |
186 | ||
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. | |
190 | ||
191 | If this capability is not provided, it is assumed that the only | |
192 | supported algorithm is SHA-1. | |
193 | ||
90503a24 JS |
194 | symref |
195 | ------ | |
196 | ||
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. | |
201 | ||
202 | Servers SHOULD include this capability for the HEAD symref if it is one of the | |
203 | refs being sent. | |
204 | ||
205 | Clients MAY use the parameters from this capability to select the proper initial | |
206 | branch when cloning a repository. | |
207 | ||
b31222cf SC |
208 | shallow |
209 | ------- | |
210 | ||
211 | This capability adds "deepen", "shallow" and "unshallow" commands to | |
212 | the fetch-pack/upload-pack protocol so clients can request shallow | |
213 | clones. | |
214 | ||
569e554b NTND |
215 | deepen-since |
216 | ------------ | |
217 | ||
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". | |
223 | ||
269a7a83 NTND |
224 | deepen-not |
225 | ---------- | |
226 | ||
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". | |
232 | ||
cccf74e2 NTND |
233 | deepen-relative |
234 | --------------- | |
235 | ||
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. | |
239 | ||
b31222cf SC |
240 | no-progress |
241 | ----------- | |
242 | ||
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. | |
248 | ||
249 | include-tag | |
250 | ----------- | |
251 | ||
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. | |
257 | ||
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. | |
263 | ||
264 | Servers MUST pack the tags if their referrant is packed and the client | |
265 | has requested include-tags. | |
266 | ||
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. | |
271 | ||
272 | The server SHOULD send include-tag, if it supports it, regardless | |
273 | of whether or not there are tags available. | |
274 | ||
275 | report-status | |
276 | ------------- | |
277 | ||
9a621ad0 | 278 | The receive-pack process can receive a 'report-status' capability, |
b31222cf SC |
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. | |
286 | ||
b913075c JX |
287 | report-status-v2 |
288 | ---------------- | |
289 | ||
290 | Capability 'report-status-v2' extends capability 'report-status' by | |
291 | adding new "option" directives in order to support reference rewritten by | |
292 | the "proc-receive" hook. The "proc-receive" hook may handle a command | |
293 | for a pseudo-reference which may create or update a reference with | |
294 | different name, new-oid, and old-oid. While the capability | |
295 | 'report-status' cannot report for such case. See pack-protocol.txt | |
296 | for details. | |
297 | ||
b31222cf SC |
298 | delete-refs |
299 | ----------- | |
300 | ||
301 | If the server sends back the 'delete-refs' capability, it means that | |
6a5d0b0a | 302 | it is capable of accepting a zero-id value as the target |
b31222cf SC |
303 | value of a reference update. It is not sent back by the client, it |
304 | simply informs the client that it can be sent zero-id values | |
305 | to delete references. | |
69fb9603 JK |
306 | |
307 | quiet | |
308 | ----- | |
309 | ||
310 | If the receive-pack server advertises the 'quiet' capability, it is | |
311 | capable of silencing human-readable progress output which otherwise may | |
312 | be shown when processing the received pack. A send-pack client should | |
313 | respond with the 'quiet' capability to suppress server-side progress | |
314 | reporting if the local progress reporting is also being suppressed | |
315 | (e.g., via `push -q`, or if stderr does not go to a tty). | |
4acbe91a | 316 | |
1b70fe5d RS |
317 | atomic |
318 | ------ | |
319 | ||
320 | If the server sends the 'atomic' capability it is capable of accepting | |
321 | atomic pushes. If the pushing client requests this capability, the server | |
322 | will update the refs in one atomic transaction. Either all refs are | |
323 | updated or none. | |
324 | ||
c714e45f SB |
325 | push-options |
326 | ------------ | |
327 | ||
328 | If the server sends the 'push-options' capability it is able to accept | |
329 | push options after the update commands have been sent, but before the | |
330 | packfile is streamed. If the pushing client requests this capability, | |
331 | the server will pass the options to the pre- and post- receive hooks | |
332 | that process this push request. | |
333 | ||
4acbe91a NTND |
334 | allow-tip-sha1-in-want |
335 | ---------------------- | |
336 | ||
337 | If the upload-pack server advertises this capability, fetch-pack may | |
0756e610 MÅ |
338 | send "want" lines with object names that exist at the server but are not |
339 | advertised by upload-pack. For historical reasons, the name of this | |
340 | capability contains "sha1". Object names are always given using the | |
341 | object format negotiated through the 'object-format' capability. | |
4adf569d | 342 | |
68ee6289 FM |
343 | allow-reachable-sha1-in-want |
344 | ---------------------------- | |
345 | ||
346 | If the upload-pack server advertises this capability, fetch-pack may | |
0756e610 MÅ |
347 | send "want" lines with object names that exist at the server but are not |
348 | advertised by upload-pack. For historical reasons, the name of this | |
349 | capability contains "sha1". Object names are always given using the | |
350 | object format negotiated through the 'object-format' capability. | |
68ee6289 | 351 | |
b89363e4 JH |
352 | push-cert=<nonce> |
353 | ----------------- | |
4adf569d JH |
354 | |
355 | The receive-pack server that advertises this capability is willing | |
b89363e4 JH |
356 | to accept a signed push certificate, and asks the <nonce> to be |
357 | included in the push certificate. A send-pack client MUST NOT | |
4adf569d JH |
358 | send a push-cert packet unless the receive-pack server advertises |
359 | this capability. | |
10ac85c7 JH |
360 | |
361 | filter | |
362 | ------ | |
363 | ||
364 | If the upload-pack server advertises the 'filter' capability, | |
365 | fetch-pack may send "filter" commands to request a partial clone | |
366 | or partial fetch and request that the server omit various objects | |
367 | from the packfile. |