From 1e2320161d27684205f55ffa91f7f481d32863d5 Mon Sep 17 00:00:00 2001 From: Ævar Arnfjörð Bjarmason Date: Thu, 4 Aug 2022 18:28:41 +0200 Subject: docs: move http-protocol docs to man section 5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the http-protocol.txt documentation over. I'm renaming it to "protocol-http" to be consistent with other things in the new gitformat-protocol-* namespace. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- Documentation/git-upload-pack.txt | 6 +- Documentation/gitprotocol-http.txt | 543 ++++++++++++++++++++++++++++++ Documentation/gitprotocol-pack.txt | 2 +- Documentation/gitprotocol-v2.txt | 4 +- Documentation/technical/http-protocol.txt | 522 ---------------------------- command-list.txt | 1 + 7 files changed, 551 insertions(+), 529 deletions(-) create mode 100644 Documentation/gitprotocol-http.txt delete mode 100644 Documentation/technical/http-protocol.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 41a070ab59..346bbcf8be 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -36,6 +36,7 @@ MAN5_TXT += gitmailmap.txt MAN5_TXT += gitmodules.txt MAN5_TXT += gitprotocol-capabilities.txt MAN5_TXT += gitprotocol-common.txt +MAN5_TXT += gitprotocol-http.txt MAN5_TXT += gitprotocol-pack.txt MAN5_TXT += gitprotocol-v2.txt MAN5_TXT += gitrepository-layout.txt @@ -106,7 +107,6 @@ TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/hash-function-transition -TECH_DOCS += technical/http-protocol TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 3409e0d36d..3f89d64077 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -39,9 +39,9 @@ OPTIONS --http-backend-info-refs:: Used by linkgit:git-http-backend[1] to serve up `$GIT_URL/info/refs?service=git-upload-pack` requests. See - "Smart Clients" in link:technical/http-protocol.html[the HTTP - transfer protocols] documentation and "HTTP Transport" in the - linkgit:gitprotocol-v2[5] documentation. Also understood by + "Smart Clients" in linkgit:gitprotocol-http[5] and "HTTP + Transport" in in the linkgit:gitprotocol-v2[5] + documentation. Also understood by linkgit:git-receive-pack[1]. :: diff --git a/Documentation/gitprotocol-http.txt b/Documentation/gitprotocol-http.txt new file mode 100644 index 0000000000..ccc13f0a40 --- /dev/null +++ b/Documentation/gitprotocol-http.txt @@ -0,0 +1,543 @@ +gitprotocol-http(5) +=================== + +NAME +---- +gitprotocol-http - Git HTTP-based protocols + + +SYNOPSIS +-------- +[verse] + + + +DESCRIPTION +----------- + +Git supports two HTTP based transfer protocols. A "dumb" protocol +which requires only a standard HTTP server on the server end of the +connection, and a "smart" protocol which requires a Git aware CGI +(or server module). This document describes both protocols. + +As a design feature smart clients can automatically upgrade "dumb" +protocol URLs to smart URLs. This permits all users to have the +same published URL, and the peers automatically select the most +efficient transport available to them. + + +URL Format +---------- + +URLs for Git repositories accessed by HTTP use the standard HTTP +URL syntax documented by RFC 1738, so they are of the form: + + http://:/? + +Within this documentation the placeholder `$GIT_URL` will stand for +the http:// repository URL entered by the end-user. + +Servers SHOULD handle all requests to locations matching `$GIT_URL`, as +both the "smart" and "dumb" HTTP protocols used by Git operate +by appending additional path components onto the end of the user +supplied `$GIT_URL` string. + +An example of a dumb client requesting for a loose object: + + $GIT_URL: http://example.com:8080/git/repo.git + URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355 + +An example of a smart request to a catch-all gateway: + + $GIT_URL: http://example.com/daemon.cgi?svc=git&q= + URL request: http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack + +An example of a request to a submodule: + + $GIT_URL: http://example.com/git/repo.git/path/submodule.git + URL request: http://example.com/git/repo.git/path/submodule.git/info/refs + +Clients MUST strip a trailing `/`, if present, from the user supplied +`$GIT_URL` string to prevent empty path tokens (`//`) from appearing +in any URL sent to a server. Compatible clients MUST expand +`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`. + + +Authentication +-------------- + +Standard HTTP authentication is used if authentication is required +to access a repository, and MAY be configured and enforced by the +HTTP server software. + +Because Git repositories are accessed by standard path components +server administrators MAY use directory based permissions within +their HTTP server to control repository access. + +Clients SHOULD support Basic authentication as described by RFC 2617. +Servers SHOULD support Basic authentication by relying upon the +HTTP server placed in front of the Git server software. + +Servers SHOULD NOT require HTTP cookies for the purposes of +authentication or access control. + +Clients and servers MAY support other common forms of HTTP based +authentication, such as Digest authentication. + + +SSL +--- + +Clients and servers SHOULD support SSL, particularly to protect +passwords when relying on Basic HTTP authentication. + + +Session State +------------- + +The Git over HTTP protocol (much like HTTP itself) is stateless +from the perspective of the HTTP server side. All state MUST be +retained and managed by the client process. This permits simple +round-robin load-balancing on the server side, without needing to +worry about state management. + +Clients MUST NOT require state management on the server side in +order to function correctly. + +Servers MUST NOT require HTTP cookies in order to function correctly. +Clients MAY store and forward HTTP cookies during request processing +as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any +cookies sent by a client. + + +General Request Processing +-------------------------- + +Except where noted, all standard HTTP behavior SHOULD be assumed +by both client and server. This includes (but is not necessarily +limited to): + +If there is no repository at `$GIT_URL`, or the resource pointed to by a +location matching `$GIT_URL` does not exist, the server MUST NOT respond +with `200 OK` response. A server SHOULD respond with +`404 Not Found`, `410 Gone`, or any other suitable HTTP status code +which does not imply the resource exists as requested. + +If there is a repository at `$GIT_URL`, but access is not currently +permitted, the server MUST respond with the `403 Forbidden` HTTP +status code. + +Servers SHOULD support both HTTP 1.0 and HTTP 1.1. +Servers SHOULD support chunked encoding for both request and response +bodies. + +Clients SHOULD support both HTTP 1.0 and HTTP 1.1. +Clients SHOULD support chunked encoding for both request and response +bodies. + +Servers MAY return ETag and/or Last-Modified headers. + +Clients MAY revalidate cached entities by including If-Modified-Since +and/or If-None-Match request headers. + +Servers MAY return `304 Not Modified` if the relevant headers appear +in the request and the entity has not changed. Clients MUST treat +`304 Not Modified` identical to `200 OK` by reusing the cached entity. + +Clients MAY reuse a cached entity without revalidation if the +Cache-Control and/or Expires header permits caching. Clients and +servers MUST follow RFC 2616 for cache controls. + + +Discovering References +---------------------- + +All HTTP clients MUST begin either a fetch or a push exchange by +discovering the references available on the remote repository. + +Dumb Clients +~~~~~~~~~~~~ + +HTTP clients that only support the "dumb" protocol MUST discover +references by making a request for the special info/refs file of +the repository. + +Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`, +without any search/query parameters. + + C: GET $GIT_URL/info/refs HTTP/1.0 + + S: 200 OK + S: + S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint + S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master + S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 + S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} + +The Content-Type of the returned info/refs entity SHOULD be +`text/plain; charset=utf-8`, but MAY be any content type. +Clients MUST NOT attempt to validate the returned Content-Type. +Dumb servers MUST NOT return a return type starting with +`application/x-git-`. + +Cache-Control headers MAY be returned to disable caching of the +returned entity. + +When examining the response clients SHOULD only examine the HTTP +status code. Valid responses are `200 OK`, or `304 Not Modified`. + +The returned content is a UNIX formatted text file describing +each ref and its known value. The file SHOULD be sorted by name +according to the C locale ordering. The file SHOULD NOT include +the default ref named `HEAD`. + + info_refs = *( ref_record ) + ref_record = any_ref / peeled_ref + + any_ref = obj-id HTAB refname LF + peeled_ref = obj-id HTAB refname LF + obj-id HTAB refname "^{}" LF + +Smart Clients +~~~~~~~~~~~~~ + +HTTP clients that support the "smart" protocol (or both the +"smart" and "dumb" protocols) MUST discover references by making +a parameterized request for the info/refs file of the repository. + +The request MUST contain exactly one query parameter, +`service=$servicename`, where `$servicename` MUST be the service +name the client wishes to contact to complete the operation. +The request MUST NOT contain additional query parameters. + + C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 + +dumb server reply: + + S: 200 OK + S: + S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint + S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master + S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 + S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} + +smart server reply: + + S: 200 OK + S: Content-Type: application/x-git-upload-pack-advertisement + S: Cache-Control: no-cache + S: + S: 001e# service=git-upload-pack\n + S: 0000 + S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n + S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n + S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n + S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n + S: 0000 + +The client may send Extra Parameters (see +linkgit:gitprotocol-pack[5]) as a colon-separated string +in the Git-Protocol HTTP header. + +Uses the `--http-backend-info-refs` option to +linkgit:git-upload-pack[1]. + +Dumb Server Response +^^^^^^^^^^^^^^^^^^^^ +Dumb servers MUST respond with the dumb server reply format. + +See the prior section under dumb clients for a more detailed +description of the dumb server response. + +Smart Server Response +^^^^^^^^^^^^^^^^^^^^^ +If the server does not recognize the requested service name, or the +requested service name has been disabled by the server administrator, +the server MUST respond with the `403 Forbidden` HTTP status code. + +Otherwise, smart servers MUST respond with the smart server reply +format for the requested service name. + +Cache-Control headers SHOULD be used to disable caching of the +returned entity. + +The Content-Type MUST be `application/x-$servicename-advertisement`. +Clients SHOULD fall back to the dumb protocol if another content +type is returned. When falling back to the dumb protocol clients +SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but +instead SHOULD use the response already in hand. Clients MUST NOT +continue if they do not support the dumb protocol. + +Clients MUST validate the status code is either `200 OK` or +`304 Not Modified`. + +Clients MUST validate the first five bytes of the response entity +matches the regex `^[0-9a-f]{4}#`. If this test fails, clients +MUST NOT continue. + +Clients MUST parse the entire response as a sequence of pkt-line +records. + +Clients MUST verify the first pkt-line is `# service=$servicename`. +Servers MUST set $servicename to be the request parameter value. +Servers SHOULD include an LF at the end of this line. +Clients MUST ignore an LF at the end of the line. + +Servers MUST terminate the response with the magic `0000` end +pkt-line marker. + +The returned response is a pkt-line stream describing each ref and +its known value. The stream SHOULD be sorted by name according to +the C locale ordering. The stream SHOULD include the default ref +named `HEAD` as the first ref. The stream MUST include capability +declarations behind a NUL on the first ref. + +The returned response contains "version 1" if "version=1" was sent as an +Extra Parameter. + + smart_reply = PKT-LINE("# service=$servicename" LF) + "0000" + *1("version 1") + ref_list + "0000" + ref_list = empty_list / non_empty_list + + empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF) + + non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF) + *ref_record + + cap-list = capability *(SP capability) + capability = 1*(LC_ALPHA / DIGIT / "-" / "_") + LC_ALPHA = %x61-7A + + ref_record = any_ref / peeled_ref + any_ref = PKT-LINE(obj-id SP name LF) + peeled_ref = PKT-LINE(obj-id SP name LF) + PKT-LINE(obj-id SP name "^{}" LF + + +Smart Service git-upload-pack +------------------------------ +This service reads from the repository pointed to by `$GIT_URL`. + +Clients MUST first perform ref discovery with +`$GIT_URL/info/refs?service=git-upload-pack`. + + C: POST $GIT_URL/git-upload-pack HTTP/1.0 + C: Content-Type: application/x-git-upload-pack-request + C: + C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n + C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n + C: 0000 + + S: 200 OK + S: Content-Type: application/x-git-upload-pack-result + S: Cache-Control: no-cache + S: + S: ....ACK %s, continue + S: ....NAK + +Clients MUST NOT reuse or revalidate a cached response. +Servers MUST include sufficient Cache-Control headers +to prevent caching of the response. + +Servers SHOULD support all capabilities defined here. + +Clients MUST send at least one "want" command in the request body. +Clients MUST NOT reference an id in a "want" command which did not +appear in the response obtained through ref discovery unless the +server advertises capability `allow-tip-sha1-in-want` or +`allow-reachable-sha1-in-want`. + + compute_request = want_list + have_list + request_end + request_end = "0000" / "done" + + want_list = PKT-LINE(want SP cap_list LF) + *(want_pkt) + want_pkt = PKT-LINE(want LF) + want = "want" SP id + cap_list = capability *(SP capability) + + have_list = *PKT-LINE("have" SP id LF) + +TODO: Document this further. + +The Negotiation Algorithm +~~~~~~~~~~~~~~~~~~~~~~~~~ +The computation to select the minimal pack proceeds as follows +(C = client, S = server): + +'init step:' + +C: Use ref discovery to obtain the advertised refs. + +C: Place any object seen into set `advertised`. + +C: Build an empty set, `common`, to hold the objects that are later + determined to be on both ends. + +C: Build a set, `want`, of the objects from `advertised` the client + wants to fetch, based on what it saw during ref discovery. + +C: Start a queue, `c_pending`, ordered by commit time (popping newest + first). Add all client refs. When a commit is popped from + the queue its parents SHOULD be automatically inserted back. + Commits MUST only enter the queue once. + +'one compute step:' + +C: Send one `$GIT_URL/git-upload-pack` request: + + C: 0032want ............................... + C: 0032want ............................... + .... + C: 0032have ............................. + C: 0032have ............................. + .... + C: 0032have ............................... + C: 0032have ............................... + .... + C: 0000 + +The stream is organized into "commands", with each command +appearing by itself in a pkt-line. Within a command line, +the text leading up to the first space is the command name, +and the remainder of the line to the first LF is the value. +Command lines are terminated with an LF as the last byte of +the pkt-line value. + +Commands MUST appear in the following order, if they appear +at all in the request stream: + +* "want" +* "have" + +The stream is terminated by a pkt-line flush (`0000`). + +A single "want" or "have" command MUST have one hex formatted +object name as its value. Multiple object names MUST be sent by sending +multiple commands. Object names MUST be given using the object format +negotiated through the `object-format` capability (default SHA-1). + +The `have` list is created by popping the first 32 commits +from `c_pending`. Less can be supplied if `c_pending` empties. + +If the client has sent 256 "have" commits and has not yet +received one of those back from `s_common`, or the client has +emptied `c_pending` it SHOULD include a "done" command to let +the server know it won't proceed: + + C: 0009done + +S: Parse the git-upload-pack request: + +Verify all objects in `want` are directly reachable from refs. + +The server MAY walk backwards through history or through +the reflog to permit slightly stale requests. + +If no "want" objects are received, send an error: +TODO: Define error if no "want" lines are requested. + +If any "want" object is not reachable, send an error: +TODO: Define error if an invalid "want" is requested. + +Create an empty list, `s_common`. + +If "have" was sent: + +Loop through the objects in the order supplied by the client. + +For each object, if the server has the object reachable from +a ref, add it to `s_common`. If a commit is added to `s_common`, +do not add any ancestors, even if they also appear in `have`. + +S: Send the git-upload-pack response: + +If the server has found a closed set of objects to pack or the +request ends with "done", it replies with the pack. +TODO: Document the pack based response + + S: PACK... + +The returned stream is the side-band-64k protocol supported +by the git-upload-pack service, and the pack is embedded into +stream 1. Progress messages from the server side MAY appear +in stream 2. + +Here a "closed set of objects" is defined to have at least +one path from every "want" to at least one "common" object. + +If the server needs more information, it replies with a +status continue response: +TODO: Document the non-pack response + +C: Parse the upload-pack response: + TODO: Document parsing response + +'Do another compute step.' + + +Smart Service git-receive-pack +------------------------------ +This service reads from the repository pointed to by `$GIT_URL`. + +Clients MUST first perform ref discovery with +`$GIT_URL/info/refs?service=git-receive-pack`. + + C: POST $GIT_URL/git-receive-pack HTTP/1.0 + C: Content-Type: application/x-git-receive-pack-request + C: + C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status + C: 0000 + C: PACK.... + + S: 200 OK + S: Content-Type: application/x-git-receive-pack-result + S: Cache-Control: no-cache + S: + S: .... + +Clients MUST NOT reuse or revalidate a cached response. +Servers MUST include sufficient Cache-Control headers +to prevent caching of the response. + +Servers SHOULD support all capabilities defined here. + +Clients MUST send at least one command in the request body. +Within the command portion of the request body clients SHOULD send +the id obtained through ref discovery as old_id. + + update_request = command_list + "PACK" + + command_list = PKT-LINE(command NUL cap_list LF) + *(command_pkt) + command_pkt = PKT-LINE(command LF) + cap_list = *(SP capability) SP + + command = create / delete / update + create = zero-id SP new_id SP name + delete = old_id SP zero-id SP name + update = old_id SP new_id SP name + +TODO: Document this further. + +REFERENCES +---------- + +http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] +http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] + +SEE ALSO +-------- + +linkgit:gitprotocol-pack[5] +linkgit:gitprotocol-capabilities[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.txt index 93b30b8845..dd4108b7a3 100644 --- a/Documentation/gitprotocol-pack.txt +++ b/Documentation/gitprotocol-pack.txt @@ -17,7 +17,7 @@ Git supports transferring data in packfiles over the ssh://, git://, http:// and file:// transports. There exist two sets of protocols, one for pushing data from a client to a server and another for fetching data from a server to a client. The three transports (ssh, git, file) use the same -protocol to transfer data. http is documented in http-protocol.txt. +protocol to transfer data. http is documented in linkgit:gitprotocol-http[5]. The processes invoked in the canonical Git implementation are 'upload-pack' on the server side and 'fetch-pack' on the client side for fetching data; diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index d6105e0740..c9c0f9160b 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -53,7 +53,7 @@ Initial Client Request In general a client can request to speak protocol v2 by sending `version=2` through the respective side-channel for the transport being used which inevitably sets `GIT_PROTOCOL`. More information can be -found in linkgit:gitprotocol-pack[5] and `http-protocol.txt`, as well as the +found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the `GIT_PROTOCOL` definition in `git.txt`. In all cases the response from the server is the capability advertisement. @@ -77,7 +77,7 @@ HTTP Transport ~~~~~~~~~~~~~~ When using the http:// or https:// transport a client makes a "smart" -info/refs request as described in `http-protocol.txt` and requests that +info/refs request as described in linkgit:gitprotocol-http[5] and requests that v2 be used by supplying "version=2" in the `Git-Protocol` header. C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt deleted file mode 100644 index 8bd672d55b..0000000000 --- a/Documentation/technical/http-protocol.txt +++ /dev/null @@ -1,522 +0,0 @@ -HTTP transfer protocols -======================= - -Git supports two HTTP based transfer protocols. A "dumb" protocol -which requires only a standard HTTP server on the server end of the -connection, and a "smart" protocol which requires a Git aware CGI -(or server module). This document describes both protocols. - -As a design feature smart clients can automatically upgrade "dumb" -protocol URLs to smart URLs. This permits all users to have the -same published URL, and the peers automatically select the most -efficient transport available to them. - - -URL Format ----------- - -URLs for Git repositories accessed by HTTP use the standard HTTP -URL syntax documented by RFC 1738, so they are of the form: - - http://:/? - -Within this documentation the placeholder `$GIT_URL` will stand for -the http:// repository URL entered by the end-user. - -Servers SHOULD handle all requests to locations matching `$GIT_URL`, as -both the "smart" and "dumb" HTTP protocols used by Git operate -by appending additional path components onto the end of the user -supplied `$GIT_URL` string. - -An example of a dumb client requesting for a loose object: - - $GIT_URL: http://example.com:8080/git/repo.git - URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355 - -An example of a smart request to a catch-all gateway: - - $GIT_URL: http://example.com/daemon.cgi?svc=git&q= - URL request: http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack - -An example of a request to a submodule: - - $GIT_URL: http://example.com/git/repo.git/path/submodule.git - URL request: http://example.com/git/repo.git/path/submodule.git/info/refs - -Clients MUST strip a trailing `/`, if present, from the user supplied -`$GIT_URL` string to prevent empty path tokens (`//`) from appearing -in any URL sent to a server. Compatible clients MUST expand -`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`. - - -Authentication --------------- - -Standard HTTP authentication is used if authentication is required -to access a repository, and MAY be configured and enforced by the -HTTP server software. - -Because Git repositories are accessed by standard path components -server administrators MAY use directory based permissions within -their HTTP server to control repository access. - -Clients SHOULD support Basic authentication as described by RFC 2617. -Servers SHOULD support Basic authentication by relying upon the -HTTP server placed in front of the Git server software. - -Servers SHOULD NOT require HTTP cookies for the purposes of -authentication or access control. - -Clients and servers MAY support other common forms of HTTP based -authentication, such as Digest authentication. - - -SSL ---- - -Clients and servers SHOULD support SSL, particularly to protect -passwords when relying on Basic HTTP authentication. - - -Session State -------------- - -The Git over HTTP protocol (much like HTTP itself) is stateless -from the perspective of the HTTP server side. All state MUST be -retained and managed by the client process. This permits simple -round-robin load-balancing on the server side, without needing to -worry about state management. - -Clients MUST NOT require state management on the server side in -order to function correctly. - -Servers MUST NOT require HTTP cookies in order to function correctly. -Clients MAY store and forward HTTP cookies during request processing -as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any -cookies sent by a client. - - -General Request Processing --------------------------- - -Except where noted, all standard HTTP behavior SHOULD be assumed -by both client and server. This includes (but is not necessarily -limited to): - -If there is no repository at `$GIT_URL`, or the resource pointed to by a -location matching `$GIT_URL` does not exist, the server MUST NOT respond -with `200 OK` response. A server SHOULD respond with -`404 Not Found`, `410 Gone`, or any other suitable HTTP status code -which does not imply the resource exists as requested. - -If there is a repository at `$GIT_URL`, but access is not currently -permitted, the server MUST respond with the `403 Forbidden` HTTP -status code. - -Servers SHOULD support both HTTP 1.0 and HTTP 1.1. -Servers SHOULD support chunked encoding for both request and response -bodies. - -Clients SHOULD support both HTTP 1.0 and HTTP 1.1. -Clients SHOULD support chunked encoding for both request and response -bodies. - -Servers MAY return ETag and/or Last-Modified headers. - -Clients MAY revalidate cached entities by including If-Modified-Since -and/or If-None-Match request headers. - -Servers MAY return `304 Not Modified` if the relevant headers appear -in the request and the entity has not changed. Clients MUST treat -`304 Not Modified` identical to `200 OK` by reusing the cached entity. - -Clients MAY reuse a cached entity without revalidation if the -Cache-Control and/or Expires header permits caching. Clients and -servers MUST follow RFC 2616 for cache controls. - - -Discovering References ----------------------- - -All HTTP clients MUST begin either a fetch or a push exchange by -discovering the references available on the remote repository. - -Dumb Clients -~~~~~~~~~~~~ - -HTTP clients that only support the "dumb" protocol MUST discover -references by making a request for the special info/refs file of -the repository. - -Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`, -without any search/query parameters. - - C: GET $GIT_URL/info/refs HTTP/1.0 - - S: 200 OK - S: - S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint - S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master - S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 - S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} - -The Content-Type of the returned info/refs entity SHOULD be -`text/plain; charset=utf-8`, but MAY be any content type. -Clients MUST NOT attempt to validate the returned Content-Type. -Dumb servers MUST NOT return a return type starting with -`application/x-git-`. - -Cache-Control headers MAY be returned to disable caching of the -returned entity. - -When examining the response clients SHOULD only examine the HTTP -status code. Valid responses are `200 OK`, or `304 Not Modified`. - -The returned content is a UNIX formatted text file describing -each ref and its known value. The file SHOULD be sorted by name -according to the C locale ordering. The file SHOULD NOT include -the default ref named `HEAD`. - - info_refs = *( ref_record ) - ref_record = any_ref / peeled_ref - - any_ref = obj-id HTAB refname LF - peeled_ref = obj-id HTAB refname LF - obj-id HTAB refname "^{}" LF - -Smart Clients -~~~~~~~~~~~~~ - -HTTP clients that support the "smart" protocol (or both the -"smart" and "dumb" protocols) MUST discover references by making -a parameterized request for the info/refs file of the repository. - -The request MUST contain exactly one query parameter, -`service=$servicename`, where `$servicename` MUST be the service -name the client wishes to contact to complete the operation. -The request MUST NOT contain additional query parameters. - - C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 - -dumb server reply: - - S: 200 OK - S: - S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint - S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master - S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 - S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} - -smart server reply: - - S: 200 OK - S: Content-Type: application/x-git-upload-pack-advertisement - S: Cache-Control: no-cache - S: - S: 001e# service=git-upload-pack\n - S: 0000 - S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n - S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n - S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n - S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n - S: 0000 - -The client may send Extra Parameters (see -linkgit:gitprotocol-pack[5]) as a colon-separated string -in the Git-Protocol HTTP header. - -Uses the `--http-backend-info-refs` option to -linkgit:git-upload-pack[1]. - -Dumb Server Response -^^^^^^^^^^^^^^^^^^^^ -Dumb servers MUST respond with the dumb server reply format. - -See the prior section under dumb clients for a more detailed -description of the dumb server response. - -Smart Server Response -^^^^^^^^^^^^^^^^^^^^^ -If the server does not recognize the requested service name, or the -requested service name has been disabled by the server administrator, -the server MUST respond with the `403 Forbidden` HTTP status code. - -Otherwise, smart servers MUST respond with the smart server reply -format for the requested service name. - -Cache-Control headers SHOULD be used to disable caching of the -returned entity. - -The Content-Type MUST be `application/x-$servicename-advertisement`. -Clients SHOULD fall back to the dumb protocol if another content -type is returned. When falling back to the dumb protocol clients -SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but -instead SHOULD use the response already in hand. Clients MUST NOT -continue if they do not support the dumb protocol. - -Clients MUST validate the status code is either `200 OK` or -`304 Not Modified`. - -Clients MUST validate the first five bytes of the response entity -matches the regex `^[0-9a-f]{4}#`. If this test fails, clients -MUST NOT continue. - -Clients MUST parse the entire response as a sequence of pkt-line -records. - -Clients MUST verify the first pkt-line is `# service=$servicename`. -Servers MUST set $servicename to be the request parameter value. -Servers SHOULD include an LF at the end of this line. -Clients MUST ignore an LF at the end of the line. - -Servers MUST terminate the response with the magic `0000` end -pkt-line marker. - -The returned response is a pkt-line stream describing each ref and -its known value. The stream SHOULD be sorted by name according to -the C locale ordering. The stream SHOULD include the default ref -named `HEAD` as the first ref. The stream MUST include capability -declarations behind a NUL on the first ref. - -The returned response contains "version 1" if "version=1" was sent as an -Extra Parameter. - - smart_reply = PKT-LINE("# service=$servicename" LF) - "0000" - *1("version 1") - ref_list - "0000" - ref_list = empty_list / non_empty_list - - empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF) - - non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF) - *ref_record - - cap-list = capability *(SP capability) - capability = 1*(LC_ALPHA / DIGIT / "-" / "_") - LC_ALPHA = %x61-7A - - ref_record = any_ref / peeled_ref - any_ref = PKT-LINE(obj-id SP name LF) - peeled_ref = PKT-LINE(obj-id SP name LF) - PKT-LINE(obj-id SP name "^{}" LF - - -Smart Service git-upload-pack ------------------------------- -This service reads from the repository pointed to by `$GIT_URL`. - -Clients MUST first perform ref discovery with -`$GIT_URL/info/refs?service=git-upload-pack`. - - C: POST $GIT_URL/git-upload-pack HTTP/1.0 - C: Content-Type: application/x-git-upload-pack-request - C: - C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n - C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n - C: 0000 - - S: 200 OK - S: Content-Type: application/x-git-upload-pack-result - S: Cache-Control: no-cache - S: - S: ....ACK %s, continue - S: ....NAK - -Clients MUST NOT reuse or revalidate a cached response. -Servers MUST include sufficient Cache-Control headers -to prevent caching of the response. - -Servers SHOULD support all capabilities defined here. - -Clients MUST send at least one "want" command in the request body. -Clients MUST NOT reference an id in a "want" command which did not -appear in the response obtained through ref discovery unless the -server advertises capability `allow-tip-sha1-in-want` or -`allow-reachable-sha1-in-want`. - - compute_request = want_list - have_list - request_end - request_end = "0000" / "done" - - want_list = PKT-LINE(want SP cap_list LF) - *(want_pkt) - want_pkt = PKT-LINE(want LF) - want = "want" SP id - cap_list = capability *(SP capability) - - have_list = *PKT-LINE("have" SP id LF) - -TODO: Document this further. - -The Negotiation Algorithm -~~~~~~~~~~~~~~~~~~~~~~~~~ -The computation to select the minimal pack proceeds as follows -(C = client, S = server): - -'init step:' - -C: Use ref discovery to obtain the advertised refs. - -C: Place any object seen into set `advertised`. - -C: Build an empty set, `common`, to hold the objects that are later - determined to be on both ends. - -C: Build a set, `want`, of the objects from `advertised` the client - wants to fetch, based on what it saw during ref discovery. - -C: Start a queue, `c_pending`, ordered by commit time (popping newest - first). Add all client refs. When a commit is popped from - the queue its parents SHOULD be automatically inserted back. - Commits MUST only enter the queue once. - -'one compute step:' - -C: Send one `$GIT_URL/git-upload-pack` request: - - C: 0032want ............................... - C: 0032want ............................... - .... - C: 0032have ............................. - C: 0032have ............................. - .... - C: 0032have ............................... - C: 0032have ............................... - .... - C: 0000 - -The stream is organized into "commands", with each command -appearing by itself in a pkt-line. Within a command line, -the text leading up to the first space is the command name, -and the remainder of the line to the first LF is the value. -Command lines are terminated with an LF as the last byte of -the pkt-line value. - -Commands MUST appear in the following order, if they appear -at all in the request stream: - -* "want" -* "have" - -The stream is terminated by a pkt-line flush (`0000`). - -A single "want" or "have" command MUST have one hex formatted -object name as its value. Multiple object names MUST be sent by sending -multiple commands. Object names MUST be given using the object format -negotiated through the `object-format` capability (default SHA-1). - -The `have` list is created by popping the first 32 commits -from `c_pending`. Less can be supplied if `c_pending` empties. - -If the client has sent 256 "have" commits and has not yet -received one of those back from `s_common`, or the client has -emptied `c_pending` it SHOULD include a "done" command to let -the server know it won't proceed: - - C: 0009done - -S: Parse the git-upload-pack request: - -Verify all objects in `want` are directly reachable from refs. - -The server MAY walk backwards through history or through -the reflog to permit slightly stale requests. - -If no "want" objects are received, send an error: -TODO: Define error if no "want" lines are requested. - -If any "want" object is not reachable, send an error: -TODO: Define error if an invalid "want" is requested. - -Create an empty list, `s_common`. - -If "have" was sent: - -Loop through the objects in the order supplied by the client. - -For each object, if the server has the object reachable from -a ref, add it to `s_common`. If a commit is added to `s_common`, -do not add any ancestors, even if they also appear in `have`. - -S: Send the git-upload-pack response: - -If the server has found a closed set of objects to pack or the -request ends with "done", it replies with the pack. -TODO: Document the pack based response - - S: PACK... - -The returned stream is the side-band-64k protocol supported -by the git-upload-pack service, and the pack is embedded into -stream 1. Progress messages from the server side MAY appear -in stream 2. - -Here a "closed set of objects" is defined to have at least -one path from every "want" to at least one "common" object. - -If the server needs more information, it replies with a -status continue response: -TODO: Document the non-pack response - -C: Parse the upload-pack response: - TODO: Document parsing response - -'Do another compute step.' - - -Smart Service git-receive-pack ------------------------------- -This service reads from the repository pointed to by `$GIT_URL`. - -Clients MUST first perform ref discovery with -`$GIT_URL/info/refs?service=git-receive-pack`. - - C: POST $GIT_URL/git-receive-pack HTTP/1.0 - C: Content-Type: application/x-git-receive-pack-request - C: - C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status - C: 0000 - C: PACK.... - - S: 200 OK - S: Content-Type: application/x-git-receive-pack-result - S: Cache-Control: no-cache - S: - S: .... - -Clients MUST NOT reuse or revalidate a cached response. -Servers MUST include sufficient Cache-Control headers -to prevent caching of the response. - -Servers SHOULD support all capabilities defined here. - -Clients MUST send at least one command in the request body. -Within the command portion of the request body clients SHOULD send -the id obtained through ref discovery as old_id. - - update_request = command_list - "PACK" - - command_list = PKT-LINE(command NUL cap_list LF) - *(command_pkt) - command_pkt = PKT-LINE(command LF) - cap_list = *(SP capability) SP - - command = create / delete / update - create = zero-id SP new_id SP name - delete = old_id SP zero-id SP name - update = old_id SP new_id SP name - -TODO: Document this further. - - -References ----------- - -http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] -http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] -linkgit:gitprotocol-pack[5] -linkgit:gitprotocol-capabilities[5] diff --git a/command-list.txt b/command-list.txt index 5394eefb6e..f96bdabd7d 100644 --- a/command-list.txt +++ b/command-list.txt @@ -224,6 +224,7 @@ gitmodules userinterfaces gitnamespaces guide gitprotocol-capabilities developerinterfaces gitprotocol-common developerinterfaces +gitprotocol-http developerinterfaces gitprotocol-pack developerinterfaces gitprotocol-v2 developerinterfaces gitremote-helpers guide -- cgit v1.2.3