| Message ID | Y+cBFF0OPSq8DGnA@coredump.intra.peff.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/2] doc/ls-remote: cosmetic cleanups for examples | expand |
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?
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>...]] 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`). EXAMPLES --------
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(-)