freshlybakedca.ke
Git fork
1gitprotocol-capabilities(5)
2===========================
3
4NAME
5----
6gitprotocol-capabilities - Protocol v0 and v1 capabilities
7
8SYNOPSIS
9--------
10[verse]
11<over-the-wire-protocol>
12
13DESCRIPTION
14-----------
15
16NOTE: this document describes capabilities for versions 0 and 1 of the pack
17protocol. For version 2, please refer to the linkgit:gitprotocol-v2[5]
18doc.
19
20Servers SHOULD support all capabilities defined in this document.
21
22On the very first line of the initial server response of either
23receive-pack and upload-pack the first reference is followed by
24a NUL byte and then a list of space delimited server capabilities.
25These allow the server to declare what it can and cannot support
26to the client.
27
28Client will then send a space separated list of capabilities it wants
29to be in effect. The client MUST NOT ask for capabilities the server
30did not say it supports.
31
32Server MUST diagnose and abort if capabilities it does not understand
33were sent. Server MUST NOT ignore capabilities that client requested
34and server advertised. As a consequence of these rules, server MUST
35NOT advertise capabilities it does not understand.
36
37The 'atomic', 'report-status', 'report-status-v2', 'delete-refs', 'quiet',
38and 'push-cert' capabilities are sent and recognized by the receive-pack
39(push to server) process.
40
41The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
42by both upload-pack and receive-pack protocols. The 'agent' and 'session-id'
43capabilities may optionally be sent in both protocols.
44
45All other capabilities are only recognized by the upload-pack (fetch
46from server) process.
47
48multi_ack
49---------
50
51The 'multi_ack' capability allows the server to return "ACK obj-id
52continue" as soon as it finds a commit that it can use as a common
53base, between the client's wants and the client's have set.
54
55By sending this early, the server can potentially head off the client
56from walking any further down that particular branch of the client's
57repository history. The client may still need to walk down other
58branches, sending have lines for those, until the server has a
59complete cut across the DAG, or the client has said "done".
60
61Without multi_ack, a client sends have lines in --date-order until
62the server has found a common base. That means the client will send
63have lines that are already known by the server to be common, because
64they overlap in time with another branch on which the server hasn't found
65a common base yet.
66
67For example suppose the client has commits in caps that the server
68doesn't and the server has commits in lower case that the client
69doesn't, as in the following diagram:
70
71 +---- u ---------------------- x
72 / +----- y
73 / /
74 a -- b -- c -- d -- E -- F
75 \
76 +--- Q -- R -- S
77
78If the client wants x,y and starts out by saying have F,S, the server
79doesn't know what F,S is. Eventually the client says "have d" and
80the server sends "ACK d continue" to let the client know to stop
81walking down that line (so don't send c-b-a), but it's not done yet,
82it needs a base for x. The client keeps going with S-R-Q, until a
83gets reached, at which point the server has a clear base and it all
84ends.
85
86Without multi_ack the client would have sent that c-b-a chain anyway,
87interleaved with S-R-Q.
88
89multi_ack_detailed
90------------------
91This is an extension of multi_ack that permits the client to better
92understand the server's in-memory state. See linkgit:gitprotocol-pack[5],
93section "Packfile Negotiation" for more information.
94
95no-done
96-------
97This capability should only be used with the smart HTTP protocol. If
98multi_ack_detailed and no-done are both present, then the sender is
99free to immediately send a pack following its first "ACK obj-id ready"
100message.
101
102Without no-done in the smart HTTP protocol, the server session would
103end and the client has to make another trip to send "done" before
104the server can send the pack. no-done removes the last round and
105thus slightly reduces latency.
106
107thin-pack
108---------
109
110A thin pack is one with deltas which reference base objects not
111contained within the pack (but are known to exist at the receiving
112end). This can reduce the network traffic significantly, but it
113requires the receiving end to know how to "thicken" these packs by
114adding the missing bases to the pack.
115
116The upload-pack server advertises 'thin-pack' when it can generate
117and send a thin pack. A client requests the 'thin-pack' capability
118when it understands how to "thicken" it, notifying the server that
119it can receive such a pack. A client MUST NOT request the
120'thin-pack' capability if it cannot turn a thin pack into a
121self-contained pack.
122
123Receive-pack, on the other hand, is assumed by default to be able to
124handle thin packs, but can ask the client not to use the feature by
125advertising the 'no-thin' capability. A client MUST NOT send a thin
126pack if the server advertises the 'no-thin' capability.
127
128The reasons for this asymmetry are historical. The receive-pack
129program did not exist until after the invention of thin packs, so
130historically the reference implementation of receive-pack always
131understood thin packs. Adding 'no-thin' later allowed receive-pack
132to disable the feature in a backwards-compatible manner.
133
134
135side-band, side-band-64k
136------------------------
137
138This capability means that the server can send, and the client can understand, multiplexed
139progress reports and error info interleaved with the packfile itself.
140
141These two options are mutually exclusive. A modern client always
142favors 'side-band-64k'.
143
144Either mode indicates that the packfile data will be streamed broken
145up into packets of up to either 1000 bytes in the case of 'side_band',
146or 65520 bytes in the case of 'side_band_64k'. Each packet is made up
147of a leading 4-byte pkt-line length of how much data is in the packet,
148followed by a 1-byte stream code, followed by the actual data.
149
150The stream code can be one of:
151
152 1 - pack data
153 2 - progress messages
154 3 - fatal error message just before stream aborts
155
156The "side-band-64k" capability came about as a way for newer clients
157that can handle much larger packets to request packets that are
158actually crammed nearly full, while maintaining backward compatibility
159for the older clients.
160
161Further, with side-band and its up to 1000-byte messages, it's actually
162999 bytes of payload and 1 byte for the stream code. With side-band-64k,
163same deal, you have up to 65519 bytes of data and 1 byte for the stream
164code.
165
166The client MUST send only one of "side-band" and "side-
167band-64k". The server MUST diagnose it as an error if client requests
168both.
169
170ofs-delta
171---------
172
173The server can send, and the client can understand, PACKv2 with delta referring to
174its base by position in pack rather than by an obj-id. That is, they can
175send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
176
177agent
178-----
179
180The server may optionally send a capability of the form `agent=X` to
181notify the client that the server is running version `X`. The client may
182optionally return its own agent string by responding with an `agent=Y`
183capability (but it MUST NOT do so if the server did not mention the
184agent capability). The `X` and `Y` strings may contain any printable
185ASCII characters except space (i.e., the byte range 32 < x < 127), and
186are typically of the form "package/version" (e.g., "git/1.8.3.1"). The
187agent strings are purely informative for statistics and debugging
188purposes, and MUST NOT be used to programmatically assume the presence
189or absence of particular features.
190
191object-format
192-------------
193
194This capability, which takes a hash algorithm as an argument, indicates
195that the server supports the given hash algorithms. It may be sent
196multiple times; if so, the first one given is the one used in the ref
197advertisement.
198
199When provided by the client, this indicates that it intends to use the
200given hash algorithm to communicate. The algorithm provided must be one
201that the server supports.
202
203If this capability is not provided, it is assumed that the only
204supported algorithm is SHA-1.
205
206symref
207------
208
209This parameterized capability is used to inform the receiver which symbolic ref
210points to which ref; for example, "symref=HEAD:refs/heads/master" tells the
211receiver that HEAD points to master. This capability can be repeated to
212represent multiple symrefs.
213
214Servers SHOULD include this capability for the HEAD symref if it is one of the
215refs being sent.
216
217Clients MAY use the parameters from this capability to select the proper initial
218branch when cloning a repository.
219
220shallow
221-------
222
223This capability adds "deepen", "shallow" and "unshallow" commands to
224the fetch-pack/upload-pack protocol so clients can request shallow
225clones.
226
227deepen-since
228------------
229
230This capability adds "deepen-since" command to fetch-pack/upload-pack
231protocol so the client can request shallow clones that are cut at a
232specific time, instead of depth. Internally it's equivalent of doing
233"rev-list --max-age=<timestamp>" on the server side. "deepen-since"
234cannot be used with "deepen".
235
236deepen-not
237----------
238
239This capability adds "deepen-not" command to fetch-pack/upload-pack
240protocol so the client can request shallow clones that are cut at a
241specific revision, instead of depth. Internally it's equivalent of
242doing "rev-list --not <rev>" on the server side. "deepen-not"
243cannot be used with "deepen", but can be used with "deepen-since".
244
245deepen-relative
246---------------
247
248If this capability is requested by the client, the semantics of
249"deepen" command is changed. The "depth" argument is the depth from
250the current shallow boundary, instead of the depth from remote refs.
251
252no-progress
253-----------
254
255The client was started with "git clone -q" or something similar, and doesn't
256want that side band 2. Basically the client just says "I do not
257wish to receive stream 2 on sideband, so do not send it to me, and if
258you did, I will drop it on the floor anyway". However, the sideband
259channel 3 is still used for error responses.
260
261include-tag
262-----------
263
264The 'include-tag' capability is about sending annotated tags if we are
265sending objects they point to. If we pack an object to the client, and
266a tag object points exactly at that object, we pack the tag object too.
267In general this allows a client to get all new annotated tags when it
268fetches a branch, in a single network connection.
269
270Clients MAY always send include-tag, hardcoding it into a request when
271the server advertises this capability. The decision for a client to
272request include-tag only has to do with the client's desires for tag
273data, whether or not a server had advertised objects in the
274refs/tags/* namespace.
275
276Servers MUST pack the tags if their referent is packed and the client
277has requested include-tags.
278
279Clients MUST be prepared for the case where a server has ignored
280include-tag and has not actually sent tags in the pack. In such
281cases the client SHOULD issue a subsequent fetch to acquire the tags
282that include-tag would have otherwise given the client.
283
284The server SHOULD send include-tag, if it supports it, regardless
285of whether or not there are tags available.
286
287report-status
288-------------
289
290The receive-pack process can receive a 'report-status' capability,
291which tells it that the client wants a report of what happened after
292a packfile upload and reference update. If the pushing client requests
293this capability, after unpacking and updating references the server
294will respond with whether the packfile unpacked successfully and if
295each reference was updated successfully. If any of those were not
296successful, it will send back an error message. See linkgit:gitprotocol-pack[5]
297for example messages.
298
299report-status-v2
300----------------
301
302Capability 'report-status-v2' extends capability 'report-status' by
303adding new "option" directives in order to support reference rewritten by
304the "proc-receive" hook. The "proc-receive" hook may handle a command
305for a pseudo-reference which may create or update a reference with
306different name, new-oid, and old-oid. While the capability
307'report-status' cannot report for such case. See linkgit:gitprotocol-pack[5]
308for details.
309
310delete-refs
311-----------
312
313If the server sends back the 'delete-refs' capability, it means that
314it is capable of accepting a zero-id value as the target
315value of a reference update. It is not sent back by the client, it
316simply informs the client that it can be sent zero-id values
317to delete references.
318
319quiet
320-----
321
322If the receive-pack server advertises the 'quiet' capability, it is
323capable of silencing human-readable progress output which otherwise may
324be shown when processing the received pack. A send-pack client should
325respond with the 'quiet' capability to suppress server-side progress
326reporting if the local progress reporting is also being suppressed
327(e.g., via `push -q`, or if stderr does not go to a tty).
328
329atomic
330------
331
332If the server sends the 'atomic' capability it is capable of accepting
333atomic pushes. If the pushing client requests this capability, the server
334will update the refs in one atomic transaction. Either all refs are
335updated or none.
336
337push-options
338------------
339
340If the server sends the 'push-options' capability it is able to accept
341push options after the update commands have been sent, but before the
342packfile is streamed. If the pushing client requests this capability,
343the server will pass the options to the pre- and post- receive hooks
344that process this push request.
345
346allow-tip-sha1-in-want
347----------------------
348
349If the upload-pack server advertises this capability, fetch-pack may
350send "want" lines with object names that exist at the server but are not
351advertised by upload-pack. For historical reasons, the name of this
352capability contains "sha1". Object names are always given using the
353object format negotiated through the 'object-format' capability.
354
355allow-reachable-sha1-in-want
356----------------------------
357
358If the upload-pack server advertises this capability, fetch-pack may
359send "want" lines with object names that exist at the server but are not
360advertised by upload-pack. For historical reasons, the name of this
361capability contains "sha1". Object names are always given using the
362object format negotiated through the 'object-format' capability.
363
364push-cert=<nonce>
365-----------------
366
367The receive-pack server that advertises this capability is willing
368to accept a signed push certificate, and asks the <nonce> to be
369included in the push certificate. A send-pack client MUST NOT
370send a push-cert packet unless the receive-pack server advertises
371this capability.
372
373filter
374------
375
376If the upload-pack server advertises the 'filter' capability,
377fetch-pack may send "filter" commands to request a partial clone
378or partial fetch and request that the server omit various objects
379from the packfile.
380
381session-id=<session-id>
382-----------------------
383
384The server may advertise a session ID that can be used to identify this process
385across multiple requests. The client may advertise its own session ID back to
386the server as well.
387
388Session IDs should be unique to a given process. They must fit within a
389packet-line, and must not contain non-printable or whitespace characters. The
390current implementation uses trace2 session IDs (see
391link:technical/api-trace2.html[api-trace2] for details), but this may change
392and users of the session ID should not rely on this fact.
393
394GIT
395---
396Part of the linkgit:git[1] suite