# Missing capabilities in Documentation/technical/protocol-capbilities.txt 9 messages from 2013-07-15 to 2013-07-26. Participants: Duy Nguyen, Clemens Buchacher, Jeff King, Nguyễn Thái Ngọc Duy, Junio C Hamano. Thread: https://gitlist.dev/t/34440 ## Duy Nguyen, 2013-07-15 12:25 Subject: Missing capabilities in Documentation/technical/protocol-capbilities.txt Message-ID: URL: https://gitlist.dev/e/CACsJy8BcEfc33HNxQB%2B_msbkbcxFfqg1xOpeRxNGL_cUqruE0w%40mail.gmail.com ``` 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? -- Duy ``` ## Clemens Buchacher, 2013-07-17 11:31 Subject: Re: Missing capabilities in Documentation/technical/protocol-capbilities.txt Message-ID: <20130717113140.GA22252@ecki.lan> URL: https://gitlist.dev/e/20130717113140.GA22252%40ecki.lan In-Reply-To: ``` On Mon, Jul 15, 2013 at 07:25:19PM +0700, Duy Nguyen 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? 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, 2013-07-24 08:00 Subject: [PATCH 0/4] protocol-capabilities documentation updates Message-ID: <20130724080051.GA3890@sigill.intra.peff.net> URL: https://gitlist.dev/e/20130724080051.GA3890%40sigill.intra.peff.net In-Reply-To: ``` 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, 2013-07-24 08:01 Subject: [PATCH 1/4] docs: fix 'report-status' protocol capability thinko Message-ID: <20130724080120.GA4425@sigill.intra.peff.net> URL: https://gitlist.dev/e/20130724080120.GA4425%40sigill.intra.peff.net In-Reply-To: <20130724080051.GA3890@sigill.intra.peff.net> ``` The report-status capability is understood by receive-pack, not upload-pack. Signed-off-by: Jeff King --- 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, 2013-07-24 08:01 Subject: [PATCH 2/4] docs: note that receive-pack knows side-band-64k capability Message-ID: <20130724080159.GB4425@sigill.intra.peff.net> URL: https://gitlist.dev/e/20130724080159.GB4425%40sigill.intra.peff.net In-Reply-To: <20130724080051.GA3890@sigill.intra.peff.net> ``` 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 --- 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, 2013-07-24 08:03 Subject: [PATCH 3/4] document 'agent' protocol capability Message-ID: <20130724080313.GC4425@sigill.intra.peff.net> URL: https://gitlist.dev/e/20130724080313.GC4425%40sigill.intra.peff.net In-Reply-To: <20130724080051.GA3890@sigill.intra.peff.net> ``` 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 --- 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, 2013-07-24 08:03 Subject: [PATCH 4/4] document 'quiet' receive-pack capability Message-ID: <20130724080342.GD4425@sigill.intra.peff.net> URL: https://gitlist.dev/e/20130724080342.GD4425%40sigill.intra.peff.net In-Reply-To: <20130724080051.GA3890@sigill.intra.peff.net> ``` 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 --- 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, 2013-07-26 11:01 Subject: [PATCH 5/4] document 'allow-tip-sha1-in-want' capability Message-ID: <1374836514-17741-1-git-send-email-pclouds@gmail.com> URL: https://gitlist.dev/e/1374836514-17741-1-git-send-email-pclouds%40gmail.com In-Reply-To: <20130724080342.GD4425@sigill.intra.peff.net> ``` 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 --- 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 Hamano, 2013-07-26 15:36 Subject: Re: [PATCH 5/4] document 'allow-tip-sha1-in-want' capability Message-ID: <7vsiz12v19.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vsiz12v19.fsf%40alter.siamese.dyndns.org In-Reply-To: <1374836514-17741-1-git-send-email-pclouds@gmail.com> ``` Nguyễn Thái Ngọc Duy writes: > 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 > --- > 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. > 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. ```