Missing capabilities in Documentation/technical/protocol-capbilities.txt

Missing capabilities in Documentation/technical/protocol-capbilities.txt

[Duy Nguyen]

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

Re: Missing capabilities in Documentation/technical/protocol-capbilities.txt

[Clemens Buchacher]

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

[PATCH 0/4] protocol-capabilities documentation updates

[Jeff King]

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

[PATCH 1/4] docs: fix 'report-status' protocol capability thinko

[Jeff King]

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

[PATCH 2/4] docs: note that receive-pack knows side-band-64k capability

[Jeff King]

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

[PATCH 3/4] document 'agent' protocol capability

[Jeff King]

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

[PATCH 4/4] document 'quiet' receive-pack capability

[Jeff King]

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

[PATCH 5/4] document 'allow-tip-sha1-in-want' capability

[Nguyễn Thái Ngọc Duy]

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

Re: [PATCH 5/4] document 'allow-tip-sha1-in-want' capability

[Junio C Hamano]

Nguyễn Thái Ngọc Duy <pclouds@gmail.com> 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 <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.

>  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.