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 thin-pack
  73 ---------
  74
  75 This capability means that the server can send a 'thin' pack, a pack
  76 which does not contain base objects; if those base objects are available
  77 on client side. Client requests 'thin-pack' capability when it
  78 understands how to "thicken" it by adding required delta bases making
  79 it self-contained.
  80
  81 Client MUST NOT request 'thin-pack' capability if it cannot turn a thin
  82 pack into a self-contained pack.
  83
  84
  85 side-band, side-band-64k
  86 ------------------------
  87
  88 This capability means that server can send, and client understand multiplexed
  89 progress reports and error info interleaved with the packfile itself.
  90
  91 These two options are mutually exclusive. A modern client always
  92 favors 'side-band-64k'.
  93
  94 Either mode indicates that the packfile data will be streamed broken
  95 up into packets of up to either 1000 bytes in the case of 'side_band',
  96 or 65520 bytes in the case of 'side_band_64k'. Each packet is made up
  97 of a leading 4-byte pkt-line length of how much data is in the packet,
  98 followed by a 1-byte stream code, followed by the actual data.
  99
 100 The stream code can be one of:
 101
 102  1 - pack data
 103  2 - progress messages
 104  3 - fatal error message just before stream aborts
 105
 106 The "side-band-64k" capability came about as a way for newer clients
 107 that can handle much larger packets to request packets that are
 108 actually crammed nearly full, while maintaining backward compatibility
 109 for the older clients.
 110
 111 Further, with side-band and its up to 1000-byte messages, it's actually
 112 999 bytes of payload and 1 byte for the stream code. With side-band-64k,
 113 same deal, you have up to 65519 bytes of data and 1 byte for the stream
 114 code.
 115
 116 The client MUST send only maximum of one of "side-band" and "side-
 117 band-64k".  Server MUST diagnose it as an error if client requests
 118 both.
 119
 120 ofs-delta
 121 ---------
 122
 123 Server can send, and client understand PACKv2 with delta referring to
 124 its base by position in pack rather than by an obj-id.  That is, they can
 125 send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
 126
 127 agent
 128 -----
 129
 130 The server may optionally send a capability of the form `agent=X` to
 131 notify the client that the server is running version `X`. The client may
 132 optionally return its own agent string by responding with an `agent=Y`
 133 capability (but it MUST NOT do so if the server did not mention the
 134 agent capability). The `X` and `Y` strings may contain any printable
 135 ASCII characters except space (i.e., the byte range 32 < x < 127), and
 136 are typically of the form "package/version" (e.g., "git/1.8.3.1"). The
 137 agent strings are purely informative for statistics and debugging
 138 purposes, and MUST NOT be used to programatically assume the presence
 139 or absence of particular features.
 140
 141 shallow
 142 -------
 143
 144 This capability adds "deepen", "shallow" and "unshallow" commands to
 145 the  fetch-pack/upload-pack protocol so clients can request shallow
 146 clones.
 147
 148 no-progress
 149 -----------
 150
 151 The client was started with "git clone -q" or something, and doesn't
 152 want that side band 2.  Basically the client just says "I do not
 153 wish to receive stream 2 on sideband, so do not send it to me, and if
 154 you did, I will drop it on the floor anyway".  However, the sideband
 155 channel 3 is still used for error responses.
 156
 157 include-tag
 158 -----------
 159
 160 The 'include-tag' capability is about sending annotated tags if we are
 161 sending objects they point to.  If we pack an object to the client, and
 162 a tag object points exactly at that object, we pack the tag object too.
 163 In general this allows a client to get all new annotated tags when it
 164 fetches a branch, in a single network connection.
 165
 166 Clients MAY always send include-tag, hardcoding it into a request when
 167 the server advertises this capability. The decision for a client to
 168 request include-tag only has to do with the client's desires for tag
 169 data, whether or not a server had advertised objects in the
 170 refs/tags/* namespace.
 171
 172 Servers MUST pack the tags if their referrant is packed and the client
 173 has requested include-tags.
 174
 175 Clients MUST be prepared for the case where a server has ignored
 176 include-tag and has not actually sent tags in the pack.  In such
 177 cases the client SHOULD issue a subsequent fetch to acquire the tags
 178 that include-tag would have otherwise given the client.
 179
 180 The server SHOULD send include-tag, if it supports it, regardless
 181 of whether or not there are tags available.
 182
 183 report-status
 184 -------------
 185
 186 The receive-pack process can receive a 'report-status' capability,
 187 which tells it that the client wants a report of what happened after
 188 a packfile upload and reference update.  If the pushing client requests
 189 this capability, after unpacking and updating references the server
 190 will respond with whether the packfile unpacked successfully and if
 191 each reference was updated successfully.  If any of those were not
 192 successful, it will send back an error message.  See pack-protocol.txt
 193 for example messages.
 194
 195 delete-refs
 196 -----------
 197
 198 If the server sends back the 'delete-refs' capability, it means that
 199 it is capable of accepting a zero-id value as the target
 200 value of a reference update.  It is not sent back by the client, it
 201 simply informs the client that it can be sent zero-id values
 202 to delete references.
 203
 204 quiet
 205 -----
 206
 207 If the receive-pack server advertises the 'quiet' capability, it is
 208 capable of silencing human-readable progress output which otherwise may
 209 be shown when processing the received pack. A send-pack client should
 210 respond with the 'quiet' capability to suppress server-side progress
 211 reporting if the local progress reporting is also being suppressed
 212 (e.g., via `push -q`, or if stderr does not go to a tty).
 213
 214 allow-tip-sha1-in-want
 215 ----------------------
 216
 217 If the upload-pack server advertises this capability, fetch-pack may
 218 send "want" lines with SHA-1s that exist at the server but are not
 219 advertised by upload-pack.