[PATCH v2 2/2] doc/ls-remote: clarify pattern format

[Jeff King <peff@peff.net>]

On Fri, Feb 10, 2023 at 06:54:03PM -0800, Junio C Hamano wrote:

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

Good catch. It is more than a micronit, as it causes t0450 to fail (I
did not even think to run the tests, since it was just a doc change).

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

Ah, thank you for bringing that up. I actually meant to call attention
to that case, as when I tried "git ls-remote . refs/heads/master", it
did not match anything, which seemed to me like a bug. But in fact it is
because I don't have a master branch in my repo (I only keep my feature
branches, plus an integration branch, and always refer to yours as
origin/master), and my experiment was buggy. :)

I do think it's worth mentioning (and thankfully there is no bug to
fix).

Here's a re-roll with both changes.

-- >8 --
Subject: [PATCH] doc/ls-remote: clarify pattern format

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" (both here and in the quick "-h" help), 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 | 15 ++++++++++-----
 builtin/ls-remote.c             |  2 +-
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index f17567945f..ff3da547dd 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>...]]
 
 DESCRIPTION
 -----------
@@ -85,11 +85,16 @@ 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 either from the start of the ref
+	(so a full name like `refs/heads/foo` matches) or from a slash
+	separator (so `bar` matches `refs/heads/bar` but not
+	`refs/heads/foobar`).
 
 EXAMPLES
 --------
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index 5d5ac03871..6516177348 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -8,7 +8,7 @@
 static const char * const ls_remote_usage[] = {
 	N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
 	   "              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
-	   "              [--symref] [<repository> [<refs>...]]"),
+	   "              [--symref] [<repository> [<patterns>...]]"),
 	NULL
 };
 
-- 
2.39.1.795.g4b3688ded9