From: Junio C Hamano <gitster@pobox.com>
Date: Sat, 11 Feb 2023 02:54:03 GMT
Subject: Re: [PATCH 2/2] doc/ls-remote: clarify pattern format
Message-ID: <xmqq5yc8gbec.fsf@gitster.g>
In-Reply-To: <Y+cBFF0OPSq8DGnA@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

> We document that you can specify "refs" to ls-remote, but we don't
> explain any further than that they are "matched" as patterns. Since this
> can be interpreted in a lot of ways, let's clarify that they are
> tail-matched globs.
>
> Likewise, let's use the word "patterns" to refer to them consistently,
> rather than "refs", and mention more explicitly that only one pattern
> needs to be matched (though there is also an example already that shows
> this in action).
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-ls-remote.txt | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> index f17567945f..2a941292a4 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -11,7 +11,7 @@ SYNOPSIS
>  [verse]
>  'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>]
>  	      [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
> -	      [--symref] [<repository> [<refs>...]]
> +	      [--symref] [<repository> [<patterns>...]]

Micronit.

builtin/ls-remote.c::ls_remote_usage[] needs a matching update.

>  
>  DESCRIPTION
>  -----------
> @@ -85,11 +85,14 @@ OPTIONS
>  	either a URL or the name of a remote (see the GIT URLS and
>  	REMOTES sections of linkgit:git-fetch[1]).
>  
> -<refs>...::
> +<patterns>...::
>  	When unspecified, all references, after filtering done
> -	with --heads and --tags, are shown.  When <refs>... are
> -	specified, only references matching the given patterns
> -	are displayed.
> +	with --heads and --tags, are shown.  When <patterns>... are
> +	specified, only references matching one or more of the given
> +	patterns are displayed. Each pattern is interpreted as a glob
> +	(see `glob` in linkgit:gitglossary[7]) which is matched against
> +	the "tail" of a ref, starting from a slash separator (so `bar`
> +	matches `refs/heads/bar` but not `refs/heads/foobar`).

Good.  Is it too obvious that the pattern `refs/heads/bar` matches
the ref `refs/heads/bar`, even though it becomes fuzzy what
"starting from a slash separator" means in such a scenario?