Document the underlying protocol used by shallow repositories and --depth commands.
Explain the exchange that occurs between a client and server when the client is requesting shallow history and/or is already using a shallow repository. Signed-off-by: Alex Neronskiy <zakmagnus@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Alex Neronskiy committed
Jun 8, 2011 at 15:11 UTC
4a1c26951610fa1d2b9f8d9f7c85979bed856c94
1 file changed
+66
-22
Documentation/technical/pack-protocol.txt
+66
-22
@@ -187,27 +187,28 @@ the client already is up-to-date.
187
188
Otherwise, it enters the negotiation phase, where the client and
189
server determine what the minimal packfile necessary for transport is,
190
-by telling the server what objects it wants and what objects it has,
191
-so the server can make a packfile that only contains the objects that the
192
-client needs. The client will also send a list of the capabilities it
193
-wants to be in effect, out of what the server said it could do with the
194
-first 'want' line.
190
+by telling the server what objects it wants, its shallow objects
191
+(if any), and the maximum commit depth it wants (if any). The client
192
+will also send a list of the capabilities it wants to be in effect,
193
+out of what the server said it could do with the first 'want' line.
194
195
----
196
upload-request = want-list
198
- have-list
199
- compute-end
197
+ *shallow-line
198
+ *1depth-request
199
+ flush-pkt
200
201
want-list = first-want
202
*additional-want
203
- flush-pkt
203
+
204
+ shallow-line = PKT_LINE("shallow" SP obj-id)
205
+
206
+ depth-request = PKT_LINE("deepen" SP depth)
207
208
first-want = PKT-LINE("want" SP obj-id SP capability-list LF)
209
additional-want = PKT-LINE("want" SP obj-id LF)
210
208
- have-list = *have-line
209
- have-line = PKT-LINE("have" SP obj-id LF)
210
- compute-end = flush-pkt / PKT-LINE("done")
211
+ depth = 1*DIGIT
212
----
213
214
Clients MUST send all the obj-ids it wants from the reference
@@ -216,21 +217,64 @@ discovery phase as 'want' lines. Clients MUST send at least one
217
obj-id in a 'want' command which did not appear in the response
218
obtained through ref discovery.
219
219
-If client is requesting a shallow clone, it will now send a 'deepen'
220
-line with the depth it is requesting.
220
+The client MUST write all obj-ids which it only has shallow copies
221
+of (meaning that it does not have the parents of a commit) as
222
+'shallow' lines so that the server is aware of the limitations of
223
+the client's history. Clients MUST NOT mention an obj-id which
224
+it does not know exists on the server.
225
+
226
+The client now sends the maximum commit history depth it wants for
227
+this transaction, which is the number of commits it wants from the
228
+tip of the history, if any, as a 'deepen' line. A depth of 0 is the
229
+same as not making a depth request. The client does not want to receive
230
+any commits beyond this depth, nor objects needed only to complete
231
+those commits. Commits whose parents are not received as a result are
232
+defined as shallow and marked as such in the server. This information
233
+is sent back to the client in the next step.
234
+
235
+Once all the 'want's and 'shallow's (and optional 'deepen') are
236
+transferred, clients MUST send a flush-pkt, to tell the server side
237
+that it is done sending the list.
238
+
239
+Otherwise, if the client sent a positive depth request, the server
240
+will determine which commits will and will not be shallow and
241
+send this information to the client. If the client did not request
242
+a positive depth, this step is skipped.
243
222
-Once all the "want"s (and optional 'deepen') are transferred,
223
-clients MUST send a flush-pkt, to tell the server side that it is
224
-done sending the list.
244
+----
245
+ shallow-update = *shallow-line
246
+ *unshallow-line
247
+ flush-pkt
248
226
-TODO: shallow/unshallow response and document the deepen command in the ABNF.
249
+ shallow-line = PKT-LINE("shallow" SP obj-id)
250
+
251
+ unshallow-line = PKT-LINE("unshallow" SP obj-id)
252
+----
253
+
254
+If the client has requested a positive depth, the server will compute
255
+the set of commits which are no deeper than the desired depth, starting
256
+at the client's wants. The server writes 'shallow' lines for each
257
+commit whose parents will not be sent as a result. The server writes
258
+an 'unshallow' line for each commit which the client has indicated is
259
+shallow, but is no longer shallow at the currently requested depth
260
+(that is, its parents will now be sent). The server MUST NOT mark
261
+as unshallow anything which the client has not indicated was shallow.
262
263
Now the client will send a list of the obj-ids it has using 'have'
229
-lines. In multi_ack mode, the canonical implementation will send up
230
-to 32 of these at a time, then will send a flush-pkt. The canonical
231
-implementation will skip ahead and send the next 32 immediately,
232
-so that there is always a block of 32 "in-flight on the wire" at a
233
-time.
264
+lines, so the server can make a packfile that only contains the objects
265
+that the client needs. In multi_ack mode, the canonical implementation
266
+will send up to 32 of these at a time, then will send a flush-pkt. The
267
+canonical implementation will skip ahead and send the next 32 immediately,
268
+so that there is always a block of 32 "in-flight on the wire" at a time.
269
+
270
+----
271
+ upload-haves = have-list
272
+ compute-end
273
+
274
+ have-list = *have-line
275
+ have-line = PKT-LINE("have" SP obj-id LF)
276
+ compute-end = flush-pkt / PKT-LINE("done")
277
+----
278
279
If the server reads 'have' lines, it then will respond by ACKing any
280
of the obj-ids the client said it had that the server also has. The