Duy NguyenI noticed that "quiet" and "agent" capabilities were missing in protocol-capabilitities.txt. I have a rough idea what they do, but I think it's best to be documented by the authors. Maybe you have some time to make a patch? -- Duy
threads / discuss / 34440
Missing capabilities in Documentation/technical/protocol-capbilities.txt
Subject: Missing capabilities in Documentation/technical/protocol-capbilities.txt
Duy Nguyen
Clemens BuchacherRe: Missing capabilities in Documentation/technical/protocol-capbilities.txt
On Mon, Jul 15, 2013 at 07:25:19PM +0700, Duy Nguyen wrote:
Show 5 quoted lines
> > I noticed that "quiet" and "agent" capabilities were missing in > protocol-capabilitities.txt. I have a rough idea what they do, but I > think it's best to be documented by the authors. Maybe you have some > time to make a patch?
Hi Duy,
I am sorry to disappoint, but if I had time to work on Git, I'd rather be writing code. I have some great ideas if you are interested. :-P
Besides, I barely even remember that it was me who implemented the "quiet" capability. In order to write documentation for it, I would have to research the implementation as much as anyone.
Cheers, Clemens
Jeff King[PATCH 0/4] protocol-capabilities documentation updates
On Mon, Jul 15, 2013 at 07:25:19PM +0700, Nguyen Thai Ngoc Duy wrote:
> I noticed that "quiet" and "agent" capabilities were missing in > protocol-capabilitities.txt. I have a rough idea what they do, but I > think it's best to be documented by the authors. Maybe you have some > time to make a patch?
Thanks for bringing it up; we should be more careful about documenting these as we add them.
I went ahead and documented them both, as I also remember the rationale for "quiet". And of course I found some other inaccuracies in the capabilities documentation while I was there. :)
[1/4]: docs: fix 'report-status' protocol capability thinko [2/4]: docs: note that receive-pack knows side-band-64k capability [3/4]: document 'agent' protocol capability [4/4]: document 'quiet' receive-pack capability
-Peff
Jeff King[PATCH 1/4] docs: fix 'report-status' protocol capability thinko
The report-status capability is understood by receive-pack, not upload-pack.
Signed-off-by: Jeff King <peff@peff.net> --- Documentation/technical/protocol-capabilities.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index b15517f..11467ff 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -168,7 +168,7 @@ report-status report-status ------------- -The upload-pack process can receive a 'report-status' capability, +The receive-pack process can receive a 'report-status' capability, which tells it that the client wants a report of what happened after a packfile upload and reference update. If the pushing client requests this capability, after unpacking and updating references the server
-- 1.8.3.rc1.30.gff0fb75
Jeff King[PATCH 2/4] docs: note that receive-pack knows side-band-64k capability
The protocol-capabilities documentation notes that any capabilities not explicitly mentioned for receive-pack work only for upload-pack.
Receive-pack has advertised and understood side-band-64k since 38a81b4 (receive-pack: Wrap status reports inside side-band-64k, 2010-02-05), but we do not mention it explicitly. Let's do so.
Note that receive-pack does not understand side-band, which was obsolete by that point.
Signed-off-by: Jeff King <peff@peff.net> --- Documentation/technical/protocol-capabilities.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 11467ff..9bc2a10 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -21,8 +21,8 @@ recognized by the receive-pack (push to server) process. The 'report-status' and 'delete-refs' capabilities are sent and recognized by the receive-pack (push to server) process. -The 'ofs-delta' capability is sent and recognized by both upload-pack -and receive-pack protocols. +The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized +by both upload-pack and receive-pack protocols. All other capabilities are only recognized by the upload-pack (fetch from server) process.
-- 1.8.3.rc1.30.gff0fb75
Jeff King[PATCH 3/4] document 'agent' protocol capability
This was added in ff5effd (include agent identifier in capability string, 2012-08-03), but neither the syntax nor the semantics were ever documented outside of the commit message.
Signed-off-by: Jeff King <peff@peff.net> --- Documentation/technical/protocol-capabilities.txt | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 9bc2a10..d35159e 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -22,7 +22,8 @@ The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized recognized by the receive-pack (push to server) process. The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized -by both upload-pack and receive-pack protocols. +by both upload-pack and receive-pack protocols. The 'agent' capability +may optionally be sent in both protocols. All other capabilities are only recognized by the upload-pack (fetch from server) process. @@ -123,6 +124,20 @@ send/read OBJ_OFS_DELTA (aka type 6) in a packfile. its base by position in pack rather than by an obj-id. That is, they can send/read OBJ_OFS_DELTA (aka type 6) in a packfile. +agent +----- + +The server may optionally send a capability of the form `agent=X` to +notify the client that the server is running version `X`. The client may +optionally return its own agent string by responding with an `agent=Y` +capability (but it MUST NOT do so if the server did not mention the +agent capability). The `X` and `Y` strings may contain any printable +ASCII characters except space (i.e., the byte range 32 < x < 127), and +are typically of the form "package/version" (e.g., "git/1.8.3.1"). The +agent strings are purely informative for statistics and debugging +purposes, and MUST NOT be used to programatically assume the presence +or absence of particular features. + shallow -------
-- 1.8.3.rc1.30.gff0fb75
Jeff King[PATCH 4/4] document 'quiet' receive-pack capability
This was added in c207e34 (fix push --quiet: add 'quiet' capability to receive-pack, 2012-01-08) but never documented.
Signed-off-by: Jeff King <peff@peff.net> --- Documentation/technical/protocol-capabilities.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index d35159e..ec131b6 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -18,7 +18,7 @@ NOT advertise capabilities it does not understand. and server advertised. As a consequence of these rules, server MUST NOT advertise capabilities it does not understand. -The 'report-status' and 'delete-refs' capabilities are sent and +The 'report-status', 'delete-refs', and 'quiet' capabilities are sent and recognized by the receive-pack (push to server) process. The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized @@ -200,3 +200,13 @@ to delete references. value of a reference update. It is not sent back by the client, it simply informs the client that it can be sent zero-id values to delete references. + +quiet +----- + +If the receive-pack server advertises the 'quiet' capability, it is +capable of silencing human-readable progress output which otherwise may +be shown when processing the received pack. A send-pack client should +respond with the 'quiet' capability to suppress server-side progress +reporting if the local progress reporting is also being suppressed +(e.g., via `push -q`, or if stderr does not go to a tty).
-- 1.8.3.rc1.30.gff0fb75
Nguyễn Thái Ngọc Duy[PATCH 5/4] document 'allow-tip-sha1-in-want' capability
See 390eb36 (upload-pack: optionally allow fetching from the tips of hidden refs - 2013-01-28) for more information.
Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> --- Maybe this too for completeness..
Documentation/technical/protocol-capabilities.txt | 7 +++++++ 1 file changed, 7 insertions(+)
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index ec131b6..31cbe07 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -210,3 +210,10 @@ be shown when processing the received pack. A send-pack client should respond with the 'quiet' capability to suppress server-side progress reporting if the local progress reporting is also being suppressed (e.g., via `push -q`, or if stderr does not go to a tty). + +allow-tip-sha1-in-want +---------------------- + +If the upload-pack server advertises this capability, fetch-pack may +send "want" lines with SHA-1s that exist at the server but are not +advertised by upload-pack.
-- 1.8.2.83.gc99314b
Junio C HamanoRe: [PATCH 5/4] document 'allow-tip-sha1-in-want' capability
Nguyễn Thái Ngọc Duy <pclouds@gmail.com> writes:
Show 6 quoted lines
> See 390eb36 (upload-pack: optionally allow fetching from the tips of > hidden refs - 2013-01-28) for more information. > > Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> > --- > Maybe this too for completeness..
You are absolutely right, and this exists only on the fetch vs upload-pack side, so there is no need to update the introductory text and the change in this patch is sufficient and complete.
Thanks.
Show 18 quoted lines
> Documentation/technical/protocol-capabilities.txt | 7 +++++++ > 1 file changed, 7 insertions(+) > > diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt > index ec131b6..31cbe07 100644 > --- a/Documentation/technical/protocol-capabilities.txt > +++ b/Documentation/technical/protocol-capabilities.txt > @@ -210,3 +210,10 @@ be shown when processing the received pack. A send-pack client should > respond with the 'quiet' capability to suppress server-side progress > reporting if the local progress reporting is also being suppressed > (e.g., via `push -q`, or if stderr does not go to a tty). > + > +allow-tip-sha1-in-want > +---------------------- > + > +If the upload-pack server advertises this capability, fetch-pack may > +send "want" lines with SHA-1s that exist at the server but are not > +advertised by upload-pack.