Alexander Neronskiy <zakmagnus@xxxxxxxxxx> writes:
> 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@xxxxxxxxxx>
> ---
> ÂDocumentation/technical/pack-protocol.txt |ÂÂ 87 ++++++++++++++++++++++-------
Hmmmm, why is this patch riddled with these s?
> diff --git a/Documentation/technical/pack-protocol.txt
> b/Documentation/technical/pack-protocol.txt
> index 369f91d..f576386 100644
> --- a/Documentation/technical/pack-protocol.txt
> +++ b/Documentation/technical/pack-protocol.txt
> @@ -187,26 +187,28 @@ server determine what the minimal packfile
> necessary for transport is.
Linewrapped, perhaps by your MUA.
> Once the client has the initial list of references that the server
> has, as well as the list of capabilities, it will begin telling the
> -server what objects it wants and what objects it has, so the server
> -can make a packfile that only contains the objects that the client needs.
> -The client will also send a list of the capabilities it wants to be in
> -effect, out of what the server said it could do with the first 'want' line.
> +server what objects it wants, its shallow objects (if any), and the
> +maximum commit depth it wants (if any). The client will also send a
> +list of the capabilities it wants to be in effect, out of what the
> +server said it could do with the first 'want' line.
>
> ----
> upload-request = want-list
> - have-list
> - compute-end
> + *shallow-line
> + *1depth-request
> + flush-pkt
>
> want-list = first-want
> *additional-want
> - flush-pkt
> +
> + shallow-line = PKT_LINE("shallow" SP obj-id)
> +
> + depth-request = PKT_LINE("deepen" SP depth)
>
> first-want = PKT-LINE("want" SP obj-id SP capability-list LF)
> additional-want = PKT-LINE("want" SP obj-id LF)
>
> - have-list = *have-line
> - have-line = PKT-LINE("have" SP obj-id LF)
> - compute-end = flush-pkt / PKT-LINE("done")
> + depth = 1*DIGIT
> ----
This change splits the earlier "upload-request" that consisted want-list,
have-list and compute-end into two phases. The first phase described
above is where the client tells the server what it wants, and what it
doesn't have (by giving the "shallow" boundaries), and possibly limits the
"wants" by depth. The second phase is described much later and consists of
the "have" and "done", which comes after the "shallow-update" phase (whose
description is new).
I think the separation makes sense, as there is a lot to talk about what
happens during this phase.
> Clients MUST send all the obj-ids it wants from the reference
> @@ -215,21 +217,64 @@ 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.
> +The client MUST write all obj-ids which it only has shallow copies
> +of (meaning that it does not have the parents of a commit) as
> +'shallow' lines so that the server is aware of the limitations of
> +the client's history. Clients MUST NOT mention an obj-id which
> +it does not know exists on the server.
> +
> +The client now sends the maximum commit history depth it wants for
> +this transaction, which is the number of commits it wants from the
> +tip of the history, if any, as a 'deepen' line. A depth of 0 is the
> +same as not making a depth request. The client does not want to receive
> +any commits beyond this depth, nor objects needed only to complete
> +those commits. Commits whose parents are not received as a result are
> +marked as shallow.
... on the server end and will be sent back in the shallow-update phase
below.
> +Once all the 'want's and 'shallow's (and optional 'deepen') are
> +transferred, clients MUST send a flush-pkt. If the client has all
> +the references on the server, and as much of their commit history
> +as it is interested in, client flushes and disconnects.
Hmmmmm, are you describing "everything-local then flush and all-done" in
do_fetch_pack() with the second sentence? If so, placing the description
here is misleading. In that case, I do not think any of the find-common
exchange starting from the "upload-request" phase happens.
> +Otherwise, if the client sent a positive depth request, the server
> +will determine which commits will and will not be shallow and
> +send this information to the client. If the client did not request
> +a positive depth, this step is skipped.
> -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.
> +----
> + shallow-update = *shallow-line
> + *unshallow-line
> + flush-pkt
> ...
This is not a complaint to this patch, but I had to read the above twice
to realize that the paragraph "Otherwise..." is not a continuation of the
detailed discussion of the "upload-request" phase, but is a preamble to
the next "shallow-update" phase. It might make sense to give a subsection
heading to each of the phases, like...
Packfile Negotiation
1. upload-request phase
After reference and capabilities... (preamble for this phase)
----
upload-request = want-list ... ABNF
----
The client MUST send all the ... (detailed description of this
phase)
2. shallow-update phase
When the client sent a positive depth request, the server will
determine ... (preamble for this phase)
----
shallow-update = *shallow-line ... ABNF
----
... detailed description of this phase ...
3. common ancestor discovery phase
Now the client will send a list of ...
... likewise ...
Thanks.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html