Documentation/gitprotocol-http.txt

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