[PATCH] Document shallow/unshallow/deepen protocol request and response.

[PATCH] Document shallow/unshallow/deepen protocol request and response.

[dborowitz]

From: Dave Borowitz <dborowitz@google.com>

This patch fixes a TODO in the pack protocol documentation about the
protocol for shallow clones. I'll be the first to admit I may not
understand shallow clones fully, but this patch is hopefully a good
starting point.

---
 Documentation/technical/pack-protocol.txt |   36 +++++++++++++++++++++-------
 1 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 9a5cdaf..d3392f5 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -194,6 +194,7 @@ effect, out of what the server said it could do with the first 'want' line.
 
 ----
   upload-request    =  want-list
+		       shallow-request
 		       have-list
 		       compute-end
 
@@ -204,6 +205,11 @@ effect, out of what the server said it could do with the first 'want' line.
   first-want        =  PKT-LINE("want" SP obj-id SP capability-list LF)
   additional-want   =  PKT-LINE("want" SP obj-id LF)
 
+  shallow-request   =  *shallow-line
+		       deepen-line
+  shallow-line      =  PKT-LINE("shallow" SP obj-id LF)
+  deepen-line       =  PKT-LINE("deepen" SP 1*DIGIT LF)
+
   have-list         =  *have-line
   have-line         =  PKT-LINE("have" SP obj-id LF)
   compute-end       =  flush-pkt / PKT-LINE("done")
@@ -215,15 +221,23 @@ discovery phase as 'want' lines. Clients MUST send at least one
 obj-id in a 'want' command which did not appear in the response
 obtained through ref discovery.
 
-If client is requesting a shallow clone, it will now send a 'deepen'
-line with the depth it is requesting.
+If client is requesting a shallow clone, it will now send a 'shallow'
+line for each shallow commit it currently has, followed by a 'deepen'
+line for the depth it is requesting.
+
+The server will respond to a shallow clone request with several
+'shallow'/'unshallow' lines. The server MUST send one 'shallow' line for
+each new commit that will be shallow following the deepen operation, and
+the server MUST send one 'unshallow' line for each shallow commit the
+client has that will no longer be shallow after the deepen. The server
+SHOULD NOT send 'shallow' lines for shallow commits the client has that
+remain shallow. The server MUST NOT mention an obj-id in an 'unshallow'
+line that the client did not mention in a corresponding 'shallow' line.
 
 Once all the "want"s (and optional 'deepen') are transferred,
 clients MUST send a flush-pkt. If the client has all the references
 on the server, client flushes and disconnects.
 
-TODO: shallow/unshallow response and document the deepen command in the ABNF.
-
 Now the client will send a list of the obj-ids it has using 'have'
 lines.  In multi_ack mode, the canonical implementation will send up
 to 32 of these at a time, then will send a flush-pkt.  The canonical
@@ -289,11 +303,15 @@ if there is no common base found.
 Then the server will start sending its packfile data.
 
 ----
-  server-response = *ack_multi ack / nak
-  ack_multi       = PKT-LINE("ACK" SP obj-id ack_status LF)
-  ack_status      = "continue" / "common" / "ready"
-  ack             = PKT-LINE("ACK SP obj-id LF)
-  nak             = PKT-LINE("NAK" LF)
+  server-response  = [shallow-response]
+		    *ack_multi ack / nak
+  shallow-response = *shallow-line
+		     *unshallow-line
+  unshallow-line   = PKT-LINE("unshallow" SP obj-id LF)
+  ack_multi        = PKT-LINE("ACK" SP obj-id ack_status LF)
+  ack_status       = "continue" / "common" / "ready"
+  ack              = PKT-LINE("ACK SP obj-id LF)
+  nak              = PKT-LINE("NAK" LF)
 ----
 
 A simple clone may look like this (with no 'have' lines):
-- 
1.7.0.rc2.28.gf476c0