{"thread":{"id":"27587","subject":"[PATCH 1/2] Fix documentation of fetch-pack that implies that the client can disconnect after sending wants.","startedAt":"2011-06-08T22:11:50Z","lastAt":"2011-06-08T22:11:51Z","messageCount":2,"participants":["ZAK Neronskiy"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"169704","messageId":"1307571111-14219-1-git-send-email-zakmagnus@google.com","threadId":"27587","inReplyTo":null,"subject":"[PATCH 1/2] Fix documentation of fetch-pack that implies that the client can disconnect after sending wants.","fromName":"ZAK Neronskiy","fromEmail":"zakmagnus@google.com","sentAt":"2011-06-08T22:11:50Z","receivedAt":"2011-06-08T22:11:50Z","isPatch":true,"sender":{"key":"zakmagnus@google.com","avatar":null},"body":"Specify conditions under which the client can terminate the connection\nearly. Previously, an unintended behavior was possible which could\nconfuse servers.\n\nBased-on-patch-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Alex Neronskiy <zakmagnus@google.com>\n---\n Documentation/technical/pack-protocol.txt |   29 +++++++++++++++--------------\n 1 files changed, 15 insertions(+), 14 deletions(-)\n\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt\nindex 369f91d..ce69f57 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/technical/pack-protocol.txt\n@@ -179,18 +179,19 @@ and descriptions.\n \n Packfile Negotiation\n --------------------\n-After reference and capabilities discovery, the client can decide\n-to terminate the connection by sending a flush-pkt, telling the\n-server it can now gracefully terminate (as happens with the ls-remote\n-command) or it can enter the negotiation phase, where the client and\n-server determine what the minimal packfile necessary for transport is.\n-\n-Once the client has the initial list of references that the server\n-has, as well as the list of capabilities, it will begin telling the\n-server what objects it wants and what objects it has, so the server\n-can make a packfile that only contains the objects that the client needs.\n-The client will also send a list of the capabilities it wants to be in\n-effect, out of what the server said it could do with the first 'want' line.\n+After reference and capabilities discovery, the client can decide to\n+terminate the connection by sending a flush-pkt, telling the server it can\n+now gracefully terminate, and disconnect, when it does not need any pack\n+data. This can happen with the ls-remote command, and also can happen when\n+the client already is up-to-date.\n+\n+Otherwise, it enters the negotiation phase, where the client and\n+server determine what the minimal packfile necessary for transport is,\n+by telling the server what objects it wants and what objects it has,\n+so the server can make a packfile that only contains the objects that the\n+client needs.  The client will also send a list of the capabilities it\n+wants to be in effect, out of what the server said it could do with the\n+first 'want' line.\n \n ----\n   upload-request    =  want-list\n@@ -219,8 +220,8 @@ If client is requesting a shallow clone, it will now send a 'deepen'\n line with the depth it is requesting.\n \n Once all the \"want\"s (and optional 'deepen') are transferred,\n-clients MUST send a flush-pkt. If the client has all the references\n-on the server, client flushes and disconnects.\n+clients MUST send a flush-pkt, to tell the server side that it is\n+done sending the list.\n \n TODO: shallow/unshallow response and document the deepen command in the ABNF.\n \n-- \n1.7.3.1\n"},{"id":"169705","messageId":"1307571111-14219-2-git-send-email-zakmagnus@google.com","threadId":"27587","inReplyTo":"1307571111-14219-1-git-send-email-zakmagnus@google.com","subject":"[PATCH 2/2] Document the underlying protocol used by shallow repositories and --depth commands.","fromName":"ZAK Neronskiy","fromEmail":"zakmagnus@google.com","sentAt":"2011-06-08T22:11:51Z","receivedAt":"2011-06-08T22:11:51Z","isPatch":true,"sender":{"key":"zakmagnus@google.com","avatar":null},"body":"Explain the exchange that occurs between a client and server when\nthe client is requesting shallow history and/or is already using\na shallow repository.\n\nSigned-off-by: Alex Neronskiy <zakmagnus@google.com>\n---\n Documentation/technical/pack-protocol.txt |   88 +++++++++++++++++++++-------\n 1 files changed, 66 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt\nindex ce69f57..a7004c6 100644\n--- a/Documentation/technical/pack-protocol.txt\n+++ b/Documentation/technical/pack-protocol.txt\n@@ -187,27 +187,28 @@ the client already is up-to-date.\n \n Otherwise, it enters the negotiation phase, where the client and\n server determine what the minimal packfile necessary for transport is,\n-by telling the server what objects it wants and what objects it has,\n-so the server can make a packfile that only contains the objects that the\n-client needs.  The client will also send a list of the capabilities it\n-wants to be in effect, out of what the server said it could do with the\n-first 'want' line.\n+by telling the server what objects it wants, its shallow objects\n+(if any), and the maximum commit depth it wants (if any).  The client\n+will also send a list of the capabilities it wants to be in effect,\n+out of what the server said it could do with the first 'want' line.\n \n ----\n   upload-request    =  want-list\n-\t\t       have-list\n-\t\t       compute-end\n+\t\t       *shallow-line\n+\t\t       *1depth-request\n+\t\t       flush-pkt\n \n   want-list         =  first-want\n \t\t       *additional-want\n-\t\t       flush-pkt\n+\n+  shallow-line      =  PKT_LINE(\"shallow\" SP obj-id)\n+\n+  depth-request     =  PKT_LINE(\"deepen\" SP depth)\n \n   first-want        =  PKT-LINE(\"want\" SP obj-id SP capability-list LF)\n   additional-want   =  PKT-LINE(\"want\" SP obj-id LF)\n \n-  have-list         =  *have-line\n-  have-line         =  PKT-LINE(\"have\" SP obj-id LF)\n-  compute-end       =  flush-pkt / PKT-LINE(\"done\")\n+  depth             =  1*DIGIT\n ----\n \n Clients MUST send all the obj-ids it wants from the reference\n@@ -216,21 +217,64 @@ discovery phase as 'want' lines. Clients MUST send at least one\n obj-id in a 'want' command which did not appear in the response\n obtained through ref discovery.\n \n-If client is requesting a shallow clone, it will now send a 'deepen'\n-line with the depth it is requesting.\n+The client MUST write all obj-ids which it only has shallow copies\n+of (meaning that it does not have the parents of a commit) as\n+'shallow' lines so that the server is aware of the limitations of\n+the client's history. Clients MUST NOT mention an obj-id which\n+it does not know exists on the server.\n+\n+The client now sends the maximum commit history depth it wants for\n+this transaction, which is the number of commits it wants from the\n+tip of the history, if any, as a 'deepen' line.  A depth of 0 is the\n+same as not making a depth request. The client does not want to receive\n+any commits beyond this depth, nor objects needed only to complete\n+those commits. Commits whose parents are not received as a result are\n+defined as shallow and marked as such in the server. This information\n+is sent back to the client in the next step.\n+\n+Once all the 'want's and 'shallow's (and optional 'deepen') are\n+transferred, clients MUST send a flush-pkt, to tell the server side\n+that it is done sending the list.\n+\n+Otherwise, if the client sent a positive depth request, the server\n+will determine which commits will and will not be shallow and\n+send this information to the client. If the client did not request\n+a positive depth, this step is skipped.\n \n-Once all the \"want\"s (and optional 'deepen') are transferred,\n-clients MUST send a flush-pkt, to tell the server side that it is\n-done sending the list.\n+----\n+  shallow-update   =  *shallow-line\n+\t\t      *unshallow-line\n+\t\t      flush-pkt\n \n-TODO: shallow/unshallow response and document the deepen command in the ABNF.\n+  shallow-line     =  PKT-LINE(\"shallow\" SP obj-id)\n+\n+  unshallow-line   =  PKT-LINE(\"unshallow\" SP obj-id)\n+----\n+\n+If the client has requested a positive depth, the server will compute\n+the set of commits which are no deeper than the desired depth, starting\n+at the client's wants. The server writes 'shallow' lines for each\n+commit whose parents will not be sent as a result. The server writes\n+an 'unshallow' line for each commit which the client has indicated is\n+shallow, but is no longer shallow at the currently requested depth\n+(that is, its parents will now be sent). The server MUST NOT mark\n+as unshallow anything which the client has not indicated was shallow.\n \n Now the client will send a list of the obj-ids it has using 'have'\n-lines.  In multi_ack mode, the canonical implementation will send up\n-to 32 of these at a time, then will send a flush-pkt.  The canonical\n-implementation will skip ahead and send the next 32 immediately,\n-so that there is always a block of 32 \"in-flight on the wire\" at a\n-time.\n+lines, so the server can make a packfile that only contains the objects\n+that the client needs. In multi_ack mode, the canonical implementation\n+will send up to 32 of these at a time, then will send a flush-pkt. The\n+canonical implementation will skip ahead and send the next 32 immediately,\n+so that there is always a block of 32 \"in-flight on the wire\" at a time.\n+\n+----\n+  upload-haves      =  have-list\n+\t\t       compute-end\n+\n+  have-list         =  *have-line\n+  have-line         =  PKT-LINE(\"have\" SP obj-id LF)\n+  compute-end       =  flush-pkt / PKT-LINE(\"done\")\n+----\n \n If the server reads 'have' lines, it then will respond by ACKing any\n of the obj-ids the client said it had that the server also has. The\n-- \n1.7.3.1\n"}]}