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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Feb 10, 2023 at 23:52 UTC
d9ec3b0dc0fe51b4e56df5a809d3a1f8d83b89eb
2 files changed
+11
-6
Documentation/git-ls-remote.txt
+10
-5
@@ -11,7 +11,7 @@ SYNOPSIS
11
[verse]
12
'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>]
13
[-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
14
- [--symref] [<repository> [<refs>...]]
14
+ [--symref] [<repository> [<patterns>...]]
15
16
DESCRIPTION
17
-----------
@@ -85,11 +85,16 @@ OPTIONS
85
either a URL or the name of a remote (see the GIT URLS and
86
REMOTES sections of linkgit:git-fetch[1]).
87
88
-<refs>...::
88
+<patterns>...::
89
When unspecified, all references, after filtering done
90
- with --heads and --tags, are shown. When <refs>... are
91
- specified, only references matching the given patterns
92
- are displayed.
90
+ with --heads and --tags, are shown. When <patterns>... are
91
+ specified, only references matching one or more of the given
92
+ patterns are displayed. Each pattern is interpreted as a glob
93
+ (see `glob` in linkgit:gitglossary[7]) which is matched against
94
+ the "tail" of a ref, starting either from the start of the ref
95
+ (so a full name like `refs/heads/foo` matches) or from a slash
96
+ separator (so `bar` matches `refs/heads/bar` but not
97
+ `refs/heads/foobar`).
98
99
EXAMPLES
100
--------
builtin/ls-remote.c
+1
-1
@@ -8,7 +8,7 @@
8
static const char * const ls_remote_usage[] = {
9
N_("git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n"
10
" [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]\n"
11
- " [--symref] [<repository> [<refs>...]]"),
11
+ " [--symref] [<repository> [<patterns>...]]"),
12
NULL
13
};
14