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