[PATCH v3 08/11] docs/protocol-v2: clarify some ls-refs ref-prefix details
- From
Jeff King <peff@peff.net>
- Date
- Sep 15, 2021, 18:35 UTC
- Message-ID
- <YUI89iI+KRVK+YAz@coredump.intra.peff.net>
- In-Reply-To
- <YUI8z5SiyvgrDBas@coredump.intra.peff.net>
We've never documented the fact that a client can provide multiple ref-prefix capabilities. Let's describe the behavior.
We also never discussed the "best effort" nature of the prefixes. The client side of git.git has always treated them this way, filtering the result with local patterns. And indeed any client must do this, because the prefix patterns are not sufficient to express the usual refspecs (and so for "foo" we ask for "refs/heads/foo", "refs/tags/foo", and so on).
So this may be considered a change in the spec with respect to client expectations / requirements, but it's mostly codifying existing behavior.
Signed-off-by: Jeff King <peff@peff.net> --- Documentation/technical/protocol-v2.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index 213538f1d0..9347b2ad13 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -193,7 +193,11 @@ ls-refs takes in the following arguments: Show peeled tags. ref-prefix <prefix> When specified, only references having a prefix matching one of - the provided prefixes are displayed. + the provided prefixes are displayed. Multiple instances may be + given, in which case references matching any prefix will be + shown. Note that this is purely for optimization; a server MAY + show refs not matching the prefix if it chooses, and clients + should filter the result themselves. If the 'unborn' feature is advertised the following argument can be included in the client's request.
-- 2.33.0.917.g33ebf6a5f6