Documentation/technical/http-protocol.txt

   1 HTTP transfer protocols
   2 =======================
   3
   4 Git supports two HTTP based transfer protocols.  A "dumb" protocol
   5 which requires only a standard HTTP server on the server end of the
   6 connection, and a "smart" protocol which requires a Git aware CGI
   7 (or server module).  This document describes both protocols.
   8
   9 As a design feature, smart clients initially attempt a smart
  10 protocol connection, but are able to detect and downgrade to the
  11 dumb behavior when a non-Git aware server is contacted.  This feature
  12 permits all users to have the same published URL, and the peers will
  13 automatically select the most efficient transport available to them.
  14
  15
  16 URL Format
  17 ----------
  18
  19 URLs for Git repositories accessed by HTTP use the standard HTTP
  20 URL syntax documented by RFC 1738, so they are of the form:
  21
  22   http://<host>:<port>/<path>
  23
  24 Within this documentation the placeholder $GIT_URL will stand for
  25 the repository URL entered by the end-user.
  26
  27 The $GIT_URL specifies the path to the repository and is mapped to
  28 a location on the server's filesystem by the HTTP server.
  29
  30 Both the "smart" and "dumb" HTTP protocols used by Git operate
  31 by appending additional path components onto the end of the user
  32 supplied $GIT_URL string.
  33
  34 Clients MUST strip a trailing '/', if present, from the user supplied
  35 $GIT_URL string to prevent empty path components ('//') from appearing
  36 in any URL sent to a server.  Compatible clients MUST expand
  37 '$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
  38
  39 Some example $GIT_URLs are shown below.  In each grouping the first
  40 URL was entered by the user, while the remaining URLS below the
  41 discussion are what will be requested by a conforming client:
  42
  43 http://git.example.com/repos/projects/it.git::
  44         The client connects to 'git.example.com' on port 80, and requests
  45         the repository available at '/repos/projects/it.git'.  The server
  46         is free to map this path to its local filesystem by any URL-to-file
  47         mapping rules it supports.
  48 +
  49 --------
  50 http://git.example.com/repos/projects/it.git/info/refs?service=git-upload-pack
  51 http://git.example.com/repos/projects/it.git/git-upload-pack
  52 --------
  53
  54 http://git.example.com/repos/projects/it.git/::
  55         Exactly like the URL group above, except a conforming client
  56         would avoid double slashes when appending the "/info/refs"
  57         or "/git-upload-pack" suffix:
  58 +
  59 --------
  60 http://git.example.com/repos/projects/it.git/info/refs?service=git-upload-pack
  61 http://git.example.com/repos/projects/it.git/git-upload-pack
  62 --------
  63
  64 http://example.com/repos/projects/frobinator::
  65         Repository URLs do not need to contain the string 'git'
  66         to be a valid $GIT_URL as described in this document.
  67 +
  68 --------
  69 http://example.com/repos/projects/frobinator/info/refs?service=git-upload-pack
  70 http://example.com/repos/projects/frobinator/git-upload-pack
  71 --------
  72
  73 *  https://example.com/git/test.git
  74         The client connects to 'example.com' on port 443 using HTTP
  75         over SSL, and requests the repository at '/git/test.git'.
  76         This is identical to the cases above, except the client is
  77         using SSL to protect its communications with the server.
  78 +
  79 --------
  80 https://example.com/git/test.git/info/refs?service=git-receive-pack
  81 https://example.com/git/test.git/git-receive-pack
  82 --------
  83
  84 *  http://desktop:8080/work/.git
  85         The client connects to 'desktop' on port 8080 using
  86         plain-text HTTP, and requests the repository at '/work/.git'.
  87         This might be a repository with a working directory, or it
  88         could be a non-standard naming of a bare repository.
  89 +
  90 --------
  91 http://desktop:8080/work/.git/info/refs?service=git-upload-pack
  92 http://desktop:8080/work/.git/git-upload-pack
  93 --------
  94
  95 *  http://example.com/r/?p=project/forks/user.git
  96         When making requests on $GIT_URLs which already contain a
  97         query string conforming clients append the suffix to the
  98         end of the query string, but for '/info/refs' add service
  99         as another query parameter.
 100 +
 101 --------
 102 http://example.com/r/?p=project/forks/user.git/info/refs&service=git-upload-pack
 103 http://example.com/r/?p=project/forks/user.git/git-upload-pack
 104 --------
 105
 106 *  http://example/repos/master.git/child.git::
 107         The client is requesting 'child.git', which lives within a
 108         location named '/repos/master.git'.
 109 +
 110 If '/repos/master.git' happens to be a valid Git repository, this
 111 is a reference to a directory called 'child.git' stored within the
 112 top level of that GIT_DIR.  It is not a reference to the contents
 113 of a revision of '/repos/master.git'.
 114 +
 115 --------
 116 http://example/repos/master.git/child.git/info/refs?service=git-upload-pack
 117 http://example/repos/master.git/child.git/git-upload-pack
 118 --------
 119
 120
 121 Authentication
 122 --------------
 123
 124 Standard HTTP authentication is used if authentication is required
 125 to access a repository, and MAY be configured and enforced by the
 126 HTTP server software.
 127
 128 Because Git repositories can be named by standard path components
 129 server administrators MAY use directory based permissions within
 130 their HTTP server to control repository access.
 131
 132 Clients SHOULD support Basic authentication as described by RFC 2616.
 133 Servers SHOULD support Basic authentication.
 134
 135 Servers SHOULD NOT require HTTP cookies for the purposes of
 136 authentication or access control.
 137
 138 Clients and servers MAY support other common forms of HTTP based
 139 authentication, such as Digest authentication.
 140
 141
 142 SSL
 143 ---
 144
 145 Clients and servers SHOULD support SSL, particularly to protect
 146 passwords when relying on Basic HTTP authentication.
 147
 148
 149 Session State
 150 -------------
 151
 152 The Git over HTTP protocol (much like HTTP itself) is stateless
 153 from the perspective of the HTTP server side.  All state must be
 154 retained and managed by the client process.  This permits simple
 155 round-robin load-balancing on the server side, without needing to
 156 worry about state management.
 157
 158 Clients MUST NOT require state management on the server side in
 159 order to function correctly.
 160
 161 Clients MAY store and forward HTTP cookies during request processing
 162 as described by RFC 2616 (HTTP/1.1).
 163
 164
 165 ABNF Notation
 166 -------------
 167
 168 ABNF notation as described by RFC 5234 is used within this document,
 169 except the following replacement core rules are used:
 170 ----
 171         HEXDIG    =  DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
 172 ----
 173
 174 We also define the following common rules:
 175 ----
 176         NUL       =  %x00
 177         zero-id   =  40*"0"
 178         obj-id    =  40*(HEXDIGIT)
 179
 180         refname  =  "HEAD"
 181         refname /=  "refs/" <see discussion below>
 182 ----
 183
 184 A refname is a hierarichal octet string beginning with "refs/" and
 185 not violating the 'git-check-ref-format' command's validation rules.
 186 More generally, they:
 187
 188 . They can include slash `/` for hierarchical (directory)
 189   grouping, but no slash-separated component can begin with a
 190   dot `.`.
 191
 192 . They must contain at least one `/`. This enforces the presence of a
 193   category like `heads/`, `tags/` etc. but the actual names are not
 194   restricted.
 195
 196 . They cannot have two consecutive dots `..` anywhere.
 197
 198 . They cannot have ASCII control characters (i.e. bytes whose
 199   values are lower than \040, or \177 `DEL`), space, tilde `~`,
 200   caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`,
 201   or open bracket `[` anywhere.
 202
 203 . They cannot end with a slash `/` nor a dot `.`.
 204
 205 . They cannot end with the sequence `.lock`.
 206
 207 . They cannot contain a sequence `@{`.
 208
 209 . They cannot contain a `\\`.
 210
 211
 212 pkt-line Format
 213 ---------------
 214
 215 Much (but not all) of the payload is described around pkt-lines.
 216
 217 A pkt-line is a variable length binary string.  The first four bytes
 218 of the line, the pkt-len, indicates the total length of the line,
 219 in hexadecimal.  The pkt-len includes the 4 bytes used to contain
 220 the length's hexadecimal representation.
 221
 222 A pkt-line MAY contain binary data, so implementors MUST ensure
 223 pkt-line parsing/formatting routines are 8-bit clean.
 224
 225 A non-binary line SHOULD BE terminated by an LF, which if present
 226 MUST be included in the total length.
 227
 228 The maximum length of a pkt-line's data component is 65520 bytes.
 229 Implementations MUST NOT send pkt-line whose length exceeds 65524
 230 (65520 bytes of payload + 4 bytes of length data).
 231
 232 Implementations SHOULD NOT send an empty pkt-line ("0004").
 233
 234 A pkt-line with a length field of 0 ("0000"), called a flush-pkt,
 235 is a special case and MUST be handled differently than an empty
 236 pkt-line ("0004").
 237
 238 ----
 239         pkt-line     =  data-pkt / flush-pkt
 240
 241         data-pkt     =  pkt-len pkt-payload
 242     pkt-len      =  4*(HEXDIG)
 243         pkt-payload  =  (pkt-len - 4)*(OCTET)
 244
 245         flush-pkt    = "0000"
 246 ----
 247
 248 Examples (as C-style strings):
 249
 250 ----
 251   pkt-line          actual value
 252   ---------------------------------
 253   "0006a\n"         "a\n"
 254   "0005a"           "a"
 255   "000bfoobar\n"    "foobar\n"
 256   "0004"            ""
 257 ----
 258
 259
 260 General Request Processing
 261 --------------------------
 262
 263 Except where noted, all standard HTTP behavior SHOULD be assumed
 264 by both client and server.  This includes (but is not necessarily
 265 limited to):
 266
 267 If there is no repository at $GIT_URL, the server MUST respond with
 268 the '404 Not Found' HTTP status code.
 269
 270 If there is a repository at $GIT_URL, but access is not currently
 271 permitted, the server MUST respond with the '403 Forbidden' HTTP
 272 status code.
 273
 274 If there is a repository at $GIT_URL, but the dumb version of the
 275 protocol is being used, a server SHOULD respond with '404 Not Found'
 276 if the requested loose object file or pack file is not found within
 277 the repository.
 278
 279 Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
 280 Servers SHOULD support chunked encoding for both
 281 request and response bodies.
 282
 283 Clients SHOULD support both HTTP 1.0 and HTTP 1.1.
 284 Clients SHOULD support chunked encoding for both
 285 request and response bodies.
 286
 287 Servers MAY return ETag and/or Last-Modified headers.
 288
 289 Clients MAY revalidate cached entities by including If-Modified-Since
 290 and/or If-None-Match request headers.
 291
 292 Servers MAY return '304 Not Modified' if the relevant headers appear
 293 in the request and the entity has not changed.  Clients MUST treat
 294 '304 Not Modified' identical to '200 OK' by reusing the cached entity.
 295
 296 Clients MAY reuse a cached entity without revalidation if the
 297 Cache-Control and/or Expires header permits caching.  Clients and
 298 servers MUST follow RFC 2616 for cache controls.
 299
 300
 301 Discovering References
 302 ----------------------
 303
 304 All HTTP clients MUST begin either a fetch or a push exchange by
 305 discovering the references available on the remote repository.
 306
 307 Dumb Clients
 308 ~~~~~~~~~~~~
 309
 310 HTTP clients that only support the "dumb" protocol MUST discover
 311 references by making a request for the special info/refs file of
 312 the repository.
 313
 314 Dumb HTTP clients MUST NOT include the 'service=$name' query
 315 parameter when fetching the info/refs file.
 316
 317         C: GET $GIT_URL/info/refs HTTP/1.0
 318
 319         S: 200 OK
 320         S:
 321         S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31     refs/heads/maint
 322         S: d049f6c27a2244e12041955e262a404c7faba355     refs/heads/master
 323         S: 2cb58b79488a98d2721cea644875a8dd0026b115     refs/tags/v1.0
 324         S: a3c2e2402b99163d1d59756e5f207ae21cccba4c     refs/tags/v1.0^{}
 325
 326 The Content-Type of the returned info/refs entity SHOULD be
 327 "text/plain; charset=utf-8", but MAY be any content type.
 328 Clients MUST NOT attempt to validate the returned Content-Type.
 329 Dumb servers MUST NOT return a return type starting with
 330 "application/x-git-".
 331
 332 Cache-Control headers MAY be returned to control caching of the
 333 returned entity.
 334
 335 The returned content is a UNIX formatted text file describing
 336 each ref and its known value.  The file SHOULD be sorted by name
 337 according to the C locale ordering.  The file SHOULD NOT include
 338 the default ref named 'HEAD'.
 339
 340 ----
 341         info-refs          =  *info-ref-record
 342         info-ref-record    =  info-any / info-peeled
 343
 344         info-any           =  obj-id HTAB refname LF
 345         info-peeled        =  obj-id HTAB refname LF
 346                               obj-id HTAB refname "^{}" LF
 347 ----
 348
 349
 350 Smart Clients
 351 ~~~~~~~~~~~~~
 352
 353 HTTP clients that support the "smart" protocol (or both the
 354 "smart" and "dumb" protocols) MUST discover references by making
 355 a parameterized request for the info/refs file of the repository.
 356
 357 The request MUST contain the query parameter, 'service=$servicename',
 358 where $servicename MUST be the service name the client wishes
 359 to contact to complete the operation.  The request MAY contain
 360 additional query parameters only if they were present in $GIT_URL
 361 (the URL entered by the user).
 362
 363 client request::
 364 ----
 365         GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
 366 ----
 367
 368 dumb server reply::
 369 ----
 370         200 OK
 371
 372         95dcfa3633004da0049d3d0fa03f80589cbcaf31        refs/heads/maint
 373         d049f6c27a2244e12041955e262a404c7faba355        refs/heads/master
 374         2cb58b79488a98d2721cea644875a8dd0026b115        refs/tags/v1.0
 375         a3c2e2402b99163d1d59756e5f207ae21cccba4c        refs/tags/v1.0^{}
 376 ----
 377
 378 smart server reply::
 379 ----
 380         200 OK
 381         Content-Type: application/x-git-upload-pack-advertisement
 382         Cache-Control: no-cache
 383
 384         ....# service=git-upload-pack
 385         0000
 386         ....d049f6c27a2244e12041955e262a404c7faba355 HEAD\0multi_ack_2
 387         ....95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
 388         ....d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
 389         ....2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
 390         ....a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
 391         0000
 392 ----
 393
 394 Dumb Server Response
 395 ^^^^^^^^^^^^^^^^^^^^
 396 Dumb servers MUST respond with the dumb server reply format.
 397
 398 See the prior section under dumb clients for a more detailed
 399 description of the dumb server response.
 400
 401 Smart Server Response
 402 ^^^^^^^^^^^^^^^^^^^^^
 403 Smart servers MUST respond with the smart server reply format if
 404 they are willing to be treated like a smart server.
 405
 406 Smart servers which have disabled the smart version of the
 407 requested service MAY respond with either the dumb server
 408 reply format, or MAY respond with "403 Forbidden".
 409
 410 If the server does not recognize the requested service name the
 411 server MUST respond with the '403 Forbidden' HTTP status code.
 412
 413 Cache-Control headers SHOULD be used to disable caching of the
 414 returned entity.
 415
 416 The Content-Type MUST be 'application/x-$servicename-advertisement'.
 417 Clients SHOULD fall back to the dumb protocol if another content
 418 type is returned.  When falling back to the dumb protocol clients
 419 SHOULD NOT make an additional request to $GIT_URL/info/refs, but
 420 instead SHOULD use the response already in hand.  Clients MUST NOT
 421 continue if they do not support the dumb protocol.
 422
 423 Clients MUST validate the first five bytes of the response entity
 424 matches the regex "^[0-9a-f]{4}#".  If this test fails, clients
 425 MUST NOT continue.
 426
 427 Clients MUST parse the entire response as a sequence of pkt-line
 428 records.
 429
 430 Clients MUST verify the first pkt-line is "# service=$servicename".
 431 Servers MUST set $servicename to be the request parameter value.
 432 Servers SHOULD include an LF at the end of this line.
 433 Clients MUST ignore an LF at the end of the line.
 434
 435 The returned response is a pkt-line stream describing each ref and
 436 its known value.  The stream SHOULD be sorted by name according to
 437 the C locale ordering.  The stream SHOULD include the default ref
 438 named 'HEAD' as the first ref.  The stream MUST include capability
 439 declarations behind a NUL on the first ref.
 440
 441 ----
 442         advertisement    =  service-hdr advertised-refs
 443
 444         service-hdr      =  PKT-LINE("# service=$servicename" LF)
 445                             flush-pkt
 446
 447         advertised-refs  =  (no-refs / list-of-refs)
 448                             flush-pkt
 449
 450         no-refs          =  PKT-LINE(zero-id SP "capabilities^{}"
 451                                      NUL capability-list LF)
 452
 453         list-of-refs     =  first-ref *other-ref
 454         first-ref        =  PKT-LINE(obj-id SP refname
 455                                      NUL capability-list LF)
 456
 457         other-ref        =  PKT-LINE(other-tip / other-peeled)
 458         other-tip        =  obj-id SP refname LF
 459         other-peeled     =  obj-id SP refname "^{}" LF
 460
 461         capability-list  =  capability *(SP capability)
 462     capability       =  1*(ALPHA / DIGIT / "-" / "_")
 463 ----
 464
 465
 466 Smart Service git-upload-pack
 467 ------------------------------
 468 This service reads from the remote repository.
 469
 470 Clients MUST first perform ref discovery with
 471 '$GIT_URL/info/refs?service=git-upload-pack'.
 472
 473 Clients MUST use POST method to send the request payload to the
 474 git-upload-pack service URL.
 475
 476 client request::
 477 ----
 478         POST $GIT_URL/git-upload-pack HTTP/1.0
 479         Content-Type: application/x-git-upload-pack-request
 480
 481         ....want 0a53e9ddeaddad63ad106860237bbf53411d11a7
 482         0000
 483         ....have 441b40d833fdfa93eb2908e52742248faf0ee993
 484         0000
 485 ----
 486
 487 server result::
 488 ----
 489         200 OK
 490         Content-Type: application/x-git-upload-pack-result
 491         Cache-Control: no-cache
 492
 493         ....ACK %s, common
 494         ....ACK %s, continue
 495         ....NAK
 496 ----
 497
 498 Clients MUST NOT reuse or revalidate a cached reponse.
 499 Servers MUST include sufficient Cache-Control headers
 500 to prevent caching of the response.
 501
 502 Servers SHOULD support all capabilities defined in this document.
 503
 504 Clients MUST send at least one 'want' command in the request body.
 505 Clients MUST NOT mention an obj-id in a 'want' command which did
 506 not appear in the response obtained through ref discovery.
 507
 508 ----
 509         upload-request    =  state-vector
 510                              have-list
 511                              compute-end
 512
 513         state-vector      =  want-list
 514                              prior-common
 515
 516         prior-common      =  *have-line
 517
 518         want-list         =  PKT-LINE(first-want)
 519                              *additional-want
 520                                                  flush-pkt
 521
 522         first-want        =  PKT-LINE("want" SP obj-id SP capability-list LF)
 523         additional-want   =  PKT-LINE("want" SP obj-id LF)
 524
 525         have-list         =  *have-line
 526         have-line         =  PKT-LINE("have" SP obj-id LF)
 527         compute-end       =  flush-pkt / PKT-LINE("done")
 528 ----
 529
 530 TODO: Document this further.
 531 TODO: Don't use uppercase for variable names below.
 532
 533 Capability include-tag
 534 ~~~~~~~~~~~~~~~~~~~~~~
 535
 536 When packing an object that an annotated tag points at, include the
 537 tag object too.  Clients can request this if they want to fetch
 538 tags, but don't know which tags they will need until after they
 539 receive the branch data.  By enabling include-tag an entire call
 540 to upload-pack can be avoided.
 541
 542 Capability thin-pack
 543 ~~~~~~~~~~~~~~~~~~~~
 544
 545 When packing a deltified object the base is not included if the base
 546 is reachable from an object listed in the COMMON set by the client.
 547 This reduces the bandwidth required to transfer, but it does slightly
 548 increase processing time for the client to save the pack to disk.
 549
 550 The Negotiation Algorithm
 551 ~~~~~~~~~~~~~~~~~~~~~~~~~
 552 The computation to select the minimal pack proceeds as follows
 553 (c = client, s = server):
 554
 555  init step:
 556  (c) Use ref discovery to obtain the advertised refs.
 557  (c) Place any object seen into set ADVERTISED.
 558
 559  (c) Build an empty set, COMMON, to hold the objects that are later
 560      determined to be on both ends.
 561  (c) Build a set, WANT, of the objects from ADVERTISED the client
 562      wants to fetch, based on what it saw during ref discovery.
 563
 564  (c) Start a queue, C_PENDING, ordered by commit time (popping newest
 565      first).  Add all client refs.  When a commit is popped from
 566      the queue its parents should be automatically inserted back.
 567      Commits MUST only enter the queue once.
 568
 569  one compute step:
 570  (c) Send one $GIT_URL/git-upload-pack request:
 571
 572         C: 0032want <WANT #1>...............................
 573         C: 0032want <WANT #2>...............................
 574         ....
 575         C: 0032have <COMMON #1>.............................
 576         C: 0032have <COMMON #2>.............................
 577         ....
 578         C: 0032have <HAVE #1>...............................
 579         C: 0032have <HAVE #2>...............................
 580         ....
 581         C: 0000
 582
 583      The stream is organized into "commands", with each command
 584      appearing by itself in a pkt-line.  Within a command line
 585      the text leading up to the first space is the command name,
 586      and the remainder of the line to the first LF is the value.
 587      Command lines are terminated with an LF as the last byte of
 588      the pkt-line value.
 589
 590      Commands MUST appear in the following order, if they appear
 591      at all in the request stream:
 592
 593        * want
 594        * have
 595
 596      The stream is terminated by a pkt-line flush ("0000").
 597
 598      A single "want" or "have" command MUST have one hex formatted
 599      SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending
 600      multiple commands.
 601
 602      The HAVE list is created by popping the first 32 commits
 603      from C_PENDING.  Less can be supplied if C_PENDING empties.
 604
 605      If the client has sent 256 HAVE commits and has not yet
 606      received one of those back from S_COMMON, or the client has
 607      emptied C_PENDING it should include a "done" command to let
 608      the server know it won't proceed:
 609
 610         C: 0009done
 611
 612   (s) Parse the git-upload-pack request:
 613
 614       Verify all objects in WANT are directly reachable from refs.
 615
 616           The server MAY walk backwards through history or through
 617       the reflog to permit slightly stale requests.
 618
 619       If no WANT objects are received, send an error:
 620
 621 TODO: Define error if no want lines are requested.
 622
 623       If any WANT object is not reachable, send an error:
 624
 625 TODO: Define error if an invalid want is requested.
 626
 627      Create an empty list, S_COMMON.
 628
 629      If 'have' was sent:
 630
 631      Loop through the objects in the order supplied by the client.
 632      For each object, if the server has the object reachable from
 633      a ref, add it to S_COMMON.  If a commit is added to S_COMMON,
 634      do not add any ancestors, even if they also appear in HAVE.
 635
 636   (s) Send the git-upload-pack response:
 637
 638      If the server has found a closed set of objects to pack or the
 639      request ends with "done", it replies with the pack.
 640
 641 TODO: Document the pack based response
 642         S: PACK...
 643
 644      The returned stream is the side-band-64k protocol supported
 645      by the git-upload-pack service, and the pack is embedded into
 646      stream 1.  Progress messages from the server side may appear
 647      in stream 2.
 648
 649      Here a "closed set of objects" is defined to have at least
 650      one path from every WANT to at least one COMMON object.
 651
 652      If the server needs more information, it replies with a
 653      status continue response:
 654
 655 TODO: Document the non-pack response
 656
 657   (c) Parse the upload-pack response:
 658
 659 TODO: Document parsing response
 660
 661       Do another compute step.
 662
 663
 664 Smart Service git-receive-pack
 665 ------------------------------
 666 This service modifies the remote repository.
 667
 668 Clients MUST first perform ref discovery with
 669 '$GIT_URL/info/refs?service=git-receive-pack'.
 670
 671         C: POST $GIT_URL/git-receive-pack HTTP/1.0
 672         C: Content-Type: application/x-git-receive-pack-request
 673         C:
 674         C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
 675         C: 0000
 676         C: PACK....
 677
 678         S: 200 OK
 679         S: Content-Type: application/x-git-receive-pack-result
 680         S: Cache-Control: no-cache
 681         S:
 682         S: ....
 683
 684 Clients MUST NOT reuse or revalidate a cached reponse.
 685 Servers MUST include sufficient Cache-Control headers
 686 to prevent caching of the response.
 687
 688 Servers SHOULD support all capabilities defined here.
 689
 690 Clients MUST send at least one command in the request body.
 691 Within the command portion of the request body clients SHOULD send
 692 the id obtained through ref discovery as old_id.
 693
 694 ----
 695         update-request    =  command-list pack-file
 696
 697         command-list      =  PKT-LINE(command NUL capability-list LF)
 698                              *PKT-LINE(command LF)
 699                              flush-pkt
 700
 701         command           =  create / delete / update
 702         create            =  zero-id SP new-id  SP name
 703         delete            =  old-id  SP zero-id SP name
 704         update            =  old-id  SP new-id  SP name
 705
 706         old-id            =  obj-id
 707         new-id            =  obj-id
 708
 709         pack-file         = "PACK" 24*(OCTET)
 710
 711         update-response   = unpack-status
 712                             1*(command-status)
 713                             flush-pkt
 714
 715         unpack-status     = PKT-LINE("unpack" SP unpack-result LF)
 716         unpack-result     = "ok" / error-msg
 717
 718         command-status    = command-ok / command-fail
 719         command-ok        = PKT-LINE("ok" SP refname LF)
 720         command-fail      = PKT-LINE("ng" SP refname SP error-msg LF)
 721
 722         error-msg         = 1*(OCTECT) ; where not "ok"
 723 ----
 724
 725 TODO: Document this further.
 726
 727
 728 References
 729 ----------
 730
 731 link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 732 link:http://www.ietf.org/rfc/rfc2119.txt[RFC 2119: Key words for use in RFCs to Indicate Requirement Levels]
 733 link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
 734 link:http://www.ietf.org/rfc/rfc5234.txt[RFC 5234: Augmented BNF for Syntax Specifications: ABNF]
 735