[PATCH v2 2/2] doc/ls-remote: clarify pattern format
- From
Jeff King <peff@peff.net>
- Date
- Feb 11, 2023, 04:52 UTC
- Message-ID
- <Y+cfKFz2rXLLVkjs@coredump.intra.peff.net>
- In-Reply-To
- <xmqq5yc8gbec.fsf@gitster.g>
On Fri, Feb 10, 2023 at 06:54:03PM -0800, Junio C Hamano wrote:
Show 8 quoted lines
> > '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).
Show 16 quoted lines
> > -<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