Documentation/technical/protocol-capabilities.txt

   1 Git Protocol Capabilities
   2 =========================
   3
   4 Servers SHOULD support all capabilities defined in this document.
   5
   6 On the very first line of the initial server response of either
   7 receive-pack and upload-pack the first reference is followed by
   8 a NUL byte and then a list of space delimited server capabilities.
   9 These allow the server to declare what it can and cannot support
  10 to the client.
  11
  12 Client will then send a space separated list of capabilities it wants
  13 to be in effect. The client MUST NOT ask for capabilities the server
  14 did not say it supports.
  15
  16 Server MUST diagnose and abort if capabilities it does not understand
  17 was sent.  Server MUST NOT ignore capabilities that client requested
  18 and server advertised.  As a consequence of these rules, server MUST
  19 NOT advertise capabilities it does not understand.
  20
  21 The 'report-status', 'delete-refs', and 'quiet' capabilities are sent and
  22 recognized by the receive-pack (push to server) process.
  23
  24 The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
  25 by both upload-pack and receive-pack protocols.  The 'agent' capability
  26 may optionally be sent in both protocols.
  27
  28 All other capabilities are only recognized by the upload-pack (fetch
  29 from server) process.
  30
  31 multi_ack
  32 ---------
  33
  34 The 'multi_ack' capability allows the server to return "ACK obj-id
  35 continue" as soon as it finds a commit that it can use as a common
  36 base, between the client's wants and the client's have set.
  37
  38 By sending this early, the server can potentially head off the client
  39 from walking any further down that particular branch of the client's
  40 repository history.  The client may still need to walk down other
  41 branches, sending have lines for those, until the server has a
  42 complete cut across the DAG, or the client has said "done".
  43
  44 Without multi_ack, a client sends have lines in --date-order until
  45 the server has found a common base.  That means the client will send
  46 have lines that are already known by the server to be common, because
  47 they overlap in time with another branch that the server hasn't found
  48 a common base on yet.
  49
  50 For example suppose the client has commits in caps that the server
  51 doesn't and the server has commits in lower case that the client
  52 doesn't, as in the following diagram:
  53
  54        +---- u ---------------------- x
  55       /              +----- y
  56      /              /
  57     a -- b -- c -- d -- E -- F
  58        \
  59         +--- Q -- R -- S
  60
  61 If the client wants x,y and starts out by saying have F,S, the server
  62 doesn't know what F,S is.  Eventually the client says "have d" and
  63 the server sends "ACK d continue" to let the client know to stop
  64 walking down that line (so don't send c-b-a), but it's not done yet,
  65 it needs a base for x. The client keeps going with S-R-Q, until a
  66 gets reached, at which point the server has a clear base and it all
  67 ends.
  68
  69 Without multi_ack the client would have sent that c-b-a chain anyway,
  70 interleaved with S-R-Q.
  71
  72 multi_ack_detailed
  73 ------------------
  74 This is an extension of multi_ack that permits client to better
  75 understand the server's in-memory state. See pack-protocol.txt,
  76 section "Packfile Negotiation" for more information.
  77
  78 thin-pack
  79 ---------
  80
  81 A thin pack is one with deltas which reference base objects not
  82 contained within the pack (but are known to exist at the receiving
  83 end). This can reduce the network traffic significantly, but it
  84 requires the receiving end to know how to "thicken" these packs by
  85 adding the missing bases to the pack.
  86
  87 The upload-pack server advertises 'thin-pack' when it can generate
  88 and send a thin pack. A client requests the 'thin-pack' capability
  89 when it understands how to "thicken" it, notifying the server that
  90 it can receive such a pack. A client MUST NOT request the
  91 'thin-pack' capability if it cannot turn a thin pack into a
  92 self-contained pack.
  93
  94 Receive-pack, on the other hand, is assumed by default to be able to
  95 handle thin packs, but can ask the client not to use the feature by
  96 advertising the 'no-thin' capability. A client MUST NOT send a thin
  97 pack if the server advertises the 'no-thin' capability.
  98
  99 The reasons for this asymmetry are historical. The receive-pack
 100 program did not exist until after the invention of thin packs, so
 101 historically the reference implementation of receive-pack always
 102 understood thin packs. Adding 'no-thin' later allowed receive-pack
 103 to disable the feature in a backwards-compatible manner.
 104
 105
 106 side-band, side-band-64k
 107 ------------------------
 108
 109 This capability means that server can send, and client understand multiplexed
 110 progress reports and error info interleaved with the packfile itself.
 111
 112 These two options are mutually exclusive. A modern client always
 113 favors 'side-band-64k'.
 114
 115 Either mode indicates that the packfile data will be streamed broken
 116 up into packets of up to either 1000 bytes in the case of 'side_band',
 117 or 65520 bytes in the case of 'side_band_64k'. Each packet is made up
 118 of a leading 4-byte pkt-line length of how much data is in the packet,
 119 followed by a 1-byte stream code, followed by the actual data.
 120
 121 The stream code can be one of:
 122
 123  1 - pack data
 124  2 - progress messages
 125  3 - fatal error message just before stream aborts
 126
 127 The "side-band-64k" capability came about as a way for newer clients
 128 that can handle much larger packets to request packets that are
 129 actually crammed nearly full, while maintaining backward compatibility
 130 for the older clients.
 131
 132 Further, with side-band and its up to 1000-byte messages, it's actually
 133 999 bytes of payload and 1 byte for the stream code. With side-band-64k,
 134 same deal, you have up to 65519 bytes of data and 1 byte for the stream
 135 code.
 136
 137 The client MUST send only maximum of one of "side-band" and "side-
 138 band-64k".  Server MUST diagnose it as an error if client requests
 139 both.
 140
 141 ofs-delta
 142 ---------
 143
 144 Server can send, and client understand PACKv2 with delta referring to
 145 its base by position in pack rather than by an obj-id.  That is, they can
 146 send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
 147
 148 agent
 149 -----
 150
 151 The server may optionally send a capability of the form `agent=X` to
 152 notify the client that the server is running version `X`. The client may
 153 optionally return its own agent string by responding with an `agent=Y`
 154 capability (but it MUST NOT do so if the server did not mention the
 155 agent capability). The `X` and `Y` strings may contain any printable
 156 ASCII characters except space (i.e., the byte range 32 < x < 127), and
 157 are typically of the form "package/version" (e.g., "git/1.8.3.1"). The
 158 agent strings are purely informative for statistics and debugging
 159 purposes, and MUST NOT be used to programatically assume the presence
 160 or absence of particular features.
 161
 162 shallow
 163 -------
 164
 165 This capability adds "deepen", "shallow" and "unshallow" commands to
 166 the  fetch-pack/upload-pack protocol so clients can request shallow
 167 clones.
 168
 169 no-progress
 170 -----------
 171
 172 The client was started with "git clone -q" or something, and doesn't
 173 want that side band 2.  Basically the client just says "I do not
 174 wish to receive stream 2 on sideband, so do not send it to me, and if
 175 you did, I will drop it on the floor anyway".  However, the sideband
 176 channel 3 is still used for error responses.
 177
 178 include-tag
 179 -----------
 180
 181 The 'include-tag' capability is about sending annotated tags if we are
 182 sending objects they point to.  If we pack an object to the client, and
 183 a tag object points exactly at that object, we pack the tag object too.
 184 In general this allows a client to get all new annotated tags when it
 185 fetches a branch, in a single network connection.
 186
 187 Clients MAY always send include-tag, hardcoding it into a request when
 188 the server advertises this capability. The decision for a client to
 189 request include-tag only has to do with the client's desires for tag
 190 data, whether or not a server had advertised objects in the
 191 refs/tags/* namespace.
 192
 193 Servers MUST pack the tags if their referrant is packed and the client
 194 has requested include-tags.
 195
 196 Clients MUST be prepared for the case where a server has ignored
 197 include-tag and has not actually sent tags in the pack.  In such
 198 cases the client SHOULD issue a subsequent fetch to acquire the tags
 199 that include-tag would have otherwise given the client.
 200
 201 The server SHOULD send include-tag, if it supports it, regardless
 202 of whether or not there are tags available.
 203
 204 report-status
 205 -------------
 206
 207 The receive-pack process can receive a 'report-status' capability,
 208 which tells it that the client wants a report of what happened after
 209 a packfile upload and reference update.  If the pushing client requests
 210 this capability, after unpacking and updating references the server
 211 will respond with whether the packfile unpacked successfully and if
 212 each reference was updated successfully.  If any of those were not
 213 successful, it will send back an error message.  See pack-protocol.txt
 214 for example messages.
 215
 216 delete-refs
 217 -----------
 218
 219 If the server sends back the 'delete-refs' capability, it means that
 220 it is capable of accepting a zero-id value as the target
 221 value of a reference update.  It is not sent back by the client, it
 222 simply informs the client that it can be sent zero-id values
 223 to delete references.
 224
 225 quiet
 226 -----
 227
 228 If the receive-pack server advertises the 'quiet' capability, it is
 229 capable of silencing human-readable progress output which otherwise may
 230 be shown when processing the received pack. A send-pack client should
 231 respond with the 'quiet' capability to suppress server-side progress
 232 reporting if the local progress reporting is also being suppressed
 233 (e.g., via `push -q`, or if stderr does not go to a tty).
 234
 235 allow-tip-sha1-in-want
 236 ----------------------
 237
 238 If the upload-pack server advertises this capability, fetch-pack may
 239 send "want" lines with SHA-1s that exist at the server but are not
 240 advertised by upload-pack.