{"thread":{"id":"35734","subject":"[PATCH v2 0/2] create HTML for http-protocol.txt","startedAt":"2014-01-26T12:52:03Z","lastAt":"2014-01-26T13:01:05Z","messageCount":5,"participants":["Thomas Ackermann"],"isPatch":true,"patchVersion":2,"patchTotal":2},"messages":[{"id":"233764","messageId":"735028458.1102653.1390740723616.JavaMail.ngmail@webmail18.arcor-online.net","threadId":"35734","inReplyTo":null,"subject":"[PATCH v2 0/2] create HTML for http-protocol.txt","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2014-01-26T12:52:03Z","receivedAt":"2014-01-26T12:52:03Z","isPatch":true,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":"\nThis is a reroll of my attempt to create usable HTML for http-protocol.txt.\n\nThe first patch addresses Junio's remarks regarding the conversion to better ASCIIDOC.\nThe patch contains some whitespace-only changes so these shouldn't be ignored while applying.\n\nThe second patch tries to fix one of the TODOs the original author has put into the document.\n\n\n---\nThomas\n"},{"id":"233765","messageId":"251995526.1102678.1390740898917.JavaMail.ngmail@webmail18.arcor-online.net","threadId":"35734","inReplyTo":"735028458.1102653.1390740723616.JavaMail.ngmail@webmail18.arcor-online.net","subject":"[PATCH 1/2] create HTML for http-protocol.txt","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2014-01-26T12:54:58Z","receivedAt":"2014-01-26T12:54:58Z","isPatch":true,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":"[PATCH 1/2] create HTML for http-protocol.txt\n\n./Documentation/technical/http-protocol.txt was missing from TECH_DOCS in Makefile.\nAdd it and also improve HTML formatting while still retaining good readability of the ASCII text:\n- Use monospace font instead of italicized or roman font for machine output and source text\n- Use roman font for things which should be body text\n- Use double quotes consistently for \"want\" and \"have\" commands\n- Use uppercase \"C\" / \"S\" consistently for \"client\" / \"server\";\n  also use \"C:\" / \"S:\" instead of \"(C)\" / \"(S)\" for consistency and\n  to avoid having formatted \"(C)\" as copyright symbol in HTML\n- Use only spaces and not a combination of tabs and spaces for whitespace\n\nSigned-off-by: Thomas Ackermann <th.acker@arcor.de>\n---\n Documentation/Makefile                    |   3 +-\n Documentation/technical/http-protocol.txt | 232 +++++++++++++++---------------\n 2 files changed, 120 insertions(+), 115 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 36c58fc..b19d52a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \n-TECH_DOCS = technical/index-format\n+TECH_DOCS = technical/http-protocol\n+TECH_DOCS += technical/index-format\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/pack-protocol\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex d21d77d..7f0cf0b 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form:\n \n   http://<host>:<port>/<path>?<searchpart>\n \n-Within this documentation the placeholder $GIT_URL will stand for\n+Within this documentation the placeholder `$GIT_URL` will stand for\n the http:// repository URL entered by the end-user.\n \n-Servers SHOULD handle all requests to locations matching $GIT_URL, as\n+Servers SHOULD handle all requests to locations matching `$GIT_URL`, as\n both the \"smart\" and \"dumb\" HTTP protocols used by Git operate\n by appending additional path components onto the end of the user\n-supplied $GIT_URL string.\n+supplied `$GIT_URL` string.\n \n An example of a dumb client requesting for a loose object:\n \n@@ -43,10 +43,10 @@ An example of a request to a submodule:\n   $GIT_URL:     http://example.com/git/repo.git/path/submodule.git\n   URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs\n \n-Clients MUST strip a trailing '/', if present, from the user supplied\n-$GIT_URL string to prevent empty path tokens ('//') from appearing\n+Clients MUST strip a trailing `/`, if present, from the user supplied\n+`$GIT_URL` string to prevent empty path tokens (`//`) from appearing\n in any URL sent to a server.  Compatible clients MUST expand\n-'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.\n+`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.\n \n \n Authentication\n@@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed\n by both client and server.  This includes (but is not necessarily\n limited to):\n \n-If there is no repository at $GIT_URL, or the resource pointed to by a\n-location matching $GIT_URL does not exist, the server MUST NOT respond\n-with '200 OK' response.  A server SHOULD respond with\n-'404 Not Found', '410 Gone', or any other suitable HTTP status code\n+If there is no repository at `$GIT_URL`, or the resource pointed to by a\n+location matching `$GIT_URL` does not exist, the server MUST NOT respond\n+with `200 OK` response.  A server SHOULD respond with\n+`404 Not Found`, `410 Gone`, or any other suitable HTTP status code\n which does not imply the resource exists as requested.\n \n-If there is a repository at $GIT_URL, but access is not currently\n-permitted, the server MUST respond with the '403 Forbidden' HTTP\n+If there is a repository at `$GIT_URL`, but access is not currently\n+permitted, the server MUST respond with the `403 Forbidden` HTTP\n status code.\n \n Servers SHOULD support both HTTP 1.0 and HTTP 1.1.\n@@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.\n Clients MAY revalidate cached entities by including If-Modified-Since\n and/or If-None-Match request headers.\n \n-Servers MAY return '304 Not Modified' if the relevant headers appear\n+Servers MAY return `304 Not Modified` if the relevant headers appear\n in the request and the entity has not changed.  Clients MUST treat\n-'304 Not Modified' identical to '200 OK' by reusing the cached entity.\n+`304 Not Modified` identical to `200 OK` by reusing the cached entity.\n \n Clients MAY reuse a cached entity without revalidation if the\n Cache-Control and/or Expires header permits caching.  Clients and\n@@ -148,7 +148,7 @@ HTTP clients that only support the \"dumb\" protocol MUST discover\n references by making a request for the special info/refs file of\n the repository.\n \n-Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,\n+Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,\n without any search/query parameters.\n \n    C: GET $GIT_URL/info/refs HTTP/1.0\n@@ -161,28 +161,28 @@ without any search/query parameters.\n    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n \n The Content-Type of the returned info/refs entity SHOULD be\n-\"text/plain; charset=utf-8\", but MAY be any content type.\n+`text/plain; charset=utf-8`, but MAY be any content type.\n Clients MUST NOT attempt to validate the returned Content-Type.\n Dumb servers MUST NOT return a return type starting with\n-\"application/x-git-\".\n+`application/x-git-`.\n \n Cache-Control headers MAY be returned to disable caching of the\n returned entity.\n \n When examining the response clients SHOULD only examine the HTTP\n-status code.  Valid responses are '200 OK', or '304 Not Modified'.\n+status code.  Valid responses are `200 OK`, or `304 Not Modified`.\n \n The returned content is a UNIX formatted text file describing\n each ref and its known value.  The file SHOULD be sorted by name\n according to the C locale ordering.  The file SHOULD NOT include\n-the default ref named 'HEAD'.\n+the default ref named `HEAD`.\n \n   info_refs   =  *( ref_record )\n   ref_record  =  any_ref / peeled_ref\n \n   any_ref     =  obj-id HTAB refname LF\n   peeled_ref  =  obj-id HTAB refname LF\n-\t\t obj-id HTAB refname \"^{}\" LF\n+                 obj-id HTAB refname \"^{}\" LF\n \n Smart Clients\n ~~~~~~~~~~~~~\n@@ -192,13 +192,14 @@ HTTP clients that support the \"smart\" protocol (or both the\n a parameterized request for the info/refs file of the repository.\n \n The request MUST contain exactly one query parameter,\n-'service=$servicename', where $servicename MUST be the service\n+`service=$servicename`, where `$servicename` MUST be the service\n name the client wishes to contact to complete the operation.\n The request MUST NOT contain additional query parameters.\n \n    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\n \n-   dumb server reply:\n+dumb server reply:\n+\n    S: 200 OK\n    S:\n    S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31\trefs/heads/maint\n@@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters.\n    S: 2cb58b79488a98d2721cea644875a8dd0026b115\trefs/tags/v1.0\n    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n \n-   smart server reply:\n+smart server reply:\n+\n    S: 200 OK\n    S: Content-Type: application/x-git-upload-pack-advertisement\n    S: Cache-Control: no-cache\n@@ -228,7 +230,7 @@ Smart Server Response\n ^^^^^^^^^^^^^^^^^^^^^\n If the server does not recognize the requested service name, or the\n requested service name has been disabled by the server administrator,\n-the server MUST respond with the '403 Forbidden' HTTP status code.\n+the server MUST respond with the `403 Forbidden` HTTP status code.\n \n Otherwise, smart servers MUST respond with the smart server reply\n format for the requested service name.\n@@ -236,46 +238,46 @@ format for the requested service name.\n Cache-Control headers SHOULD be used to disable caching of the\n returned entity.\n \n-The Content-Type MUST be 'application/x-$servicename-advertisement'.\n+The Content-Type MUST be `application/x-$servicename-advertisement`.\n Clients SHOULD fall back to the dumb protocol if another content\n type is returned.  When falling back to the dumb protocol clients\n-SHOULD NOT make an additional request to $GIT_URL/info/refs, but\n+SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but\n instead SHOULD use the response already in hand.  Clients MUST NOT\n continue if they do not support the dumb protocol.\n \n-Clients MUST validate the status code is either '200 OK' or\n-'304 Not Modified'.\n+Clients MUST validate the status code is either `200 OK` or\n+`304 Not Modified`.\n \n Clients MUST validate the first five bytes of the response entity\n-matches the regex \"^[0-9a-f]{4}#\".  If this test fails, clients\n+matches the regex `^[0-9a-f]{4}#`.  If this test fails, clients\n MUST NOT continue.\n \n Clients MUST parse the entire response as a sequence of pkt-line\n records.\n \n-Clients MUST verify the first pkt-line is \"# service=$servicename\".\n+Clients MUST verify the first pkt-line is `# service=$servicename`.\n Servers MUST set $servicename to be the request parameter value.\n Servers SHOULD include an LF at the end of this line.\n Clients MUST ignore an LF at the end of the line.\n \n-Servers MUST terminate the response with the magic \"0000\" end\n+Servers MUST terminate the response with the magic `0000` end\n pkt-line marker.\n \n The returned response is a pkt-line stream describing each ref and\n its known value.  The stream SHOULD be sorted by name according to\n the C locale ordering.  The stream SHOULD include the default ref\n-named 'HEAD' as the first ref.  The stream MUST include capability\n+named `HEAD` as the first ref.  The stream MUST include capability\n declarations behind a NUL on the first ref.\n \n   smart_reply     =  PKT-LINE(\"# service=$servicename\" LF)\n-\t\t     ref_list\n-\t\t     \"0000\"\n+                     ref_list\n+                     \"0000\"\n   ref_list        =  empty_list / non_empty_list\n \n   empty_list      =  PKT-LINE(zero-id SP \"capabilities^{}\" NUL cap-list LF)\n \n   non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)\n-\t\t     *ref_record\n+                     *ref_record\n \n   cap-list        =  capability *(SP capability)\n   capability      =  1*(LC_ALPHA / DIGIT / \"-\" / \"_\")\n@@ -284,14 +286,15 @@ declarations behind a NUL on the first ref.\n   ref_record      =  any_ref / peeled_ref\n   any_ref         =  PKT-LINE(obj-id SP name LF)\n   peeled_ref      =  PKT-LINE(obj-id SP name LF)\n-\t\t     PKT-LINE(obj-id SP name \"^{}\" LF\n+                     PKT-LINE(obj-id SP name \"^{}\" LF\n+\n \n Smart Service git-upload-pack\n ------------------------------\n-This service reads from the repository pointed to by $GIT_URL.\n+This service reads from the repository pointed to by `$GIT_URL`.\n \n Clients MUST first perform ref discovery with\n-'$GIT_URL/info/refs?service=git-upload-pack'.\n+`$GIT_URL/info/refs?service=git-upload-pack`.\n \n    C: POST $GIT_URL/git-upload-pack HTTP/1.0\n    C: Content-Type: application/x-git-upload-pack-request\n@@ -313,18 +316,18 @@ to prevent caching of the response.\n \n Servers SHOULD support all capabilities defined here.\n \n-Clients MUST send at least one 'want' command in the request body.\n-Clients MUST NOT reference an id in a 'want' command which did not\n+Clients MUST send at least one \"want\" command in the request body.\n+Clients MUST NOT reference an id in a \"want\" command which did not\n appear in the response obtained through ref discovery unless the\n-server advertises capability \"allow-tip-sha1-in-want\".\n+server advertises capability `allow-tip-sha1-in-want`.\n \n   compute_request   =  want_list\n-\t\t       have_list\n-\t\t       request_end\n+                       have_list\n+                       request_end\n   request_end       =  \"0000\" / \"done\"\n \n   want_list         =  PKT-LINE(want NUL cap_list LF)\n-\t\t       *(want_pkt)\n+                       *(want_pkt)\n   want_pkt          =  PKT-LINE(want LF)\n   want              =  \"want\" SP id\n   cap_list          =  *(SP capability) SP\n@@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.\n The Negotiation Algorithm\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n The computation to select the minimal pack proceeds as follows\n-(c = client, s = server):\n+(C = client, S = server):\n+\n+'init step:'\n+\n+C: Use ref discovery to obtain the advertised refs.\n+\n+C: Place any object seen into set ADVERTISED.\n \n- init step:\n- (c) Use ref discovery to obtain the advertised refs.\n- (c) Place any object seen into set ADVERTISED.\n+C: Build an empty set, COMMON, to hold the objects that are later\n+   determined to be on both ends.\n \n- (c) Build an empty set, COMMON, to hold the objects that are later\n-     determined to be on both ends.\n- (c) Build a set, WANT, of the objects from ADVERTISED the client\n-     wants to fetch, based on what it saw during ref discovery.\n+C: Build a set, WANT, of the objects from ADVERTISED the client\n+   wants to fetch, based on what it saw during ref discovery.\n \n- (c) Start a queue, C_PENDING, ordered by commit time (popping newest\n-     first).  Add all client refs.  When a commit is popped from\n-     the queue its parents SHOULD be automatically inserted back.\n-     Commits MUST only enter the queue once.\n+C: Start a queue, C_PENDING, ordered by commit time (popping newest\n+   first).  Add all client refs.  When a commit is popped from\n+   the queue its parents SHOULD be automatically inserted back.\n+   Commits MUST only enter the queue once.\n \n- one compute step:\n- (c) Send one $GIT_URL/git-upload-pack request:\n+'one compute step:'\n+\n+C: Send one `$GIT_URL/git-upload-pack` request:\n \n    C: 0032want <WANT #1>...............................\n    C: 0032want <WANT #2>...............................\n@@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as follows\n    ....\n    C: 0000\n \n-     The stream is organized into \"commands\", with each command\n-     appearing by itself in a pkt-line.  Within a command line\n-     the text leading up to the first space is the command name,\n-     and the remainder of the line to the first LF is the value.\n-     Command lines are terminated with an LF as the last byte of\n-     the pkt-line value.\n+The stream is organized into \"commands\", with each command\n+appearing by itself in a pkt-line.  Within a command line\n+the text leading up to the first space is the command name,\n+and the remainder of the line to the first LF is the value.\n+Command lines are terminated with an LF as the last byte of\n+the pkt-line value.\n \n-     Commands MUST appear in the following order, if they appear\n-     at all in the request stream:\n+Commands MUST appear in the following order, if they appear\n+at all in the request stream:\n \n-       * want\n-       * have\n+* \"want\"\n+* \"have\"\n \n-     The stream is terminated by a pkt-line flush (\"0000\").\n+The stream is terminated by a pkt-line flush (`0000`).\n \n-     A single \"want\" or \"have\" command MUST have one hex formatted\n-     SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n-     multiple commands.\n+A single \"want\" or \"have\" command MUST have one hex formatted\n+SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n+multiple commands.\n \n-     The HAVE list is created by popping the first 32 commits\n-     from C_PENDING.  Less can be supplied if C_PENDING empties.\n+The HAVE list is created by popping the first 32 commits\n+from C_PENDING.  Less can be supplied if C_PENDING empties.\n \n-     If the client has sent 256 HAVE commits and has not yet\n-     received one of those back from S_COMMON, or the client has\n-     emptied C_PENDING it SHOULD include a \"done\" command to let\n-     the server know it won't proceed:\n+If the client has sent 256 HAVE commits and has not yet\n+received one of those back from S_COMMON, or the client has\n+emptied C_PENDING it SHOULD include a \"done\" command to let\n+the server know it won't proceed:\n \n    C: 0009done\n \n-  (s) Parse the git-upload-pack request:\n-\n-      Verify all objects in WANT are directly reachable from refs.\n-\n-      The server MAY walk backwards through history or through\n-      the reflog to permit slightly stale requests.\n+S: Parse the git-upload-pack request:\n \n-      If no WANT objects are received, send an error:\n+Verify all objects in WANT are directly reachable from refs.\n \n-TODO: Define error if no want lines are requested.\n+The server MAY walk backwards through history or through\n+the reflog to permit slightly stale requests.\n \n-      If any WANT object is not reachable, send an error:\n+If no WANT objects are received, send an error:\n+TODO: Define error if no \"want\" lines are requested.\n \n-TODO: Define error if an invalid want is requested.\n+If any WANT object is not reachable, send an error:\n+TODO: Define error if an invalid \"want\" is requested.\n \n-     Create an empty list, S_COMMON.\n+Create an empty list, S_COMMON.\n \n-     If 'have' was sent:\n+If \"have\" was sent:\n \n-     Loop through the objects in the order supplied by the client.\n-     For each object, if the server has the object reachable from\n-     a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n-     do not add any ancestors, even if they also appear in HAVE.\n+Loop through the objects in the order supplied by the client.\n \n-  (s) Send the git-upload-pack response:\n+For each object, if the server has the object reachable from\n+a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n+do not add any ancestors, even if they also appear in HAVE.\n \n-     If the server has found a closed set of objects to pack or the\n-     request ends with \"done\", it replies with the pack.\n+S: Send the git-upload-pack response:\n \n+If the server has found a closed set of objects to pack or the\n+request ends with \"done\", it replies with the pack.\n TODO: Document the pack based response\n-   S: PACK...\n \n-     The returned stream is the side-band-64k protocol supported\n-     by the git-upload-pack service, and the pack is embedded into\n-     stream 1.  Progress messages from the server side MAY appear\n-     in stream 2.\n+   S: PACK...\n \n-     Here a \"closed set of objects\" is defined to have at least\n-     one path from every WANT to at least one COMMON object.\n+The returned stream is the side-band-64k protocol supported\n+by the git-upload-pack service, and the pack is embedded into\n+stream 1.  Progress messages from the server side MAY appear\n+in stream 2.\n \n-     If the server needs more information, it replies with a\n-     status continue response:\n+Here a \"closed set of objects\" is defined to have at least\n+one path from every WANT to at least one COMMON object.\n \n+If the server needs more information, it replies with a\n+status continue response:\n TODO: Document the non-pack response\n \n-  (c) Parse the upload-pack response:\n-\n-TODO: Document parsing response\n+C: Parse the upload-pack response:\n+   TODO: Document parsing response\n \n-      Do another compute step.\n+'Do another compute step.'\n \n \n Smart Service git-receive-pack\n ------------------------------\n-This service reads from the repository pointed to by $GIT_URL.\n+This service reads from the repository pointed to by `$GIT_URL`.\n \n Clients MUST first perform ref discovery with\n-'$GIT_URL/info/refs?service=git-receive-pack'.\n+`$GIT_URL/info/refs?service=git-receive-pack`.\n \n    C: POST $GIT_URL/git-receive-pack HTTP/1.0\n    C: Content-Type: application/x-git-receive-pack-request\n@@ -479,10 +483,10 @@ Within the command portion of the request body clients SHOULD send\n the id obtained through ref discovery as old_id.\n \n   update_request  =  command_list\n-\t\t     \"PACK\" <binary data>\n+                     \"PACK\" <binary data>\n \n   command_list    =  PKT-LINE(command NUL cap_list LF)\n-\t\t     *(command_pkt)\n+                     *(command_pkt)\n   command_pkt     =  PKT-LINE(command LF)\n   cap_list        =  *(SP capability) SP\n \n-- \n1.8.5.2.msysgit.0\n\n\n\n---\nThomas\n"},{"id":"233766","messageId":"1554188039.1102690.1390740977023.JavaMail.ngmail@webmail18.arcor-online.net","threadId":"35734","inReplyTo":"735028458.1102653.1390740723616.JavaMail.ngmail@webmail18.arcor-online.net","subject":"[PATCH 2/2] http-protocol.txt: don't use uppercase for variable names in \"The Negotiation Algorithm\"","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2014-01-26T12:56:17Z","receivedAt":"2014-01-26T12:56:17Z","isPatch":true,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":"\nSigned-off-by: Thomas Ackermann <th.acker@arcor.de>\n---\n Documentation/technical/http-protocol.txt | 45 +++++++++++++++----------------\n 1 file changed, 22 insertions(+), 23 deletions(-)\n\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex 7f0cf0b..90beb32 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -335,7 +335,6 @@ server advertises capability `allow-tip-sha1-in-want`.\n   have_list         =  *PKT-LINE(\"have\" SP id LF)\n \n TODO: Document this further.\n-TODO: Don't use uppercase for variable names below.\n \n The Negotiation Algorithm\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -346,15 +345,15 @@ The computation to select the minimal pack proceeds as follows\n \n C: Use ref discovery to obtain the advertised refs.\n \n-C: Place any object seen into set ADVERTISED.\n+C: Place any object seen into set `advertised`.\n \n-C: Build an empty set, COMMON, to hold the objects that are later\n+C: Build an empty set, `common`, to hold the objects that are later\n    determined to be on both ends.\n \n-C: Build a set, WANT, of the objects from ADVERTISED the client\n+C: Build a set, `want`, of the objects from `advertised` the client\n    wants to fetch, based on what it saw during ref discovery.\n \n-C: Start a queue, C_PENDING, ordered by commit time (popping newest\n+C: Start a queue, `c_pending`, ordered by commit time (popping newest\n    first).  Add all client refs.  When a commit is popped from\n    the queue its parents SHOULD be automatically inserted back.\n    Commits MUST only enter the queue once.\n@@ -363,14 +362,14 @@ C: Start a queue, C_PENDING, ordered by commit time (popping newest\n \n C: Send one `$GIT_URL/git-upload-pack` request:\n \n-   C: 0032want <WANT #1>...............................\n-   C: 0032want <WANT #2>...............................\n+   C: 0032want <want #1>...............................\n+   C: 0032want <want #2>...............................\n    ....\n-   C: 0032have <COMMON #1>.............................\n-   C: 0032have <COMMON #2>.............................\n+   C: 0032have <common #1>.............................\n+   C: 0032have <common #2>.............................\n    ....\n-   C: 0032have <HAVE #1>...............................\n-   C: 0032have <HAVE #2>...............................\n+   C: 0032have <have #1>...............................\n+   C: 0032have <have #2>...............................\n    ....\n    C: 0000\n \n@@ -393,38 +392,38 @@ A single \"want\" or \"have\" command MUST have one hex formatted\n SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n multiple commands.\n \n-The HAVE list is created by popping the first 32 commits\n-from C_PENDING.  Less can be supplied if C_PENDING empties.\n+The `have` list is created by popping the first 32 commits\n+from `c_pending`.  Less can be supplied if `c_pending` empties.\n \n-If the client has sent 256 HAVE commits and has not yet\n-received one of those back from S_COMMON, or the client has\n-emptied C_PENDING it SHOULD include a \"done\" command to let\n+If the client has sent 256 \"have\" commits and has not yet\n+received one of those back from `s_common`, or the client has\n+emptied `c_pending` it SHOULD include a \"done\" command to let\n the server know it won't proceed:\n \n    C: 0009done\n \n S: Parse the git-upload-pack request:\n \n-Verify all objects in WANT are directly reachable from refs.\n+Verify all objects in `want` are directly reachable from refs.\n \n The server MAY walk backwards through history or through\n the reflog to permit slightly stale requests.\n \n-If no WANT objects are received, send an error:\n+If no \"want\" objects are received, send an error:\n TODO: Define error if no \"want\" lines are requested.\n \n-If any WANT object is not reachable, send an error:\n+If any \"want\" object is not reachable, send an error:\n TODO: Define error if an invalid \"want\" is requested.\n \n-Create an empty list, S_COMMON.\n+Create an empty list, `s_common`.\n \n If \"have\" was sent:\n \n Loop through the objects in the order supplied by the client.\n \n For each object, if the server has the object reachable from\n-a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n-do not add any ancestors, even if they also appear in HAVE.\n+a ref, add it to `s_common`.  If a commit is added to `s_common`,\n+do not add any ancestors, even if they also appear in `have`.\n \n S: Send the git-upload-pack response:\n \n@@ -440,7 +439,7 @@ stream 1.  Progress messages from the server side MAY appear\n in stream 2.\n \n Here a \"closed set of objects\" is defined to have at least\n-one path from every WANT to at least one COMMON object.\n+one path from every \"want\" to at least one \"common\" object.\n \n If the server needs more information, it replies with a\n status continue response:\n-- \n1.8.5.2.msysgit.0\n\n\n---\nThomas\n"},{"id":"233767","messageId":"1604478570.1102699.1390741039526.JavaMail.ngmail@webmail18.arcor-online.net","threadId":"35734","inReplyTo":"735028458.1102653.1390740723616.JavaMail.ngmail@webmail18.arcor-online.net","subject":"[PATCH 1/2] create HTML for http-protocol.txt","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2014-01-26T12:57:19Z","receivedAt":"2014-01-26T12:57:19Z","isPatch":true,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":"\n./Documentation/technical/http-protocol.txt was missing from TECH_DOCS in Makefile.\nAdd it and also improve HTML formatting while still retaining good readability of the ASCII text:\n- Use monospace font instead of italicized or roman font for machine output and source text\n- Use roman font for things which should be body text\n- Use double quotes consistently for \"want\" and \"have\" commands\n- Use uppercase \"C\" / \"S\" consistently for \"client\" / \"server\";\n  also use \"C:\" / \"S:\" instead of \"(C)\" / \"(S)\" for consistency and\n  to avoid having formatted \"(C)\" as copyright symbol in HTML\n- Use only spaces and not a combination of tabs and spaces for whitespace\n\nSigned-off-by: Thomas Ackermann <th.acker@arcor.de>\n---\n Documentation/Makefile                    |   3 +-\n Documentation/technical/http-protocol.txt | 232 +++++++++++++++---------------\n 2 files changed, 120 insertions(+), 115 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 36c58fc..b19d52a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \n-TECH_DOCS = technical/index-format\n+TECH_DOCS = technical/http-protocol\n+TECH_DOCS += technical/index-format\n TECH_DOCS += technical/pack-format\n TECH_DOCS += technical/pack-heuristics\n TECH_DOCS += technical/pack-protocol\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex d21d77d..7f0cf0b 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form:\n \n   http://<host>:<port>/<path>?<searchpart>\n \n-Within this documentation the placeholder $GIT_URL will stand for\n+Within this documentation the placeholder `$GIT_URL` will stand for\n the http:// repository URL entered by the end-user.\n \n-Servers SHOULD handle all requests to locations matching $GIT_URL, as\n+Servers SHOULD handle all requests to locations matching `$GIT_URL`, as\n both the \"smart\" and \"dumb\" HTTP protocols used by Git operate\n by appending additional path components onto the end of the user\n-supplied $GIT_URL string.\n+supplied `$GIT_URL` string.\n \n An example of a dumb client requesting for a loose object:\n \n@@ -43,10 +43,10 @@ An example of a request to a submodule:\n   $GIT_URL:     http://example.com/git/repo.git/path/submodule.git\n   URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs\n \n-Clients MUST strip a trailing '/', if present, from the user supplied\n-$GIT_URL string to prevent empty path tokens ('//') from appearing\n+Clients MUST strip a trailing `/`, if present, from the user supplied\n+`$GIT_URL` string to prevent empty path tokens (`//`) from appearing\n in any URL sent to a server.  Compatible clients MUST expand\n-'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.\n+`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.\n \n \n Authentication\n@@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed\n by both client and server.  This includes (but is not necessarily\n limited to):\n \n-If there is no repository at $GIT_URL, or the resource pointed to by a\n-location matching $GIT_URL does not exist, the server MUST NOT respond\n-with '200 OK' response.  A server SHOULD respond with\n-'404 Not Found', '410 Gone', or any other suitable HTTP status code\n+If there is no repository at `$GIT_URL`, or the resource pointed to by a\n+location matching `$GIT_URL` does not exist, the server MUST NOT respond\n+with `200 OK` response.  A server SHOULD respond with\n+`404 Not Found`, `410 Gone`, or any other suitable HTTP status code\n which does not imply the resource exists as requested.\n \n-If there is a repository at $GIT_URL, but access is not currently\n-permitted, the server MUST respond with the '403 Forbidden' HTTP\n+If there is a repository at `$GIT_URL`, but access is not currently\n+permitted, the server MUST respond with the `403 Forbidden` HTTP\n status code.\n \n Servers SHOULD support both HTTP 1.0 and HTTP 1.1.\n@@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.\n Clients MAY revalidate cached entities by including If-Modified-Since\n and/or If-None-Match request headers.\n \n-Servers MAY return '304 Not Modified' if the relevant headers appear\n+Servers MAY return `304 Not Modified` if the relevant headers appear\n in the request and the entity has not changed.  Clients MUST treat\n-'304 Not Modified' identical to '200 OK' by reusing the cached entity.\n+`304 Not Modified` identical to `200 OK` by reusing the cached entity.\n \n Clients MAY reuse a cached entity without revalidation if the\n Cache-Control and/or Expires header permits caching.  Clients and\n@@ -148,7 +148,7 @@ HTTP clients that only support the \"dumb\" protocol MUST discover\n references by making a request for the special info/refs file of\n the repository.\n \n-Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,\n+Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,\n without any search/query parameters.\n \n    C: GET $GIT_URL/info/refs HTTP/1.0\n@@ -161,28 +161,28 @@ without any search/query parameters.\n    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n \n The Content-Type of the returned info/refs entity SHOULD be\n-\"text/plain; charset=utf-8\", but MAY be any content type.\n+`text/plain; charset=utf-8`, but MAY be any content type.\n Clients MUST NOT attempt to validate the returned Content-Type.\n Dumb servers MUST NOT return a return type starting with\n-\"application/x-git-\".\n+`application/x-git-`.\n \n Cache-Control headers MAY be returned to disable caching of the\n returned entity.\n \n When examining the response clients SHOULD only examine the HTTP\n-status code.  Valid responses are '200 OK', or '304 Not Modified'.\n+status code.  Valid responses are `200 OK`, or `304 Not Modified`.\n \n The returned content is a UNIX formatted text file describing\n each ref and its known value.  The file SHOULD be sorted by name\n according to the C locale ordering.  The file SHOULD NOT include\n-the default ref named 'HEAD'.\n+the default ref named `HEAD`.\n \n   info_refs   =  *( ref_record )\n   ref_record  =  any_ref / peeled_ref\n \n   any_ref     =  obj-id HTAB refname LF\n   peeled_ref  =  obj-id HTAB refname LF\n-\t\t obj-id HTAB refname \"^{}\" LF\n+                 obj-id HTAB refname \"^{}\" LF\n \n Smart Clients\n ~~~~~~~~~~~~~\n@@ -192,13 +192,14 @@ HTTP clients that support the \"smart\" protocol (or both the\n a parameterized request for the info/refs file of the repository.\n \n The request MUST contain exactly one query parameter,\n-'service=$servicename', where $servicename MUST be the service\n+`service=$servicename`, where `$servicename` MUST be the service\n name the client wishes to contact to complete the operation.\n The request MUST NOT contain additional query parameters.\n \n    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\n \n-   dumb server reply:\n+dumb server reply:\n+\n    S: 200 OK\n    S:\n    S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31\trefs/heads/maint\n@@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters.\n    S: 2cb58b79488a98d2721cea644875a8dd0026b115\trefs/tags/v1.0\n    S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n \n-   smart server reply:\n+smart server reply:\n+\n    S: 200 OK\n    S: Content-Type: application/x-git-upload-pack-advertisement\n    S: Cache-Control: no-cache\n@@ -228,7 +230,7 @@ Smart Server Response\n ^^^^^^^^^^^^^^^^^^^^^\n If the server does not recognize the requested service name, or the\n requested service name has been disabled by the server administrator,\n-the server MUST respond with the '403 Forbidden' HTTP status code.\n+the server MUST respond with the `403 Forbidden` HTTP status code.\n \n Otherwise, smart servers MUST respond with the smart server reply\n format for the requested service name.\n@@ -236,46 +238,46 @@ format for the requested service name.\n Cache-Control headers SHOULD be used to disable caching of the\n returned entity.\n \n-The Content-Type MUST be 'application/x-$servicename-advertisement'.\n+The Content-Type MUST be `application/x-$servicename-advertisement`.\n Clients SHOULD fall back to the dumb protocol if another content\n type is returned.  When falling back to the dumb protocol clients\n-SHOULD NOT make an additional request to $GIT_URL/info/refs, but\n+SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but\n instead SHOULD use the response already in hand.  Clients MUST NOT\n continue if they do not support the dumb protocol.\n \n-Clients MUST validate the status code is either '200 OK' or\n-'304 Not Modified'.\n+Clients MUST validate the status code is either `200 OK` or\n+`304 Not Modified`.\n \n Clients MUST validate the first five bytes of the response entity\n-matches the regex \"^[0-9a-f]{4}#\".  If this test fails, clients\n+matches the regex `^[0-9a-f]{4}#`.  If this test fails, clients\n MUST NOT continue.\n \n Clients MUST parse the entire response as a sequence of pkt-line\n records.\n \n-Clients MUST verify the first pkt-line is \"# service=$servicename\".\n+Clients MUST verify the first pkt-line is `# service=$servicename`.\n Servers MUST set $servicename to be the request parameter value.\n Servers SHOULD include an LF at the end of this line.\n Clients MUST ignore an LF at the end of the line.\n \n-Servers MUST terminate the response with the magic \"0000\" end\n+Servers MUST terminate the response with the magic `0000` end\n pkt-line marker.\n \n The returned response is a pkt-line stream describing each ref and\n its known value.  The stream SHOULD be sorted by name according to\n the C locale ordering.  The stream SHOULD include the default ref\n-named 'HEAD' as the first ref.  The stream MUST include capability\n+named `HEAD` as the first ref.  The stream MUST include capability\n declarations behind a NUL on the first ref.\n \n   smart_reply     =  PKT-LINE(\"# service=$servicename\" LF)\n-\t\t     ref_list\n-\t\t     \"0000\"\n+                     ref_list\n+                     \"0000\"\n   ref_list        =  empty_list / non_empty_list\n \n   empty_list      =  PKT-LINE(zero-id SP \"capabilities^{}\" NUL cap-list LF)\n \n   non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)\n-\t\t     *ref_record\n+                     *ref_record\n \n   cap-list        =  capability *(SP capability)\n   capability      =  1*(LC_ALPHA / DIGIT / \"-\" / \"_\")\n@@ -284,14 +286,15 @@ declarations behind a NUL on the first ref.\n   ref_record      =  any_ref / peeled_ref\n   any_ref         =  PKT-LINE(obj-id SP name LF)\n   peeled_ref      =  PKT-LINE(obj-id SP name LF)\n-\t\t     PKT-LINE(obj-id SP name \"^{}\" LF\n+                     PKT-LINE(obj-id SP name \"^{}\" LF\n+\n \n Smart Service git-upload-pack\n ------------------------------\n-This service reads from the repository pointed to by $GIT_URL.\n+This service reads from the repository pointed to by `$GIT_URL`.\n \n Clients MUST first perform ref discovery with\n-'$GIT_URL/info/refs?service=git-upload-pack'.\n+`$GIT_URL/info/refs?service=git-upload-pack`.\n \n    C: POST $GIT_URL/git-upload-pack HTTP/1.0\n    C: Content-Type: application/x-git-upload-pack-request\n@@ -313,18 +316,18 @@ to prevent caching of the response.\n \n Servers SHOULD support all capabilities defined here.\n \n-Clients MUST send at least one 'want' command in the request body.\n-Clients MUST NOT reference an id in a 'want' command which did not\n+Clients MUST send at least one \"want\" command in the request body.\n+Clients MUST NOT reference an id in a \"want\" command which did not\n appear in the response obtained through ref discovery unless the\n-server advertises capability \"allow-tip-sha1-in-want\".\n+server advertises capability `allow-tip-sha1-in-want`.\n \n   compute_request   =  want_list\n-\t\t       have_list\n-\t\t       request_end\n+                       have_list\n+                       request_end\n   request_end       =  \"0000\" / \"done\"\n \n   want_list         =  PKT-LINE(want NUL cap_list LF)\n-\t\t       *(want_pkt)\n+                       *(want_pkt)\n   want_pkt          =  PKT-LINE(want LF)\n   want              =  \"want\" SP id\n   cap_list          =  *(SP capability) SP\n@@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.\n The Negotiation Algorithm\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n The computation to select the minimal pack proceeds as follows\n-(c = client, s = server):\n+(C = client, S = server):\n+\n+'init step:'\n+\n+C: Use ref discovery to obtain the advertised refs.\n+\n+C: Place any object seen into set ADVERTISED.\n \n- init step:\n- (c) Use ref discovery to obtain the advertised refs.\n- (c) Place any object seen into set ADVERTISED.\n+C: Build an empty set, COMMON, to hold the objects that are later\n+   determined to be on both ends.\n \n- (c) Build an empty set, COMMON, to hold the objects that are later\n-     determined to be on both ends.\n- (c) Build a set, WANT, of the objects from ADVERTISED the client\n-     wants to fetch, based on what it saw during ref discovery.\n+C: Build a set, WANT, of the objects from ADVERTISED the client\n+   wants to fetch, based on what it saw during ref discovery.\n \n- (c) Start a queue, C_PENDING, ordered by commit time (popping newest\n-     first).  Add all client refs.  When a commit is popped from\n-     the queue its parents SHOULD be automatically inserted back.\n-     Commits MUST only enter the queue once.\n+C: Start a queue, C_PENDING, ordered by commit time (popping newest\n+   first).  Add all client refs.  When a commit is popped from\n+   the queue its parents SHOULD be automatically inserted back.\n+   Commits MUST only enter the queue once.\n \n- one compute step:\n- (c) Send one $GIT_URL/git-upload-pack request:\n+'one compute step:'\n+\n+C: Send one `$GIT_URL/git-upload-pack` request:\n \n    C: 0032want <WANT #1>...............................\n    C: 0032want <WANT #2>...............................\n@@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as follows\n    ....\n    C: 0000\n \n-     The stream is organized into \"commands\", with each command\n-     appearing by itself in a pkt-line.  Within a command line\n-     the text leading up to the first space is the command name,\n-     and the remainder of the line to the first LF is the value.\n-     Command lines are terminated with an LF as the last byte of\n-     the pkt-line value.\n+The stream is organized into \"commands\", with each command\n+appearing by itself in a pkt-line.  Within a command line\n+the text leading up to the first space is the command name,\n+and the remainder of the line to the first LF is the value.\n+Command lines are terminated with an LF as the last byte of\n+the pkt-line value.\n \n-     Commands MUST appear in the following order, if they appear\n-     at all in the request stream:\n+Commands MUST appear in the following order, if they appear\n+at all in the request stream:\n \n-       * want\n-       * have\n+* \"want\"\n+* \"have\"\n \n-     The stream is terminated by a pkt-line flush (\"0000\").\n+The stream is terminated by a pkt-line flush (`0000`).\n \n-     A single \"want\" or \"have\" command MUST have one hex formatted\n-     SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n-     multiple commands.\n+A single \"want\" or \"have\" command MUST have one hex formatted\n+SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n+multiple commands.\n \n-     The HAVE list is created by popping the first 32 commits\n-     from C_PENDING.  Less can be supplied if C_PENDING empties.\n+The HAVE list is created by popping the first 32 commits\n+from C_PENDING.  Less can be supplied if C_PENDING empties.\n \n-     If the client has sent 256 HAVE commits and has not yet\n-     received one of those back from S_COMMON, or the client has\n-     emptied C_PENDING it SHOULD include a \"done\" command to let\n-     the server know it won't proceed:\n+If the client has sent 256 HAVE commits and has not yet\n+received one of those back from S_COMMON, or the client has\n+emptied C_PENDING it SHOULD include a \"done\" command to let\n+the server know it won't proceed:\n \n    C: 0009done\n \n-  (s) Parse the git-upload-pack request:\n-\n-      Verify all objects in WANT are directly reachable from refs.\n-\n-      The server MAY walk backwards through history or through\n-      the reflog to permit slightly stale requests.\n+S: Parse the git-upload-pack request:\n \n-      If no WANT objects are received, send an error:\n+Verify all objects in WANT are directly reachable from refs.\n \n-TODO: Define error if no want lines are requested.\n+The server MAY walk backwards through history or through\n+the reflog to permit slightly stale requests.\n \n-      If any WANT object is not reachable, send an error:\n+If no WANT objects are received, send an error:\n+TODO: Define error if no \"want\" lines are requested.\n \n-TODO: Define error if an invalid want is requested.\n+If any WANT object is not reachable, send an error:\n+TODO: Define error if an invalid \"want\" is requested.\n \n-     Create an empty list, S_COMMON.\n+Create an empty list, S_COMMON.\n \n-     If 'have' was sent:\n+If \"have\" was sent:\n \n-     Loop through the objects in the order supplied by the client.\n-     For each object, if the server has the object reachable from\n-     a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n-     do not add any ancestors, even if they also appear in HAVE.\n+Loop through the objects in the order supplied by the client.\n \n-  (s) Send the git-upload-pack response:\n+For each object, if the server has the object reachable from\n+a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n+do not add any ancestors, even if they also appear in HAVE.\n \n-     If the server has found a closed set of objects to pack or the\n-     request ends with \"done\", it replies with the pack.\n+S: Send the git-upload-pack response:\n \n+If the server has found a closed set of objects to pack or the\n+request ends with \"done\", it replies with the pack.\n TODO: Document the pack based response\n-   S: PACK...\n \n-     The returned stream is the side-band-64k protocol supported\n-     by the git-upload-pack service, and the pack is embedded into\n-     stream 1.  Progress messages from the server side MAY appear\n-     in stream 2.\n+   S: PACK...\n \n-     Here a \"closed set of objects\" is defined to have at least\n-     one path from every WANT to at least one COMMON object.\n+The returned stream is the side-band-64k protocol supported\n+by the git-upload-pack service, and the pack is embedded into\n+stream 1.  Progress messages from the server side MAY appear\n+in stream 2.\n \n-     If the server needs more information, it replies with a\n-     status continue response:\n+Here a \"closed set of objects\" is defined to have at least\n+one path from every WANT to at least one COMMON object.\n \n+If the server needs more information, it replies with a\n+status continue response:\n TODO: Document the non-pack response\n \n-  (c) Parse the upload-pack response:\n-\n-TODO: Document parsing response\n+C: Parse the upload-pack response:\n+   TODO: Document parsing response\n \n-      Do another compute step.\n+'Do another compute step.'\n \n \n Smart Service git-receive-pack\n ------------------------------\n-This service reads from the repository pointed to by $GIT_URL.\n+This service reads from the repository pointed to by `$GIT_URL`.\n \n Clients MUST first perform ref discovery with\n-'$GIT_URL/info/refs?service=git-receive-pack'.\n+`$GIT_URL/info/refs?service=git-receive-pack`.\n \n    C: POST $GIT_URL/git-receive-pack HTTP/1.0\n    C: Content-Type: application/x-git-receive-pack-request\n@@ -479,10 +483,10 @@ Within the command portion of the request body clients SHOULD send\n the id obtained through ref discovery as old_id.\n \n   update_request  =  command_list\n-\t\t     \"PACK\" <binary data>\n+                     \"PACK\" <binary data>\n \n   command_list    =  PKT-LINE(command NUL cap_list LF)\n-\t\t     *(command_pkt)\n+                     *(command_pkt)\n   command_pkt     =  PKT-LINE(command LF)\n   cap_list        =  *(SP capability) SP\n \n-- \n1.8.5.2.msysgit.0\n\n\n---\nThomas\n"},{"id":"233768","messageId":"1512575333.1102049.1390741265687.JavaMail.ngmail@webmail13.arcor-online.net","threadId":"35734","inReplyTo":"251995526.1102678.1390740898917.JavaMail.ngmail@webmail18.arcor-online.net","subject":"Aw: [PATCH 1/2] create HTML for http-protocol.txt","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2014-01-26T13:01:05Z","receivedAt":"2014-01-26T13:01:05Z","isPatch":true,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":" \nplease ignore this one\n\n----- Original Nachricht ----\nVon:     Thomas Ackermann <th.acker@arcor.de>\nAn:      git@vger.kernel.org\nDatum:   26.01.2014 13:54\nBetreff: [PATCH 1/2] create HTML for http-protocol.txt\n\n> [PATCH 1/2] create HTML for http-protocol.txt\n> \n> ./Documentation/technical/http-protocol.txt was missing from TECH_DOCS in\n> Makefile.\n> Add it and also improve HTML formatting while still retaining good\n> readability of the ASCII text:\n> - Use monospace font instead of italicized or roman font for machine output\n> and source text\n> - Use roman font for things which should be body text\n> - Use double quotes consistently for \"want\" and \"have\" commands\n> - Use uppercase \"C\" / \"S\" consistently for \"client\" / \"server\";\n>   also use \"C:\" / \"S:\" instead of \"(C)\" / \"(S)\" for consistency and\n>   to avoid having formatted \"(C)\" as copyright symbol in HTML\n> - Use only spaces and not a combination of tabs and spaces for whitespace\n> \n> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>\n> ---\n>  Documentation/Makefile                    |   3 +-\n>  Documentation/technical/http-protocol.txt | 232\n> +++++++++++++++---------------\n>  2 files changed, 120 insertions(+), 115 deletions(-)\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 36c58fc..b19d52a 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -60,7 +60,8 @@ SP_ARTICLES += howto/maintain-git\n>  API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt\n> technical/api-index.txt, $(wildcard technical/api-*.txt)))\n>  SP_ARTICLES += $(API_DOCS)\n>  \n> -TECH_DOCS = technical/index-format\n> +TECH_DOCS = technical/http-protocol\n> +TECH_DOCS += technical/index-format\n>  TECH_DOCS += technical/pack-format\n>  TECH_DOCS += technical/pack-heuristics\n>  TECH_DOCS += technical/pack-protocol\n> diff --git a/Documentation/technical/http-protocol.txt\n> b/Documentation/technical/http-protocol.txt\n> index d21d77d..7f0cf0b 100644\n> --- a/Documentation/technical/http-protocol.txt\n> +++ b/Documentation/technical/http-protocol.txt\n> @@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the\n> form:\n>  \n>    http://<host>:<port>/<path>?<searchpart>\n>  \n> -Within this documentation the placeholder $GIT_URL will stand for\n> +Within this documentation the placeholder `$GIT_URL` will stand for\n>  the http:// repository URL entered by the end-user.\n>  \n> -Servers SHOULD handle all requests to locations matching $GIT_URL, as\n> +Servers SHOULD handle all requests to locations matching `$GIT_URL`, as\n>  both the \"smart\" and \"dumb\" HTTP protocols used by Git operate\n>  by appending additional path components onto the end of the user\n> -supplied $GIT_URL string.\n> +supplied `$GIT_URL` string.\n>  \n>  An example of a dumb client requesting for a loose object:\n>  \n> @@ -43,10 +43,10 @@ An example of a request to a submodule:\n>    $GIT_URL:     http://example.com/git/repo.git/path/submodule.git\n>    URL request: \n> http://example.com/git/repo.git/path/submodule.git/info/refs\n>  \n> -Clients MUST strip a trailing '/', if present, from the user supplied\n> -$GIT_URL string to prevent empty path tokens ('//') from appearing\n> +Clients MUST strip a trailing `/`, if present, from the user supplied\n> +`$GIT_URL` string to prevent empty path tokens (`//`) from appearing\n>  in any URL sent to a server.  Compatible clients MUST expand\n> -'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.\n> +`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`.\n>  \n>  \n>  Authentication\n> @@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD\n> be assumed\n>  by both client and server.  This includes (but is not necessarily\n>  limited to):\n>  \n> -If there is no repository at $GIT_URL, or the resource pointed to by a\n> -location matching $GIT_URL does not exist, the server MUST NOT respond\n> -with '200 OK' response.  A server SHOULD respond with\n> -'404 Not Found', '410 Gone', or any other suitable HTTP status code\n> +If there is no repository at `$GIT_URL`, or the resource pointed to by a\n> +location matching `$GIT_URL` does not exist, the server MUST NOT respond\n> +with `200 OK` response.  A server SHOULD respond with\n> +`404 Not Found`, `410 Gone`, or any other suitable HTTP status code\n>  which does not imply the resource exists as requested.\n>  \n> -If there is a repository at $GIT_URL, but access is not currently\n> -permitted, the server MUST respond with the '403 Forbidden' HTTP\n> +If there is a repository at `$GIT_URL`, but access is not currently\n> +permitted, the server MUST respond with the `403 Forbidden` HTTP\n>  status code.\n>  \n>  Servers SHOULD support both HTTP 1.0 and HTTP 1.1.\n> @@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers.\n>  Clients MAY revalidate cached entities by including If-Modified-Since\n>  and/or If-None-Match request headers.\n>  \n> -Servers MAY return '304 Not Modified' if the relevant headers appear\n> +Servers MAY return `304 Not Modified` if the relevant headers appear\n>  in the request and the entity has not changed.  Clients MUST treat\n> -'304 Not Modified' identical to '200 OK' by reusing the cached entity.\n> +`304 Not Modified` identical to `200 OK` by reusing the cached entity.\n>  \n>  Clients MAY reuse a cached entity without revalidation if the\n>  Cache-Control and/or Expires header permits caching.  Clients and\n> @@ -148,7 +148,7 @@ HTTP clients that only support the \"dumb\" protocol MUST\n> discover\n>  references by making a request for the special info/refs file of\n>  the repository.\n>  \n> -Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs,\n> +Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`,\n>  without any search/query parameters.\n>  \n>     C: GET $GIT_URL/info/refs HTTP/1.0\n> @@ -161,28 +161,28 @@ without any search/query parameters.\n>     S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n>  \n>  The Content-Type of the returned info/refs entity SHOULD be\n> -\"text/plain; charset=utf-8\", but MAY be any content type.\n> +`text/plain; charset=utf-8`, but MAY be any content type.\n>  Clients MUST NOT attempt to validate the returned Content-Type.\n>  Dumb servers MUST NOT return a return type starting with\n> -\"application/x-git-\".\n> +`application/x-git-`.\n>  \n>  Cache-Control headers MAY be returned to disable caching of the\n>  returned entity.\n>  \n>  When examining the response clients SHOULD only examine the HTTP\n> -status code.  Valid responses are '200 OK', or '304 Not Modified'.\n> +status code.  Valid responses are `200 OK`, or `304 Not Modified`.\n>  \n>  The returned content is a UNIX formatted text file describing\n>  each ref and its known value.  The file SHOULD be sorted by name\n>  according to the C locale ordering.  The file SHOULD NOT include\n> -the default ref named 'HEAD'.\n> +the default ref named `HEAD`.\n>  \n>    info_refs   =  *( ref_record )\n>    ref_record  =  any_ref / peeled_ref\n>  \n>    any_ref     =  obj-id HTAB refname LF\n>    peeled_ref  =  obj-id HTAB refname LF\n> -\t\t obj-id HTAB refname \"^{}\" LF\n> +                 obj-id HTAB refname \"^{}\" LF\n>  \n>  Smart Clients\n>  ~~~~~~~~~~~~~\n> @@ -192,13 +192,14 @@ HTTP clients that support the \"smart\" protocol (or\n> both the\n>  a parameterized request for the info/refs file of the repository.\n>  \n>  The request MUST contain exactly one query parameter,\n> -'service=$servicename', where $servicename MUST be the service\n> +`service=$servicename`, where `$servicename` MUST be the service\n>  name the client wishes to contact to complete the operation.\n>  The request MUST NOT contain additional query parameters.\n>  \n>     C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0\n>  \n> -   dumb server reply:\n> +dumb server reply:\n> +\n>     S: 200 OK\n>     S:\n>     S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31\trefs/heads/maint\n> @@ -206,7 +207,8 @@ The request MUST NOT contain additional query\n> parameters.\n>     S: 2cb58b79488a98d2721cea644875a8dd0026b115\trefs/tags/v1.0\n>     S: a3c2e2402b99163d1d59756e5f207ae21cccba4c\trefs/tags/v1.0^{}\n>  \n> -   smart server reply:\n> +smart server reply:\n> +\n>     S: 200 OK\n>     S: Content-Type: application/x-git-upload-pack-advertisement\n>     S: Cache-Control: no-cache\n> @@ -228,7 +230,7 @@ Smart Server Response\n>  ^^^^^^^^^^^^^^^^^^^^^\n>  If the server does not recognize the requested service name, or the\n>  requested service name has been disabled by the server administrator,\n> -the server MUST respond with the '403 Forbidden' HTTP status code.\n> +the server MUST respond with the `403 Forbidden` HTTP status code.\n>  \n>  Otherwise, smart servers MUST respond with the smart server reply\n>  format for the requested service name.\n> @@ -236,46 +238,46 @@ format for the requested service name.\n>  Cache-Control headers SHOULD be used to disable caching of the\n>  returned entity.\n>  \n> -The Content-Type MUST be 'application/x-$servicename-advertisement'.\n> +The Content-Type MUST be `application/x-$servicename-advertisement`.\n>  Clients SHOULD fall back to the dumb protocol if another content\n>  type is returned.  When falling back to the dumb protocol clients\n> -SHOULD NOT make an additional request to $GIT_URL/info/refs, but\n> +SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but\n>  instead SHOULD use the response already in hand.  Clients MUST NOT\n>  continue if they do not support the dumb protocol.\n>  \n> -Clients MUST validate the status code is either '200 OK' or\n> -'304 Not Modified'.\n> +Clients MUST validate the status code is either `200 OK` or\n> +`304 Not Modified`.\n>  \n>  Clients MUST validate the first five bytes of the response entity\n> -matches the regex \"^[0-9a-f]{4}#\".  If this test fails, clients\n> +matches the regex `^[0-9a-f]{4}#`.  If this test fails, clients\n>  MUST NOT continue.\n>  \n>  Clients MUST parse the entire response as a sequence of pkt-line\n>  records.\n>  \n> -Clients MUST verify the first pkt-line is \"# service=$servicename\".\n> +Clients MUST verify the first pkt-line is `# service=$servicename`.\n>  Servers MUST set $servicename to be the request parameter value.\n>  Servers SHOULD include an LF at the end of this line.\n>  Clients MUST ignore an LF at the end of the line.\n>  \n> -Servers MUST terminate the response with the magic \"0000\" end\n> +Servers MUST terminate the response with the magic `0000` end\n>  pkt-line marker.\n>  \n>  The returned response is a pkt-line stream describing each ref and\n>  its known value.  The stream SHOULD be sorted by name according to\n>  the C locale ordering.  The stream SHOULD include the default ref\n> -named 'HEAD' as the first ref.  The stream MUST include capability\n> +named `HEAD` as the first ref.  The stream MUST include capability\n>  declarations behind a NUL on the first ref.\n>  \n>    smart_reply     =  PKT-LINE(\"# service=$servicename\" LF)\n> -\t\t     ref_list\n> -\t\t     \"0000\"\n> +                     ref_list\n> +                     \"0000\"\n>    ref_list        =  empty_list / non_empty_list\n>  \n>    empty_list      =  PKT-LINE(zero-id SP \"capabilities^{}\" NUL cap-list\n> LF)\n>  \n>    non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)\n> -\t\t     *ref_record\n> +                     *ref_record\n>  \n>    cap-list        =  capability *(SP capability)\n>    capability      =  1*(LC_ALPHA / DIGIT / \"-\" / \"_\")\n> @@ -284,14 +286,15 @@ declarations behind a NUL on the first ref.\n>    ref_record      =  any_ref / peeled_ref\n>    any_ref         =  PKT-LINE(obj-id SP name LF)\n>    peeled_ref      =  PKT-LINE(obj-id SP name LF)\n> -\t\t     PKT-LINE(obj-id SP name \"^{}\" LF\n> +                     PKT-LINE(obj-id SP name \"^{}\" LF\n> +\n>  \n>  Smart Service git-upload-pack\n>  ------------------------------\n> -This service reads from the repository pointed to by $GIT_URL.\n> +This service reads from the repository pointed to by `$GIT_URL`.\n>  \n>  Clients MUST first perform ref discovery with\n> -'$GIT_URL/info/refs?service=git-upload-pack'.\n> +`$GIT_URL/info/refs?service=git-upload-pack`.\n>  \n>     C: POST $GIT_URL/git-upload-pack HTTP/1.0\n>     C: Content-Type: application/x-git-upload-pack-request\n> @@ -313,18 +316,18 @@ to prevent caching of the response.\n>  \n>  Servers SHOULD support all capabilities defined here.\n>  \n> -Clients MUST send at least one 'want' command in the request body.\n> -Clients MUST NOT reference an id in a 'want' command which did not\n> +Clients MUST send at least one \"want\" command in the request body.\n> +Clients MUST NOT reference an id in a \"want\" command which did not\n>  appear in the response obtained through ref discovery unless the\n> -server advertises capability \"allow-tip-sha1-in-want\".\n> +server advertises capability `allow-tip-sha1-in-want`.\n>  \n>    compute_request   =  want_list\n> -\t\t       have_list\n> -\t\t       request_end\n> +                       have_list\n> +                       request_end\n>    request_end       =  \"0000\" / \"done\"\n>  \n>    want_list         =  PKT-LINE(want NUL cap_list LF)\n> -\t\t       *(want_pkt)\n> +                       *(want_pkt)\n>    want_pkt          =  PKT-LINE(want LF)\n>    want              =  \"want\" SP id\n>    cap_list          =  *(SP capability) SP\n> @@ -337,24 +340,28 @@ TODO: Don't use uppercase for variable names below.\n>  The Negotiation Algorithm\n>  ~~~~~~~~~~~~~~~~~~~~~~~~~\n>  The computation to select the minimal pack proceeds as follows\n> -(c = client, s = server):\n> +(C = client, S = server):\n> +\n> +'init step:'\n> +\n> +C: Use ref discovery to obtain the advertised refs.\n> +\n> +C: Place any object seen into set ADVERTISED.\n>  \n> - init step:\n> - (c) Use ref discovery to obtain the advertised refs.\n> - (c) Place any object seen into set ADVERTISED.\n> +C: Build an empty set, COMMON, to hold the objects that are later\n> +   determined to be on both ends.\n>  \n> - (c) Build an empty set, COMMON, to hold the objects that are later\n> -     determined to be on both ends.\n> - (c) Build a set, WANT, of the objects from ADVERTISED the client\n> -     wants to fetch, based on what it saw during ref discovery.\n> +C: Build a set, WANT, of the objects from ADVERTISED the client\n> +   wants to fetch, based on what it saw during ref discovery.\n>  \n> - (c) Start a queue, C_PENDING, ordered by commit time (popping newest\n> -     first).  Add all client refs.  When a commit is popped from\n> -     the queue its parents SHOULD be automatically inserted back.\n> -     Commits MUST only enter the queue once.\n> +C: Start a queue, C_PENDING, ordered by commit time (popping newest\n> +   first).  Add all client refs.  When a commit is popped from\n> +   the queue its parents SHOULD be automatically inserted back.\n> +   Commits MUST only enter the queue once.\n>  \n> - one compute step:\n> - (c) Send one $GIT_URL/git-upload-pack request:\n> +'one compute step:'\n> +\n> +C: Send one `$GIT_URL/git-upload-pack` request:\n>  \n>     C: 0032want <WANT #1>...............................\n>     C: 0032want <WANT #2>...............................\n> @@ -367,93 +374,90 @@ The computation to select the minimal pack proceeds as\n> follows\n>     ....\n>     C: 0000\n>  \n> -     The stream is organized into \"commands\", with each command\n> -     appearing by itself in a pkt-line.  Within a command line\n> -     the text leading up to the first space is the command name,\n> -     and the remainder of the line to the first LF is the value.\n> -     Command lines are terminated with an LF as the last byte of\n> -     the pkt-line value.\n> +The stream is organized into \"commands\", with each command\n> +appearing by itself in a pkt-line.  Within a command line\n> +the text leading up to the first space is the command name,\n> +and the remainder of the line to the first LF is the value.\n> +Command lines are terminated with an LF as the last byte of\n> +the pkt-line value.\n>  \n> -     Commands MUST appear in the following order, if they appear\n> -     at all in the request stream:\n> +Commands MUST appear in the following order, if they appear\n> +at all in the request stream:\n>  \n> -       * want\n> -       * have\n> +* \"want\"\n> +* \"have\"\n>  \n> -     The stream is terminated by a pkt-line flush (\"0000\").\n> +The stream is terminated by a pkt-line flush (`0000`).\n>  \n> -     A single \"want\" or \"have\" command MUST have one hex formatted\n> -     SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n> -     multiple commands.\n> +A single \"want\" or \"have\" command MUST have one hex formatted\n> +SHA-1 as its value.  Multiple SHA-1s MUST be sent by sending\n> +multiple commands.\n>  \n> -     The HAVE list is created by popping the first 32 commits\n> -     from C_PENDING.  Less can be supplied if C_PENDING empties.\n> +The HAVE list is created by popping the first 32 commits\n> +from C_PENDING.  Less can be supplied if C_PENDING empties.\n>  \n> -     If the client has sent 256 HAVE commits and has not yet\n> -     received one of those back from S_COMMON, or the client has\n> -     emptied C_PENDING it SHOULD include a \"done\" command to let\n> -     the server know it won't proceed:\n> +If the client has sent 256 HAVE commits and has not yet\n> +received one of those back from S_COMMON, or the client has\n> +emptied C_PENDING it SHOULD include a \"done\" command to let\n> +the server know it won't proceed:\n>  \n>     C: 0009done\n>  \n> -  (s) Parse the git-upload-pack request:\n> -\n> -      Verify all objects in WANT are directly reachable from refs.\n> -\n> -      The server MAY walk backwards through history or through\n> -      the reflog to permit slightly stale requests.\n> +S: Parse the git-upload-pack request:\n>  \n> -      If no WANT objects are received, send an error:\n> +Verify all objects in WANT are directly reachable from refs.\n>  \n> -TODO: Define error if no want lines are requested.\n> +The server MAY walk backwards through history or through\n> +the reflog to permit slightly stale requests.\n>  \n> -      If any WANT object is not reachable, send an error:\n> +If no WANT objects are received, send an error:\n> +TODO: Define error if no \"want\" lines are requested.\n>  \n> -TODO: Define error if an invalid want is requested.\n> +If any WANT object is not reachable, send an error:\n> +TODO: Define error if an invalid \"want\" is requested.\n>  \n> -     Create an empty list, S_COMMON.\n> +Create an empty list, S_COMMON.\n>  \n> -     If 'have' was sent:\n> +If \"have\" was sent:\n>  \n> -     Loop through the objects in the order supplied by the client.\n> -     For each object, if the server has the object reachable from\n> -     a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n> -     do not add any ancestors, even if they also appear in HAVE.\n> +Loop through the objects in the order supplied by the client.\n>  \n> -  (s) Send the git-upload-pack response:\n> +For each object, if the server has the object reachable from\n> +a ref, add it to S_COMMON.  If a commit is added to S_COMMON,\n> +do not add any ancestors, even if they also appear in HAVE.\n>  \n> -     If the server has found a closed set of objects to pack or the\n> -     request ends with \"done\", it replies with the pack.\n> +S: Send the git-upload-pack response:\n>  \n> +If the server has found a closed set of objects to pack or the\n> +request ends with \"done\", it replies with the pack.\n>  TODO: Document the pack based response\n> -   S: PACK...\n>  \n> -     The returned stream is the side-band-64k protocol supported\n> -     by the git-upload-pack service, and the pack is embedded into\n> -     stream 1.  Progress messages from the server side MAY appear\n> -     in stream 2.\n> +   S: PACK...\n>  \n> -     Here a \"closed set of objects\" is defined to have at least\n> -     one path from every WANT to at least one COMMON object.\n> +The returned stream is the side-band-64k protocol supported\n> +by the git-upload-pack service, and the pack is embedded into\n> +stream 1.  Progress messages from the server side MAY appear\n> +in stream 2.\n>  \n> -     If the server needs more information, it replies with a\n> -     status continue response:\n> +Here a \"closed set of objects\" is defined to have at least\n> +one path from every WANT to at least one COMMON object.\n>  \n> +If the server needs more information, it replies with a\n> +status continue response:\n>  TODO: Document the non-pack response\n>  \n> -  (c) Parse the upload-pack response:\n> -\n> -TODO: Document parsing response\n> +C: Parse the upload-pack response:\n> +   TODO: Document parsing response\n>  \n> -      Do another compute step.\n> +'Do another compute step.'\n>  \n>  \n>  Smart Service git-receive-pack\n>  ------------------------------\n> -This service reads from the repository pointed to by $GIT_URL.\n> +This service reads from the repository pointed to by `$GIT_URL`.\n>  \n>  Clients MUST first perform ref discovery with\n> -'$GIT_URL/info/refs?service=git-receive-pack'.\n> +`$GIT_URL/info/refs?service=git-receive-pack`.\n>  \n>     C: POST $GIT_URL/git-receive-pack HTTP/1.0\n>     C: Content-Type: application/x-git-receive-pack-request\n> @@ -479,10 +483,10 @@ Within the command portion of the request body clients\n> SHOULD send\n>  the id obtained through ref discovery as old_id.\n>  \n>    update_request  =  command_list\n> -\t\t     \"PACK\" <binary data>\n> +                     \"PACK\" <binary data>\n>  \n>    command_list    =  PKT-LINE(command NUL cap_list LF)\n> -\t\t     *(command_pkt)\n> +                     *(command_pkt)\n>    command_pkt     =  PKT-LINE(command LF)\n>    cap_list        =  *(SP capability) SP\n>  \n> -- \n> 1.8.5.2.msysgit.0\n> \n> \n> \n> ---\n> Thomas\n> \n\n---\nThomas\n"}]}