{"thread":{"id":"34730","subject":"[PATCH] Document smart http","startedAt":"2013-08-20T05:08:08Z","lastAt":"2013-08-20T14:20:45Z","messageCount":3,"participants":["Nguyễn Thái Ngọc Duy","Jeff King","Duy Nguyen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"225494","messageId":"1376975288-17079-1-git-send-email-pclouds@gmail.com","threadId":"34730","inReplyTo":null,"subject":"[PATCH] Document smart http","fromName":"Nguyễn Thái Ngọc Duy","fromEmail":"pclouds@gmail.com","sentAt":"2013-08-20T05:08:08Z","receivedAt":"2013-08-20T05:08:08Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"This may provide some clues for those who want to modify smart http\ncode as smart http is pretty much undocumented. Smart http \"document\"\nso far is a few commit messages and the source code.\n\nSigned-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com>\n---\n Documentation/git-fetch-pack.txt          | 11 +++--\n Documentation/git-receive-pack.txt        | 12 +++++-\n Documentation/git-send-pack.txt           |  9 +++-\n Documentation/git-upload-pack.txt         |  9 +++-\n Documentation/technical/pack-protocol.txt | 69 +++++++++++++++++++++++++++++++\n 5 files changed, 103 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt\nindex 1e71754..85a9437 100644\n--- a/Documentation/git-fetch-pack.txt\n+++ b/Documentation/git-fetch-pack.txt\n@@ -9,10 +9,7 @@ git-fetch-pack - Receive missing objects from another repository\n SYNOPSIS\n --------\n [verse]\n-'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag]\n-\t[--upload-pack=<git-upload-pack>]\n-\t[--depth=<n>] [--no-progress]\n-\t[-v] [<host>:]<directory> [<refs>...]\n+'git fetch-pack' [options] [<host>:]<directory> [<refs>...]\n \n DESCRIPTION\n -----------\n@@ -90,6 +87,12 @@ be in a separate packet, and the list must end with a flush packet.\n --no-progress::\n \tDo not show the progress.\n \n+--stateless-rpc::\n+\tSmart HTTP mode.\n+\n+--lock-pack::\n+\tIssue \"lock\" command to the remote helper via stdout.\n+\n -v::\n \tRun verbosely.\n \ndiff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt\nindex b1f7dc6..0b2029c 100644\n--- a/Documentation/git-receive-pack.txt\n+++ b/Documentation/git-receive-pack.txt\n@@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository\n SYNOPSIS\n --------\n [verse]\n-'git-receive-pack' <directory>\n+'git-receive-pack' [options] <directory>\n \n DESCRIPTION\n -----------\n@@ -35,6 +35,16 @@ are not fast-forwards.\n \n OPTIONS\n -------\n+--stateless-rpc::\n+\tSmart HTTP mode.\n+\n+--advertise-refs::\n+\tOnly the initial ref advertisement is output then exits\n+\timmediately.\n+\n+--quiet::\n+\tMake unpack-objects at the receive-pack end quiet.\n+\n <directory>::\n \tThe repository to sync into.\n \ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex dc3a568..6cee3d4 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -9,7 +9,7 @@ git-send-pack - Push objects over Git protocol to another repository\n SYNOPSIS\n --------\n [verse]\n-'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...]\n+'git send-pack' [options] [<host>:]<directory> [<ref>...]\n \n DESCRIPTION\n -----------\n@@ -52,6 +52,13 @@ OPTIONS\n \tSend a \"thin\" pack, which records objects in deltified form based\n \ton objects not included in the pack to reduce network traffic.\n \n+--stateless-rpc::\n+\tSmart HTTP mode.\n+\n+--helper-status:\n+\tIssue status commands (e.g. \"ok\" or \"error\") to the remote\n+\thelper via stdout.\n+\n <host>::\n \tA remote host to house the repository.  When this\n \tpart is specified, 'git-receive-pack' is invoked via\ndiff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt\nindex 0abc806..ce9a455 100644\n--- a/Documentation/git-upload-pack.txt\n+++ b/Documentation/git-upload-pack.txt\n@@ -9,7 +9,7 @@ git-upload-pack - Send objects packed back to git-fetch-pack\n SYNOPSIS\n --------\n [verse]\n-'git-upload-pack' [--strict] [--timeout=<n>] <directory>\n+'git-upload-pack' [options] <directory>\n \n DESCRIPTION\n -----------\n@@ -31,6 +31,13 @@ OPTIONS\n --timeout=<n>::\n \tInterrupt transfer after <n> seconds of inactivity.\n \n+--stateless-rpc::\n+\tSmart HTTP mode.\n+\n+--advertise-refs::\n+\tOnly the initial ref advertisement is output then exits\n+\timmediately.\n+\n <directory>::\n \tThe repository to sync from.\n \ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt\nindex b898e97..7590394 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/technical/pack-protocol.txt\n@@ -546,3 +546,72 @@ An example client/server communication might look like this:\n    S: 0018ok refs/heads/debug\\n\n    S: 002ang refs/heads/master non-fast-forward\\n\n ----\n+\n+Smart HTTP Transport\n+--------------------\n+\n+Smart HTTP protocol is basically \"git protocol on top of http\". The\n+base protocol is modified slightly to fit HTTP processing model: no\n+bidirectional full-duplex connections, the program may read the\n+request, write a response and must exit. Any negotiation is broken\n+down into many separate GET or POST requests. The server is\n+stateless. The client must send enough information so that the server\n+can recreate the previous state.\n+\n+Reference Discovery\n+-------------------\n+\n+The server end always sends the list of references in both push and\n+fetch cases. This ref list is retrieved by the client's sending HTTP\n+GET request to a smart http url ending with\n+\"/info/refs?service=<service>\" where <service> could be either\n+git-upload-pack or git-receive-pack for fetching or pushing\n+respectively. The output is in pkt-line format.\n+\n+----\n+  advertised-refs  =  service\n+\t\t      flush-pkt\n+\t\t      (no-refs / list-of-refs)\n+\t\t      flush-pkt\n+\n+  service          =  PKT-LINE(\"# service=\" service-name)\n+  service-name     =  (\"git-upload-pack\" / \"git-receive-pack\")\n+\n+  no-refs          =  PKT-LINE(zero-id SP \"capabilities^{}\"\n+\t\t      NUL capability-list LF)\n+\n+  list-of-refs     =  first-ref *other-ref\n+  first-ref        =  PKT-LINE(obj-id SP refname\n+\t\t      NUL capability-list LF)\n+\n+  other-ref        =  PKT-LINE(other-tip / other-peeled)\n+  other-tip        =  obj-id SP refname LF\n+  other-peeled     =  obj-id SP refname \"^{}\" LF\n+\n+  capability-list  =  capability *(SP capability)\n+  capability       =  1*(LC_ALPHA / DIGIT / \"-\" / \"_\")\n+  LC_ALPHA         =  %x61-7A\n+----\n+\n+Packfile Negotiation\n+--------------------\n+\n+For fetching, packet negotiation is via a series of HTTP POST requests\n+to an url ending with \"/git-upload-pack\" with the content in pkt-line\n+format. git-upload-pack's response consists of a \"service\" line like\n+in Reference Discovery followed by normal git-upload-pack packet\n+lines. Capability multi_ack_detailed is required by Smart HTTP.\n+\n+Common objects that are discovered are appended onto the request as\n+have lines and are sent again on the next request. This allows the\n+remote side to reinitialize its in-memory list of common objects\n+during the next request and the remote does not need to maintain the\n+negotiation state.\n+\n+Reference Update Request\n+------------------------\n+\n+For pushing, a HTTP POST request is sent to an url ending with\n+\"/git-receive-pack\" with the content in pkt-line format.\n+git-receive-pack's response consists of a \"service\" line like in\n+Reference Discovery followed by normal git-receive-pack packet lines.\n-- \n1.8.2.82.gc24b958\n"},{"id":"225510","messageId":"20130820141630.GB32370@sigill.intra.peff.net","threadId":"34730","inReplyTo":"1376975288-17079-1-git-send-email-pclouds@gmail.com","subject":"Re: [PATCH] Document smart http","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2013-08-20T14:16:30Z","receivedAt":"2013-08-20T14:16:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Aug 20, 2013 at 12:08:08PM +0700, Nguyen Thai Ngoc Duy wrote:\n\n> This may provide some clues for those who want to modify smart http\n> code as smart http is pretty much undocumented. Smart http \"document\"\n> so far is a few commit messages and the source code.\n\nThere was also this:\n\n  http://article.gmane.org/gmane.comp.version-control.git/129734\n\nwhich seems to have never gotten updated enough to be applied along with\nthe code. But with some updates to make sure it matches the current\nbehavior, it is probably a more comprehensive description.\n\nBut if you don't feel like spending more time on this on top of what\nyou've already done, I think the patch I'm responding to is better than\nwhat we have now (i.e., nothing).\n\n> +Reference Discovery\n> +-------------------\n> +\n> +The server end always sends the list of references in both push and\n> +fetch cases. This ref list is retrieved by the client's sending HTTP\n> +GET request to a smart http url ending with\n> +\"/info/refs?service=<service>\" where <service> could be either\n> +git-upload-pack or git-receive-pack for fetching or pushing\n> +respectively. The output is in pkt-line format.\n> +\n> +----\n> +  advertised-refs  =  service\n> +\t\t      flush-pkt\n> +\t\t      (no-refs / list-of-refs)\n> +\t\t      flush-pkt\n> +\n> +  service          =  PKT-LINE(\"# service=\" service-name)\n> +  service-name     =  (\"git-upload-pack\" / \"git-receive-pack\")\n> +\n> +  no-refs          =  PKT-LINE(zero-id SP \"capabilities^{}\"\n> +\t\t      NUL capability-list LF)\n> +\n> +  list-of-refs     =  first-ref *other-ref\n> +  first-ref        =  PKT-LINE(obj-id SP refname\n> +\t\t      NUL capability-list LF)\n> +\n> +  other-ref        =  PKT-LINE(other-tip / other-peeled)\n> +  other-tip        =  obj-id SP refname LF\n> +  other-peeled     =  obj-id SP refname \"^{}\" LF\n> +\n> +  capability-list  =  capability *(SP capability)\n> +  capability       =  1*(LC_ALPHA / DIGIT / \"-\" / \"_\")\n> +  LC_ALPHA         =  %x61-7A\n> +----\n\nMost of this is a repeat of what is in the earlier sections. I don't\nthink the protocol is changing much and these are not likely to get out of\ndate with each other, but I wonder if it is easier on the reader to\nsimply describe the output in terms of what is added on top of the\nregular ref advertisement (i.e., the service line). Something like:\n\n  stateless-advertised-refs =  service\n                               advertised-refs\n\n  service                   =  PKT-LINE(\"# service=\" service-name)\n  service-name              =  (\"git-upload-pack\" / \"git-receive-pack\")\n\nwhere advertised-refs is defined in the earlier BNF. You may also want\nto note:\n\n  Servers may respond to a smart request with a regular `advertised-refs`\n  response rather than a `stateless-advertised-refs` response. In this\n  case, the client MUST assume that the server does not understand smart\n  HTTP and either abort or proceed with the non-smart protocol.\n\n-Peff\n"},{"id":"225514","messageId":"CACsJy8Ax3zJOBYaASnNfu6CTFoTw5=XRdSmK9KTMjSUEEvsE7w@mail.gmail.com","threadId":"34730","inReplyTo":"20130820141630.GB32370@sigill.intra.peff.net","subject":"Re: [PATCH] Document smart http","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2013-08-20T14:20:45Z","receivedAt":"2013-08-20T14:20:45Z","isPatch":true,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Tue, Aug 20, 2013 at 9:16 PM, Jeff King <peff@peff.net> wrote:\n> On Tue, Aug 20, 2013 at 12:08:08PM +0700, Nguyen Thai Ngoc Duy wrote:\n>\n>> This may provide some clues for those who want to modify smart http\n>> code as smart http is pretty much undocumented. Smart http \"document\"\n>> so far is a few commit messages and the source code.\n>\n> There was also this:\n>\n>   http://article.gmane.org/gmane.comp.version-control.git/129734\n>\n> which seems to have never gotten updated enough to be applied along with\n> the code. But with some updates to make sure it matches the current\n> behavior, it is probably a more comprehensive description.\n\nIf I knew about this patch, it could have saved me a lot of time\nreading remote-curl.c. Will check it with current code and resubmit an\nupdate of this version instead.\n-- \nDuy\n"}]}