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