Merge branch 'ds/config-literal-value'
[git] / Documentation / technical / pack-protocol.txt
1 Packfile transfer protocols
2 ===========================
3
4 Git supports transferring data in packfiles over the ssh://, git://, http:// and
5 file:// transports.  There exist two sets of protocols, one for pushing
6 data from a client to a server and another for fetching data from a
7 server to a client.  The three transports (ssh, git, file) use the same
8 protocol to transfer data. http is documented in http-protocol.txt.
9
10 The processes invoked in the canonical Git implementation are 'upload-pack'
11 on the server side and 'fetch-pack' on the client side for fetching data;
12 then 'receive-pack' on the server and 'send-pack' on the client for pushing
13 data.  The protocol functions to have a server tell a client what is
14 currently on the server, then for the two to negotiate the smallest amount
15 of data to send in order to fully update one or the other.
16
17 pkt-line Format
18 ---------------
19
20 The descriptions below build on the pkt-line format described in
21 protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless
22 otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
23 include a LF, but the receiver MUST NOT complain if it is not present.
24
25 An error packet is a special pkt-line that contains an error string.
26
27 ----
28   error-line     =  PKT-LINE("ERR" SP explanation-text)
29 ----
30
31 Throughout the protocol, where `PKT-LINE(...)` is expected, an error packet MAY
32 be sent. Once this packet is sent by a client or a server, the data transfer
33 process defined in this protocol is terminated.
34
35 Transports
36 ----------
37 There are three transports over which the packfile protocol is
38 initiated.  The Git transport is a simple, unauthenticated server that
39 takes the command (almost always 'upload-pack', though Git
40 servers can be configured to be globally writable, in which 'receive-
41 pack' initiation is also allowed) with which the client wishes to
42 communicate and executes it and connects it to the requesting
43 process.
44
45 In the SSH transport, the client just runs the 'upload-pack'
46 or 'receive-pack' process on the server over the SSH protocol and then
47 communicates with that invoked process over the SSH connection.
48
49 The file:// transport runs the 'upload-pack' or 'receive-pack'
50 process locally and communicates with it over a pipe.
51
52 Extra Parameters
53 ----------------
54
55 The protocol provides a mechanism in which clients can send additional
56 information in its first message to the server. These are called "Extra
57 Parameters", and are supported by the Git, SSH, and HTTP protocols.
58
59 Each Extra Parameter takes the form of `<key>=<value>` or `<key>`.
60
61 Servers that receive any such Extra Parameters MUST ignore all
62 unrecognized keys. Currently, the only Extra Parameter recognized is
63 "version" with a value of '1' or '2'.  See protocol-v2.txt for more
64 information on protocol version 2.
65
66 Git Transport
67 -------------
68
69 The Git transport starts off by sending the command and repository
70 on the wire using the pkt-line format, followed by a NUL byte and a
71 hostname parameter, terminated by a NUL byte.
72
73    0033git-upload-pack /project.git\0host=myserver.com\0
74
75 The transport may send Extra Parameters by adding an additional NUL
76 byte, and then adding one or more NUL-terminated strings:
77
78    003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0
79
80 --
81    git-proto-request = request-command SP pathname NUL
82                        [ host-parameter NUL ] [ NUL extra-parameters ]
83    request-command   = "git-upload-pack" / "git-receive-pack" /
84                        "git-upload-archive"   ; case sensitive
85    pathname          = *( %x01-ff ) ; exclude NUL
86    host-parameter    = "host=" hostname [ ":" port ]
87    extra-parameters  = 1*extra-parameter
88    extra-parameter   = 1*( %x01-ff ) NUL
89 --
90
91 host-parameter is used for the
92 git-daemon name based virtual hosting.  See --interpolated-path
93 option to git daemon, with the %H/%CH format characters.
94
95 Basically what the Git client is doing to connect to an 'upload-pack'
96 process on the server side over the Git protocol is this:
97
98    $ echo -e -n \
99      "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" |
100      nc -v example.com 9418
101
102
103 SSH Transport
104 -------------
105
106 Initiating the upload-pack or receive-pack processes over SSH is
107 executing the binary on the server via SSH remote execution.
108 It is basically equivalent to running this:
109
110    $ ssh git.example.com "git-upload-pack '/project.git'"
111
112 For a server to support Git pushing and pulling for a given user over
113 SSH, that user needs to be able to execute one or both of those
114 commands via the SSH shell that they are provided on login.  On some
115 systems, that shell access is limited to only being able to run those
116 two commands, or even just one of them.
117
118 In an ssh:// format URI, it's absolute in the URI, so the '/' after
119 the host name (or port number) is sent as an argument, which is then
120 read by the remote git-upload-pack exactly as is, so it's effectively
121 an absolute path in the remote filesystem.
122
123        git clone ssh://user@example.com/project.git
124                     |
125                     v
126     ssh user@example.com "git-upload-pack '/project.git'"
127
128 In a "user@host:path" format URI, its relative to the user's home
129 directory, because the Git client will run:
130
131      git clone user@example.com:project.git
132                     |
133                     v
134   ssh user@example.com "git-upload-pack 'project.git'"
135
136 The exception is if a '~' is used, in which case
137 we execute it without the leading '/'.
138
139       ssh://user@example.com/~alice/project.git,
140                      |
141                      v
142    ssh user@example.com "git-upload-pack '~alice/project.git'"
143
144 Depending on the value of the `protocol.version` configuration variable,
145 Git may attempt to send Extra Parameters as a colon-separated string in
146 the GIT_PROTOCOL environment variable. This is done only if
147 the `ssh.variant` configuration variable indicates that the ssh command
148 supports passing environment variables as an argument.
149
150 A few things to remember here:
151
152 - The "command name" is spelled with dash (e.g. git-upload-pack), but
153   this can be overridden by the client;
154
155 - The repository path is always quoted with single quotes.
156
157 Fetching Data From a Server
158 ---------------------------
159
160 When one Git repository wants to get data that a second repository
161 has, the first can 'fetch' from the second.  This operation determines
162 what data the server has that the client does not then streams that
163 data down to the client in packfile format.
164
165
166 Reference Discovery
167 -------------------
168
169 When the client initially connects the server will immediately respond
170 with a version number (if "version=1" is sent as an Extra Parameter),
171 and a listing of each reference it has (all branches and tags) along
172 with the object name that each reference currently points to.
173
174    $ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" |
175       nc -v example.com 9418
176    000eversion 1
177    00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
178                 side-band side-band-64k ofs-delta shallow no-progress include-tag
179    00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
180    003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
181    003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
182    003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0
183    003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
184    0000
185
186 The returned response is a pkt-line stream describing each ref and
187 its current value.  The stream MUST be sorted by name according to
188 the C locale ordering.
189
190 If HEAD is a valid ref, HEAD MUST appear as the first advertised
191 ref.  If HEAD is not a valid ref, HEAD MUST NOT appear in the
192 advertisement list at all, but other refs may still appear.
193
194 The stream MUST include capability declarations behind a NUL on the
195 first ref. The peeled value of a ref (that is "ref^{}") MUST be
196 immediately after the ref itself, if presented. A conforming server
197 MUST peel the ref if it's an annotated tag.
198
199 ----
200   advertised-refs  =  *1("version 1")
201                       (no-refs / list-of-refs)
202                       *shallow
203                       flush-pkt
204
205   no-refs          =  PKT-LINE(zero-id SP "capabilities^{}"
206                       NUL capability-list)
207
208   list-of-refs     =  first-ref *other-ref
209   first-ref        =  PKT-LINE(obj-id SP refname
210                       NUL capability-list)
211
212   other-ref        =  PKT-LINE(other-tip / other-peeled)
213   other-tip        =  obj-id SP refname
214   other-peeled     =  obj-id SP refname "^{}"
215
216   shallow          =  PKT-LINE("shallow" SP obj-id)
217
218   capability-list  =  capability *(SP capability)
219   capability       =  1*(LC_ALPHA / DIGIT / "-" / "_")
220   LC_ALPHA         =  %x61-7A
221 ----
222
223 Server and client MUST use lowercase for obj-id, both MUST treat obj-id
224 as case-insensitive.
225
226 See protocol-capabilities.txt for a list of allowed server capabilities
227 and descriptions.
228
229 Packfile Negotiation
230 --------------------
231 After reference and capabilities discovery, the client can decide to
232 terminate the connection by sending a flush-pkt, telling the server it can
233 now gracefully terminate, and disconnect, when it does not need any pack
234 data. This can happen with the ls-remote command, and also can happen when
235 the client already is up to date.
236
237 Otherwise, it enters the negotiation phase, where the client and
238 server determine what the minimal packfile necessary for transport is,
239 by telling the server what objects it wants, its shallow objects
240 (if any), and the maximum commit depth it wants (if any).  The client
241 will also send a list of the capabilities it wants to be in effect,
242 out of what the server said it could do with the first 'want' line.
243
244 ----
245   upload-request    =  want-list
246                        *shallow-line
247                        *1depth-request
248                        [filter-request]
249                        flush-pkt
250
251   want-list         =  first-want
252                        *additional-want
253
254   shallow-line      =  PKT-LINE("shallow" SP obj-id)
255
256   depth-request     =  PKT-LINE("deepen" SP depth) /
257                        PKT-LINE("deepen-since" SP timestamp) /
258                        PKT-LINE("deepen-not" SP ref)
259
260   first-want        =  PKT-LINE("want" SP obj-id SP capability-list)
261   additional-want   =  PKT-LINE("want" SP obj-id)
262
263   depth             =  1*DIGIT
264
265   filter-request    =  PKT-LINE("filter" SP filter-spec)
266 ----
267
268 Clients MUST send all the obj-ids it wants from the reference
269 discovery phase as 'want' lines. Clients MUST send at least one
270 'want' command in the request body. Clients MUST NOT mention an
271 obj-id in a 'want' command which did not appear in the response
272 obtained through ref discovery.
273
274 The client MUST write all obj-ids which it only has shallow copies
275 of (meaning that it does not have the parents of a commit) as
276 'shallow' lines so that the server is aware of the limitations of
277 the client's history.
278
279 The client now sends the maximum commit history depth it wants for
280 this transaction, which is the number of commits it wants from the
281 tip of the history, if any, as a 'deepen' line.  A depth of 0 is the
282 same as not making a depth request. The client does not want to receive
283 any commits beyond this depth, nor does it want objects needed only to
284 complete those commits. Commits whose parents are not received as a
285 result are defined as shallow and marked as such in the server. This
286 information is sent back to the client in the next step.
287
288 The client can optionally request that pack-objects omit various
289 objects from the packfile using one of several filtering techniques.
290 These are intended for use with partial clone and partial fetch
291 operations. An object that does not meet a filter-spec value is
292 omitted unless explicitly requested in a 'want' line. See `rev-list`
293 for possible filter-spec values.
294
295 Once all the 'want's and 'shallow's (and optional 'deepen') are
296 transferred, clients MUST send a flush-pkt, to tell the server side
297 that it is done sending the list.
298
299 Otherwise, if the client sent a positive depth request, the server
300 will determine which commits will and will not be shallow and
301 send this information to the client. If the client did not request
302 a positive depth, this step is skipped.
303
304 ----
305   shallow-update   =  *shallow-line
306                       *unshallow-line
307                       flush-pkt
308
309   shallow-line     =  PKT-LINE("shallow" SP obj-id)
310
311   unshallow-line   =  PKT-LINE("unshallow" SP obj-id)
312 ----
313
314 If the client has requested a positive depth, the server will compute
315 the set of commits which are no deeper than the desired depth. The set
316 of commits start at the client's wants.
317
318 The server writes 'shallow' lines for each
319 commit whose parents will not be sent as a result. The server writes
320 an 'unshallow' line for each commit which the client has indicated is
321 shallow, but is no longer shallow at the currently requested depth
322 (that is, its parents will now be sent). The server MUST NOT mark
323 as unshallow anything which the client has not indicated was shallow.
324
325 Now the client will send a list of the obj-ids it has using 'have'
326 lines, so the server can make a packfile that only contains the objects
327 that the client needs. In multi_ack mode, the canonical implementation
328 will send up to 32 of these at a time, then will send a flush-pkt. The
329 canonical implementation will skip ahead and send the next 32 immediately,
330 so that there is always a block of 32 "in-flight on the wire" at a time.
331
332 ----
333   upload-haves      =  have-list
334                        compute-end
335
336   have-list         =  *have-line
337   have-line         =  PKT-LINE("have" SP obj-id)
338   compute-end       =  flush-pkt / PKT-LINE("done")
339 ----
340
341 If the server reads 'have' lines, it then will respond by ACKing any
342 of the obj-ids the client said it had that the server also has. The
343 server will ACK obj-ids differently depending on which ack mode is
344 chosen by the client.
345
346 In multi_ack mode:
347
348   * the server will respond with 'ACK obj-id continue' for any common
349     commits.
350
351   * once the server has found an acceptable common base commit and is
352     ready to make a packfile, it will blindly ACK all 'have' obj-ids
353     back to the client.
354
355   * the server will then send a 'NAK' and then wait for another response
356     from the client - either a 'done' or another list of 'have' lines.
357
358 In multi_ack_detailed mode:
359
360   * the server will differentiate the ACKs where it is signaling
361     that it is ready to send data with 'ACK obj-id ready' lines, and
362     signals the identified common commits with 'ACK obj-id common' lines.
363
364 Without either multi_ack or multi_ack_detailed:
365
366  * upload-pack sends "ACK obj-id" on the first common object it finds.
367    After that it says nothing until the client gives it a "done".
368
369  * upload-pack sends "NAK" on a flush-pkt if no common object
370    has been found yet.  If one has been found, and thus an ACK
371    was already sent, it's silent on the flush-pkt.
372
373 After the client has gotten enough ACK responses that it can determine
374 that the server has enough information to send an efficient packfile
375 (in the canonical implementation, this is determined when it has received
376 enough ACKs that it can color everything left in the --date-order queue
377 as common with the server, or the --date-order queue is empty), or the
378 client determines that it wants to give up (in the canonical implementation,
379 this is determined when the client sends 256 'have' lines without getting
380 any of them ACKed by the server - meaning there is nothing in common and
381 the server should just send all of its objects), then the client will send
382 a 'done' command.  The 'done' command signals to the server that the client
383 is ready to receive its packfile data.
384
385 However, the 256 limit *only* turns on in the canonical client
386 implementation if we have received at least one "ACK %s continue"
387 during a prior round.  This helps to ensure that at least one common
388 ancestor is found before we give up entirely.
389
390 Once the 'done' line is read from the client, the server will either
391 send a final 'ACK obj-id' or it will send a 'NAK'. 'obj-id' is the object
392 name of the last commit determined to be common. The server only sends
393 ACK after 'done' if there is at least one common base and multi_ack or
394 multi_ack_detailed is enabled. The server always sends NAK after 'done'
395 if there is no common base found.
396
397 Instead of 'ACK' or 'NAK', the server may send an error message (for
398 example, if it does not recognize an object in a 'want' line received
399 from the client).
400
401 Then the server will start sending its packfile data.
402
403 ----
404   server-response = *ack_multi ack / nak
405   ack_multi       = PKT-LINE("ACK" SP obj-id ack_status)
406   ack_status      = "continue" / "common" / "ready"
407   ack             = PKT-LINE("ACK" SP obj-id)
408   nak             = PKT-LINE("NAK")
409 ----
410
411 A simple clone may look like this (with no 'have' lines):
412
413 ----
414    C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
415      side-band-64k ofs-delta\n
416    C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
417    C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
418    C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
419    C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n
420    C: 0000
421    C: 0009done\n
422
423    S: 0008NAK\n
424    S: [PACKFILE]
425 ----
426
427 An incremental update (fetch) response might look like this:
428
429 ----
430    C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
431      side-band-64k ofs-delta\n
432    C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
433    C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
434    C: 0000
435    C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
436    C: [30 more have lines]
437    C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n
438    C: 0000
439
440    S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n
441    S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n
442    S: 0008NAK\n
443
444    C: 0009done\n
445
446    S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n
447    S: [PACKFILE]
448 ----
449
450
451 Packfile Data
452 -------------
453
454 Now that the client and server have finished negotiation about what
455 the minimal amount of data that needs to be sent to the client is, the server
456 will construct and send the required data in packfile format.
457
458 See pack-format.txt for what the packfile itself actually looks like.
459
460 If 'side-band' or 'side-band-64k' capabilities have been specified by
461 the client, the server will send the packfile data multiplexed.
462
463 Each packet starting with the packet-line length of the amount of data
464 that follows, followed by a single byte specifying the sideband the
465 following data is coming in on.
466
467 In 'side-band' mode, it will send up to 999 data bytes plus 1 control
468 code, for a total of up to 1000 bytes in a pkt-line.  In 'side-band-64k'
469 mode it will send up to 65519 data bytes plus 1 control code, for a
470 total of up to 65520 bytes in a pkt-line.
471
472 The sideband byte will be a '1', '2' or a '3'. Sideband '1' will contain
473 packfile data, sideband '2' will be used for progress information that the
474 client will generally print to stderr and sideband '3' is used for error
475 information.
476
477 If no 'side-band' capability was specified, the server will stream the
478 entire packfile without multiplexing.
479
480
481 Pushing Data To a Server
482 ------------------------
483
484 Pushing data to a server will invoke the 'receive-pack' process on the
485 server, which will allow the client to tell it which references it should
486 update and then send all the data the server will need for those new
487 references to be complete.  Once all the data is received and validated,
488 the server will then update its references to what the client specified.
489
490 Authentication
491 --------------
492
493 The protocol itself contains no authentication mechanisms.  That is to be
494 handled by the transport, such as SSH, before the 'receive-pack' process is
495 invoked.  If 'receive-pack' is configured over the Git transport, those
496 repositories will be writable by anyone who can access that port (9418) as
497 that transport is unauthenticated.
498
499 Reference Discovery
500 -------------------
501
502 The reference discovery phase is done nearly the same way as it is in the
503 fetching protocol. Each reference obj-id and name on the server is sent
504 in packet-line format to the client, followed by a flush-pkt.  The only
505 real difference is that the capability listing is different - the only
506 possible values are 'report-status', 'report-status-v2', 'delete-refs',
507 'ofs-delta', 'atomic' and 'push-options'.
508
509 Reference Update Request and Packfile Transfer
510 ----------------------------------------------
511
512 Once the client knows what references the server is at, it can send a
513 list of reference update requests.  For each reference on the server
514 that it wants to update, it sends a line listing the obj-id currently on
515 the server, the obj-id the client would like to update it to and the name
516 of the reference.
517
518 This list is followed by a flush-pkt.
519
520 ----
521   update-requests   =  *shallow ( command-list | push-cert )
522
523   shallow           =  PKT-LINE("shallow" SP obj-id)
524
525   command-list      =  PKT-LINE(command NUL capability-list)
526                        *PKT-LINE(command)
527                        flush-pkt
528
529   command           =  create / delete / update
530   create            =  zero-id SP new-id  SP name
531   delete            =  old-id  SP zero-id SP name
532   update            =  old-id  SP new-id  SP name
533
534   old-id            =  obj-id
535   new-id            =  obj-id
536
537   push-cert         = PKT-LINE("push-cert" NUL capability-list LF)
538                       PKT-LINE("certificate version 0.1" LF)
539                       PKT-LINE("pusher" SP ident LF)
540                       PKT-LINE("pushee" SP url LF)
541                       PKT-LINE("nonce" SP nonce LF)
542                       *PKT-LINE("push-option" SP push-option LF)
543                       PKT-LINE(LF)
544                       *PKT-LINE(command LF)
545                       *PKT-LINE(gpg-signature-lines LF)
546                       PKT-LINE("push-cert-end" LF)
547
548   push-option       =  1*( VCHAR | SP )
549 ----
550
551 If the server has advertised the 'push-options' capability and the client has
552 specified 'push-options' as part of the capability list above, the client then
553 sends its push options followed by a flush-pkt.
554
555 ----
556   push-options      =  *PKT-LINE(push-option) flush-pkt
557 ----
558
559 For backwards compatibility with older Git servers, if the client sends a push
560 cert and push options, it MUST send its push options both embedded within the
561 push cert and after the push cert. (Note that the push options within the cert
562 are prefixed, but the push options after the cert are not.) Both these lists
563 MUST be the same, modulo the prefix.
564
565 After that the packfile that
566 should contain all the objects that the server will need to complete the new
567 references will be sent.
568
569 ----
570   packfile          =  "PACK" 28*(OCTET)
571 ----
572
573 If the receiving end does not support delete-refs, the sending end MUST
574 NOT ask for delete command.
575
576 If the receiving end does not support push-cert, the sending end
577 MUST NOT send a push-cert command.  When a push-cert command is
578 sent, command-list MUST NOT be sent; the commands recorded in the
579 push certificate is used instead.
580
581 The packfile MUST NOT be sent if the only command used is 'delete'.
582
583 A packfile MUST be sent if either create or update command is used,
584 even if the server already has all the necessary objects.  In this
585 case the client MUST send an empty packfile.   The only time this
586 is likely to happen is if the client is creating
587 a new branch or a tag that points to an existing obj-id.
588
589 The server will receive the packfile, unpack it, then validate each
590 reference that is being updated that it hasn't changed while the request
591 was being processed (the obj-id is still the same as the old-id), and
592 it will run any update hooks to make sure that the update is acceptable.
593 If all of that is fine, the server will then update the references.
594
595 Push Certificate
596 ----------------
597
598 A push certificate begins with a set of header lines.  After the
599 header and an empty line, the protocol commands follow, one per
600 line. Note that the trailing LF in push-cert PKT-LINEs is _not_
601 optional; it must be present.
602
603 Currently, the following header fields are defined:
604
605 `pusher` ident::
606         Identify the GPG key in "Human Readable Name <email@address>"
607         format.
608
609 `pushee` url::
610         The repository URL (anonymized, if the URL contains
611         authentication material) the user who ran `git push`
612         intended to push into.
613
614 `nonce` nonce::
615         The 'nonce' string the receiving repository asked the
616         pushing user to include in the certificate, to prevent
617         replay attacks.
618
619 The GPG signature lines are a detached signature for the contents
620 recorded in the push certificate before the signature block begins.
621 The detached signature is used to certify that the commands were
622 given by the pusher, who must be the signer.
623
624 Report Status
625 -------------
626
627 After receiving the pack data from the sender, the receiver sends a
628 report if 'report-status' or 'report-status-v2' capability is in effect.
629 It is a short listing of what happened in that update.  It will first
630 list the status of the packfile unpacking as either 'unpack ok' or
631 'unpack [error]'.  Then it will list the status for each of the references
632 that it tried to update.  Each line is either 'ok [refname]' if the
633 update was successful, or 'ng [refname] [error]' if the update was not.
634
635 ----
636   report-status     = unpack-status
637                       1*(command-status)
638                       flush-pkt
639
640   unpack-status     = PKT-LINE("unpack" SP unpack-result)
641   unpack-result     = "ok" / error-msg
642
643   command-status    = command-ok / command-fail
644   command-ok        = PKT-LINE("ok" SP refname)
645   command-fail      = PKT-LINE("ng" SP refname SP error-msg)
646
647   error-msg         = 1*(OCTET) ; where not "ok"
648 ----
649
650 The 'report-status-v2' capability extends the protocol by adding new option
651 lines in order to support reporting of reference rewritten by the
652 'proc-receive' hook.  The 'proc-receive' hook may handle a command for a
653 pseudo-reference which may create or update one or more references, and each
654 reference may have different name, different new-oid, and different old-oid.
655
656 ----
657   report-status-v2  = unpack-status
658                       1*(command-status-v2)
659                       flush-pkt
660
661   unpack-status     = PKT-LINE("unpack" SP unpack-result)
662   unpack-result     = "ok" / error-msg
663
664   command-status-v2 = command-ok-v2 / command-fail
665   command-ok-v2     = command-ok
666                       *option-line
667
668   command-ok        = PKT-LINE("ok" SP refname)
669   command-fail      = PKT-LINE("ng" SP refname SP error-msg)
670
671   error-msg         = 1*(OCTET) ; where not "ok"
672
673   option-line       = *1(option-refname)
674                       *1(option-old-oid)
675                       *1(option-new-oid)
676                       *1(option-forced-update)
677
678   option-refname    = PKT-LINE("option" SP "refname" SP refname)
679   option-old-oid    = PKT-LINE("option" SP "old-oid" SP obj-id)
680   option-new-oid    = PKT-LINE("option" SP "new-oid" SP obj-id)
681   option-force      = PKT-LINE("option" SP "forced-update")
682
683 ----
684
685 Updates can be unsuccessful for a number of reasons.  The reference can have
686 changed since the reference discovery phase was originally sent, meaning
687 someone pushed in the meantime.  The reference being pushed could be a
688 non-fast-forward reference and the update hooks or configuration could be
689 set to not allow that, etc.  Also, some references can be updated while others
690 can be rejected.
691
692 An example client/server communication might look like this:
693
694 ----
695    S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n
696    S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n
697    S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n
698    S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n
699    S: 0000
700
701    C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n
702    C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n
703    C: 0000
704    C: [PACKDATA]
705
706    S: 000eunpack ok\n
707    S: 0018ok refs/heads/debug\n
708    S: 002ang refs/heads/master non-fast-forward\n
709 ----