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 can automatically upgrade "dumb"
  10 protocol URLs to smart URLs.  This permits all users to have the
  11 same published URL, and the peers automatically select the most
  12 efficient transport available to them.
  13
  14
  15 URL Format
  16 ----------
  17
  18 URLs for Git repositories accessed by HTTP use the standard HTTP
  19 URL syntax documented by RFC 1738, so they are of the form:
  20
  21   http://<host>:<port>/<path>?<searchpart>
  22
  23 Within this documentation the placeholder `$GIT_URL` will stand for
  24 the http:// repository URL entered by the end-user.
  25
  26 Servers SHOULD handle all requests to locations matching `$GIT_URL`, as
  27 both the "smart" and "dumb" HTTP protocols used by Git operate
  28 by appending additional path components onto the end of the user
  29 supplied `$GIT_URL` string.
  30
  31 An example of a dumb client requesting for a loose object:
  32
  33   $GIT_URL:     http://example.com:8080/git/repo.git
  34   URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
  35
  36 An example of a smart request to a catch-all gateway:
  37
  38   $GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
  39   URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
  40
  41 An example of a request to a submodule:
  42
  43   $GIT_URL:     http://example.com/git/repo.git/path/submodule.git
  44   URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs
  45
  46 Clients MUST strip a trailing `/`, if present, from the user supplied
  47 `$GIT_URL` string to prevent empty path tokens (`//`) from appearing
  48 in any URL sent to a server.  Compatible clients MUST expand
  49 `$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.
  50
  51
  52 Authentication
  53 --------------
  54
  55 Standard HTTP authentication is used if authentication is required
  56 to access a repository, and MAY be configured and enforced by the
  57 HTTP server software.
  58
  59 Because Git repositories are accessed by standard path components
  60 server administrators MAY use directory based permissions within
  61 their HTTP server to control repository access.
  62
  63 Clients SHOULD support Basic authentication as described by RFC 2617.
  64 Servers SHOULD support Basic authentication by relying upon the
  65 HTTP server placed in front of the Git server software.
  66
  67 Servers SHOULD NOT require HTTP cookies for the purposes of
  68 authentication or access control.
  69
  70 Clients and servers MAY support other common forms of HTTP based
  71 authentication, such as Digest authentication.
  72
  73
  74 SSL
  75 ---
  76
  77 Clients and servers SHOULD support SSL, particularly to protect
  78 passwords when relying on Basic HTTP authentication.
  79
  80
  81 Session State
  82 -------------
  83
  84 The Git over HTTP protocol (much like HTTP itself) is stateless
  85 from the perspective of the HTTP server side.  All state MUST be
  86 retained and managed by the client process.  This permits simple
  87 round-robin load-balancing on the server side, without needing to
  88 worry about state management.
  89
  90 Clients MUST NOT require state management on the server side in
  91 order to function correctly.
  92
  93 Servers MUST NOT require HTTP cookies in order to function correctly.
  94 Clients MAY store and forward HTTP cookies during request processing
  95 as described by RFC 2616 (HTTP/1.1).  Servers SHOULD ignore any
  96 cookies sent by a client.
  97
  98
  99 General Request Processing
 100 --------------------------
 101
 102 Except where noted, all standard HTTP behavior SHOULD be assumed
 103 by both client and server.  This includes (but is not necessarily
 104 limited to):
 105
 106 If there is no repository at `$GIT_URL`, or the resource pointed to by a
 107 location matching `$GIT_URL` does not exist, the server MUST NOT respond
 108 with `200 OK` response.  A server SHOULD respond with
 109 `404 Not Found`, `410 Gone`, or any other suitable HTTP status code
 110 which does not imply the resource exists as requested.
 111
 112 If there is a repository at `$GIT_URL`, but access is not currently
 113 permitted, the server MUST respond with the `403 Forbidden` HTTP
 114 status code.
 115
 116 Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
 117 Servers SHOULD support chunked encoding for both request and response
 118 bodies.
 119
 120 Clients SHOULD support both HTTP 1.0 and HTTP 1.1.
 121 Clients SHOULD support chunked encoding for both request and response
 122 bodies.
 123
 124 Servers MAY return ETag and/or Last-Modified headers.
 125
 126 Clients MAY revalidate cached entities by including If-Modified-Since
 127 and/or If-None-Match request headers.
 128
 129 Servers MAY return `304 Not Modified` if the relevant headers appear
 130 in the request and the entity has not changed.  Clients MUST treat
 131 `304 Not Modified` identical to `200 OK` by reusing the cached entity.
 132
 133 Clients MAY reuse a cached entity without revalidation if the
 134 Cache-Control and/or Expires header permits caching.  Clients and
 135 servers MUST follow RFC 2616 for cache controls.
 136
 137
 138 Discovering References
 139 ----------------------
 140
 141 All HTTP clients MUST begin either a fetch or a push exchange by
 142 discovering the references available on the remote repository.
 143
 144 Dumb Clients
 145 ~~~~~~~~~~~~
 146
 147 HTTP clients that only support the "dumb" protocol MUST discover
 148 references by making a request for the special info/refs file of
 149 the repository.
 150
 151 Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,
 152 without any search/query parameters.
 153
 154    C: GET $GIT_URL/info/refs HTTP/1.0
 155
 156    S: 200 OK
 157    S:
 158    S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
 159    S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
 160    S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
 161    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
 162
 163 The Content-Type of the returned info/refs entity SHOULD be
 164 `text/plain; charset=utf-8`, but MAY be any content type.
 165 Clients MUST NOT attempt to validate the returned Content-Type.
 166 Dumb servers MUST NOT return a return type starting with
 167 `application/x-git-`.
 168
 169 Cache-Control headers MAY be returned to disable caching of the
 170 returned entity.
 171
 172 When examining the response clients SHOULD only examine the HTTP
 173 status code.  Valid responses are `200 OK`, or `304 Not Modified`.
 174
 175 The returned content is a UNIX formatted text file describing
 176 each ref and its known value.  The file SHOULD be sorted by name
 177 according to the C locale ordering.  The file SHOULD NOT include
 178 the default ref named `HEAD`.
 179
 180   info_refs   =  *( ref_record )
 181   ref_record  =  any_ref / peeled_ref
 182
 183   any_ref     =  obj-id HTAB refname LF
 184   peeled_ref  =  obj-id HTAB refname LF
 185                  obj-id HTAB refname "^{}" LF
 186
 187 Smart Clients
 188 ~~~~~~~~~~~~~
 189
 190 HTTP clients that support the "smart" protocol (or both the
 191 "smart" and "dumb" protocols) MUST discover references by making
 192 a parameterized request for the info/refs file of the repository.
 193
 194 The request MUST contain exactly one query parameter,
 195 `service=$servicename`, where `$servicename` MUST be the service
 196 name the client wishes to contact to complete the operation.
 197 The request MUST NOT contain additional query parameters.
 198
 199    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
 200
 201 dumb server reply:
 202
 203    S: 200 OK
 204    S:
 205    S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
 206    S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
 207    S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
 208    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
 209
 210 smart server reply:
 211
 212    S: 200 OK
 213    S: Content-Type: application/x-git-upload-pack-advertisement
 214    S: Cache-Control: no-cache
 215    S:
 216    S: 001e# service=git-upload-pack\n
 217    S: 0000
 218    S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
 219    S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
 220    S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
 221    S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
 222    S: 0000
 223
 224 The client may send Extra Parameters (see
 225 Documentation/technical/pack-protocol.txt) as a colon-separated string
 226 in the Git-Protocol HTTP header.
 227
 228 Uses the `--http-backend-info-refs` option to
 229 linkgit:git-upload-pack[1].
 230
 231 Dumb Server Response
 232 ^^^^^^^^^^^^^^^^^^^^
 233 Dumb servers MUST respond with the dumb server reply format.
 234
 235 See the prior section under dumb clients for a more detailed
 236 description of the dumb server response.
 237
 238 Smart Server Response
 239 ^^^^^^^^^^^^^^^^^^^^^
 240 If the server does not recognize the requested service name, or the
 241 requested service name has been disabled by the server administrator,
 242 the server MUST respond with the `403 Forbidden` HTTP status code.
 243
 244 Otherwise, smart servers MUST respond with the smart server reply
 245 format for the requested service name.
 246
 247 Cache-Control headers SHOULD be used to disable caching of the
 248 returned entity.
 249
 250 The Content-Type MUST be `application/x-$servicename-advertisement`.
 251 Clients SHOULD fall back to the dumb protocol if another content
 252 type is returned.  When falling back to the dumb protocol clients
 253 SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but
 254 instead SHOULD use the response already in hand.  Clients MUST NOT
 255 continue if they do not support the dumb protocol.
 256
 257 Clients MUST validate the status code is either `200 OK` or
 258 `304 Not Modified`.
 259
 260 Clients MUST validate the first five bytes of the response entity
 261 matches the regex `^[0-9a-f]{4}#`.  If this test fails, clients
 262 MUST NOT continue.
 263
 264 Clients MUST parse the entire response as a sequence of pkt-line
 265 records.
 266
 267 Clients MUST verify the first pkt-line is `# service=$servicename`.
 268 Servers MUST set $servicename to be the request parameter value.
 269 Servers SHOULD include an LF at the end of this line.
 270 Clients MUST ignore an LF at the end of the line.
 271
 272 Servers MUST terminate the response with the magic `0000` end
 273 pkt-line marker.
 274
 275 The returned response is a pkt-line stream describing each ref and
 276 its known value.  The stream SHOULD be sorted by name according to
 277 the C locale ordering.  The stream SHOULD include the default ref
 278 named `HEAD` as the first ref.  The stream MUST include capability
 279 declarations behind a NUL on the first ref.
 280
 281 The returned response contains "version 1" if "version=1" was sent as an
 282 Extra Parameter.
 283
 284   smart_reply     =  PKT-LINE("# service=$servicename" LF)
 285                      "0000"
 286                      *1("version 1")
 287                      ref_list
 288                      "0000"
 289   ref_list        =  empty_list / non_empty_list
 290
 291   empty_list      =  PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
 292
 293   non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)
 294                      *ref_record
 295
 296   cap-list        =  capability *(SP capability)
 297   capability      =  1*(LC_ALPHA / DIGIT / "-" / "_")
 298   LC_ALPHA        =  %x61-7A
 299
 300   ref_record      =  any_ref / peeled_ref
 301   any_ref         =  PKT-LINE(obj-id SP name LF)
 302   peeled_ref      =  PKT-LINE(obj-id SP name LF)
 303                      PKT-LINE(obj-id SP name "^{}" LF
 304
 305
 306 Smart Service git-upload-pack
 307 ------------------------------
 308 This service reads from the repository pointed to by `$GIT_URL`.
 309
 310 Clients MUST first perform ref discovery with
 311 `$GIT_URL/info/refs?service=git-upload-pack`.
 312
 313    C: POST $GIT_URL/git-upload-pack HTTP/1.0
 314    C: Content-Type: application/x-git-upload-pack-request
 315    C:
 316    C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
 317    C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
 318    C: 0000
 319
 320    S: 200 OK
 321    S: Content-Type: application/x-git-upload-pack-result
 322    S: Cache-Control: no-cache
 323    S:
 324    S: ....ACK %s, continue
 325    S: ....NAK
 326
 327 Clients MUST NOT reuse or revalidate a cached response.
 328 Servers MUST include sufficient Cache-Control headers
 329 to prevent caching of the response.
 330
 331 Servers SHOULD support all capabilities defined here.
 332
 333 Clients MUST send at least one "want" command in the request body.
 334 Clients MUST NOT reference an id in a "want" command which did not
 335 appear in the response obtained through ref discovery unless the
 336 server advertises capability `allow-tip-sha1-in-want` or
 337 `allow-reachable-sha1-in-want`.
 338
 339   compute_request   =  want_list
 340                        have_list
 341                        request_end
 342   request_end       =  "0000" / "done"
 343
 344   want_list         =  PKT-LINE(want SP cap_list LF)
 345                        *(want_pkt)
 346   want_pkt          =  PKT-LINE(want LF)
 347   want              =  "want" SP id
 348   cap_list          =  capability *(SP capability)
 349
 350   have_list         =  *PKT-LINE("have" SP id LF)
 351
 352 TODO: Document this further.
 353
 354 The Negotiation Algorithm
 355 ~~~~~~~~~~~~~~~~~~~~~~~~~
 356 The computation to select the minimal pack proceeds as follows
 357 (C = client, S = server):
 358
 359 'init step:'
 360
 361 C: Use ref discovery to obtain the advertised refs.
 362
 363 C: Place any object seen into set `advertised`.
 364
 365 C: Build an empty set, `common`, to hold the objects that are later
 366    determined to be on both ends.
 367
 368 C: Build a set, `want`, of the objects from `advertised` the client
 369    wants to fetch, based on what it saw during ref discovery.
 370
 371 C: Start a queue, `c_pending`, ordered by commit time (popping newest
 372    first).  Add all client refs.  When a commit is popped from
 373    the queue its parents SHOULD be automatically inserted back.
 374    Commits MUST only enter the queue once.
 375
 376 'one compute step:'
 377
 378 C: Send one `$GIT_URL/git-upload-pack` request:
 379
 380    C: 0032want <want #1>...............................
 381    C: 0032want <want #2>...............................
 382    ....
 383    C: 0032have <common #1>.............................
 384    C: 0032have <common #2>.............................
 385    ....
 386    C: 0032have <have #1>...............................
 387    C: 0032have <have #2>...............................
 388    ....
 389    C: 0000
 390
 391 The stream is organized into "commands", with each command
 392 appearing by itself in a pkt-line.  Within a command line,
 393 the text leading up to the first space is the command name,
 394 and the remainder of the line to the first LF is the value.
 395 Command lines are terminated with an LF as the last byte of
 396 the pkt-line value.
 397
 398 Commands MUST appear in the following order, if they appear
 399 at all in the request stream:
 400
 401 * "want"
 402 * "have"
 403
 404 The stream is terminated by a pkt-line flush (`0000`).
 405
 406 A single "want" or "have" command MUST have one hex formatted
 407 object name as its value.  Multiple object names MUST be sent by sending
 408 multiple commands. Object names MUST be given using the object format
 409 negotiated through the `object-format` capability (default SHA-1).
 410
 411 The `have` list is created by popping the first 32 commits
 412 from `c_pending`.  Less can be supplied if `c_pending` empties.
 413
 414 If the client has sent 256 "have" commits and has not yet
 415 received one of those back from `s_common`, or the client has
 416 emptied `c_pending` it SHOULD include a "done" command to let
 417 the server know it won't proceed:
 418
 419    C: 0009done
 420
 421 S: Parse the git-upload-pack request:
 422
 423 Verify all objects in `want` are directly reachable from refs.
 424
 425 The server MAY walk backwards through history or through
 426 the reflog to permit slightly stale requests.
 427
 428 If no "want" objects are received, send an error:
 429 TODO: Define error if no "want" lines are requested.
 430
 431 If any "want" object is not reachable, send an error:
 432 TODO: Define error if an invalid "want" is requested.
 433
 434 Create an empty list, `s_common`.
 435
 436 If "have" was sent:
 437
 438 Loop through the objects in the order supplied by the client.
 439
 440 For each object, if the server has the object reachable from
 441 a ref, add it to `s_common`.  If a commit is added to `s_common`,
 442 do not add any ancestors, even if they also appear in `have`.
 443
 444 S: Send the git-upload-pack response:
 445
 446 If the server has found a closed set of objects to pack or the
 447 request ends with "done", it replies with the pack.
 448 TODO: Document the pack based response
 449
 450    S: PACK...
 451
 452 The returned stream is the side-band-64k protocol supported
 453 by the git-upload-pack service, and the pack is embedded into
 454 stream 1.  Progress messages from the server side MAY appear
 455 in stream 2.
 456
 457 Here a "closed set of objects" is defined to have at least
 458 one path from every "want" to at least one "common" object.
 459
 460 If the server needs more information, it replies with a
 461 status continue response:
 462 TODO: Document the non-pack response
 463
 464 C: Parse the upload-pack response:
 465    TODO: Document parsing response
 466
 467 'Do another compute step.'
 468
 469
 470 Smart Service git-receive-pack
 471 ------------------------------
 472 This service reads from the repository pointed to by `$GIT_URL`.
 473
 474 Clients MUST first perform ref discovery with
 475 `$GIT_URL/info/refs?service=git-receive-pack`.
 476
 477    C: POST $GIT_URL/git-receive-pack HTTP/1.0
 478    C: Content-Type: application/x-git-receive-pack-request
 479    C:
 480    C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
 481    C: 0000
 482    C: PACK....
 483
 484    S: 200 OK
 485    S: Content-Type: application/x-git-receive-pack-result
 486    S: Cache-Control: no-cache
 487    S:
 488    S: ....
 489
 490 Clients MUST NOT reuse or revalidate a cached response.
 491 Servers MUST include sufficient Cache-Control headers
 492 to prevent caching of the response.
 493
 494 Servers SHOULD support all capabilities defined here.
 495
 496 Clients MUST send at least one command in the request body.
 497 Within the command portion of the request body clients SHOULD send
 498 the id obtained through ref discovery as old_id.
 499
 500   update_request  =  command_list
 501                      "PACK" <binary data>
 502
 503   command_list    =  PKT-LINE(command NUL cap_list LF)
 504                      *(command_pkt)
 505   command_pkt     =  PKT-LINE(command LF)
 506   cap_list        =  *(SP capability) SP
 507
 508   command         =  create / delete / update
 509   create          =  zero-id SP new_id SP name
 510   delete          =  old_id SP zero-id SP name
 511   update          =  old_id SP new_id SP name
 512
 513 TODO: Document this further.
 514
 515
 516 References
 517 ----------
 518
 519 http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
 520 http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
 521 link:technical/pack-protocol.html
 522 link:technical/protocol-capabilities.html