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@xxxxxxxx>
---
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
