| Message ID | 17b0284c379e62a756e1bba008f4671f6afc0ad9.1708468374.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | de2852ab6fecad63e41982823436e66ffa3fb3a2 |
| Headers | show |
| Series | Doc placeholders | expand |
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > [verse] > -'git rev-parse' [<options>] <args>... > +'git rev-parse' [<options>] <arg>... Good. The "or more" is signalled by the ellipsis, not "args" being plural. > ---short[=length]:: > +--short[=<length>]:: > Same as `--verify` but shortens the object name to a unique > prefix with at least `length` characters. The minimum length This same comment applies throughout this patch, but in other places when we use <placeholder> in the option argument description, don't we use the same <placeholder> in text as well? I am wondering if the `length` (typeset in fixed-width) should become <length>. What do other recent[*] documentation pages commonly do? Side note: I say "recent" because rev-parse doc is one of the oldest ones that did not get typesetting attention they deserve, compared to more recent ones that got nitpicked while they were written and updated. > ---branches[=pattern]:: > ---tags[=pattern]:: > ---remotes[=pattern]:: > +--branches[=<pattern>]:: > +--tags[=<pattern>]:: > +--remotes[=<pattern>]:: > Show all branches, tags, or remote-tracking branches, > respectively (i.e., refs found in `refs/heads`, > `refs/tags`, or `refs/remotes`, respectively). Ditto. We see `pattern` that may want to become <pattern> in the description (after the post context of this hunk). > ---glob=pattern:: > +--glob=<pattern>:: > Show all refs matching the shell glob pattern `pattern`. If > the pattern does not start with `refs/`, this is automatically > prepended. If the pattern does not contain a globbing Ditto. > ---exclude-hidden=[fetch|receive|uploadpack]:: > +--exclude-hidden=(fetch|receive|uploadpack):: > Do not include refs that would be hidden by `git-fetch`, > `git-receive-pack` or `git-upload-pack` by consulting the appropriate > `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` Good. > ---since=datestring:: > ---after=datestring:: > +--since=<datestring>:: > +--after=<datestring>:: > Parse the date string, and output the corresponding > --max-age= parameter for 'git rev-list'. Good, modulo possibly "date string" -> "<datestring>". > ---until=datestring:: > ---before=datestring:: > +--until=<datestring>:: > +--before=<datestring>:: > Parse the date string, and output the corresponding > --min-age= parameter for 'git rev-list'. Ditto. > -<args>...:: > +<arg>...:: > Flags and parameters to be parsed. Good.
Le 20/02/2024 à 23:57, Junio C Hamano a écrit : > "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> [verse] >> -'git rev-parse' [<options>] <args>... >> +'git rev-parse' [<options>] <arg>... > > Good. The "or more" is signalled by the ellipsis, not "args" being > plural. > >> ---short[=length]:: >> +--short[=<length>]:: >> Same as `--verify` but shortens the object name to a unique >> prefix with at least `length` characters. The minimum length > > This same comment applies throughout this patch, but in other places > when we use <placeholder> in the option argument description, don't > we use the same <placeholder> in text as well? I am wondering if > the `length` (typeset in fixed-width) should become <length>. What > do other recent[*] documentation pages commonly do? This is another part of the inconsistences in documentation that I'd like to tackle (hopefully, not in another life). Using angle brackets for placeholders everywhere they appear is a visual link to the preceding syntax description, but may feel a bit heavy on some cases. Anyway, I'm all for applying the rule everywhere, for the sake of consistency. Backticks and single quotes are used indistinctively (by the way, asciidoctor does not process single quotes as markup) and are not used everywhere they should. Using backticks is also a good hint for translators to mean "verbatim, do not translate". Obviously, the placeholders ask for translation, so the backtick rule should not apply to them, even if another formating would be welcome : _<placeholder>_ for instance? > > Side note: I say "recent" because rev-parse doc is one of > the oldest ones that did not get typesetting attention they > deserve, compared to more recent ones that got nitpicked > while they were written and updated. > >> ---branches[=pattern]:: >> ---tags[=pattern]:: >> ---remotes[=pattern]:: >> +--branches[=<pattern>]:: >> +--tags[=<pattern>]:: >> +--remotes[=<pattern>]:: >> Show all branches, tags, or remote-tracking branches, >> respectively (i.e., refs found in `refs/heads`, >> `refs/tags`, or `refs/remotes`, respectively). > > Ditto. We see `pattern` that may want to become <pattern> in the > description (after the post context of this hunk). > >> ---glob=pattern:: >> +--glob=<pattern>:: >> Show all refs matching the shell glob pattern `pattern`. If >> the pattern does not start with `refs/`, this is automatically >> prepended. If the pattern does not contain a globbing > > Ditto. > >> ---exclude-hidden=[fetch|receive|uploadpack]:: >> +--exclude-hidden=(fetch|receive|uploadpack):: >> Do not include refs that would be hidden by `git-fetch`, >> `git-receive-pack` or `git-upload-pack` by consulting the appropriate >> `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` > > Good. > >> ---since=datestring:: >> ---after=datestring:: >> +--since=<datestring>:: >> +--after=<datestring>:: >> Parse the date string, and output the corresponding >> --max-age= parameter for 'git rev-list'. > > Good, modulo possibly "date string" -> "<datestring>". > >> ---until=datestring:: >> ---before=datestring:: >> +--until=<datestring>:: >> +--before=<datestring>:: >> Parse the date string, and output the corresponding >> --min-age= parameter for 'git rev-list'. > > Ditto. > >> -<args>...:: >> +<arg>...:: >> Flags and parameters to be parsed. > > Good.
Jean-Noël Avila <jn.avila@free.fr> writes: >>> ---short[=length]:: >>> +--short[=<length>]:: >>> Same as `--verify` but shortens the object name to a unique >>> prefix with at least `length` characters. The minimum length >> This same comment applies throughout this patch, but in other places >> when we use <placeholder> in the option argument description, don't >> we use the same <placeholder> in text as well? I am wondering if >> the `length` (typeset in fixed-width) should become <length>. What >> do other recent[*] documentation pages commonly do? > > This is another part of the inconsistences in documentation that I'd > like to tackle (hopefully, not in another life). > > Using angle brackets for placeholders everywhere they appear is a > visual link to the preceding syntax description, but may feel a bit > heavy on some cases. Anyway, I'm all for applying the rule everywhere, > for the sake of consistency. I agree that if <placeholder> is not an appropriate way to spell them in the explanation text, we would want to change them consistently everywhere, and until then, using the angle-bracketted <placeholder> that is common would be better. The text will be modified again when we decide to switch from <placeholder> to something else, so updating them now may be a wasted effort, but (1) we may decide that <placeholder> is good enough after all, or (2) it may make it easier to mechanically identify words whose mark-up should be converted if we consistently use <placeholder> now, even if we know it won't be the final mark-up. So I am inclined to say that we should first do `length` -> <length> in the body text in the short term. But I also think we should *not* do so as part of this patch, whose focus is how the option enumeration header should mark up the option arguments. > Backticks and single quotes are used indistinctively (by the way, > asciidoctor does not process single quotes as markup) and are not used > everywhere they should. Using backticks is also a good hint for > translators to mean "verbatim, do not translate". Obviously, the > placeholders ask for translation, so the backtick rule should not > apply to them, even if another formating would be welcome : > _<placeholder>_ for instance? Yes. The way AsciiDoc renders (at least HTML) an unadorned <placeholder> is not so great. In "git-add.html" manual page, we see these examples. The first one (unadorned) does not make the placeholder word stand out enough; the second one that does `<file>` makes it stand out better, but as you said, the `verbatim` mark-up is semantically wrong. https://git.github.io/htmldocs/git-add.html#:~:text=For%20more%20details%20about%20the%20%3Cpathspec%3E%20syntax https://git.github.io/htmldocs/git-add.html#:~:text=Pathspec%20is%20passed%20in%20%3Cfile%3E%20instead%20of%20commandline%20args.%20If%20%3Cfile%3E%20is%20exactly%20%2D%20then%20standard%20input%20is%20used.%20Pathspec The last part of the Documentation/CodingGuidelines document talks about how to mark up placeholders but it does not go beyond saying that they are written as <hyphen-in-between-words-in-angle-braket>. Whatever mark-up rule we decide to use, we should document it there. Thanks.
On Wednesday, 21 February 2024 18:31:30 CET Junio C Hamano wrote: > Jean-Noël Avila <jn.avila@free.fr> writes: > > >>> ---short[=length]:: > >>> +--short[=<length>]:: > >>> Same as `--verify` but shortens the object name to a unique > >>> prefix with at least `length` characters. The minimum length > >> This same comment applies throughout this patch, but in other places > >> when we use <placeholder> in the option argument description, don't > >> we use the same <placeholder> in text as well? I am wondering if > >> the `length` (typeset in fixed-width) should become <length>. What > >> do other recent[*] documentation pages commonly do? > > > > This is another part of the inconsistences in documentation that I'd > > like to tackle (hopefully, not in another life). > > > > Using angle brackets for placeholders everywhere they appear is a > > visual link to the preceding syntax description, but may feel a bit > > heavy on some cases. Anyway, I'm all for applying the rule everywhere, > > for the sake of consistency. > > I agree that if <placeholder> is not an appropriate way to spell > them in the explanation text, we would want to change them > consistently everywhere, and until then, using the angle-bracketted > <placeholder> that is common would be better. The text will be > modified again when we decide to switch from <placeholder> to > something else, so updating them now may be a wasted effort, but (1) > we may decide that <placeholder> is good enough after all, or (2) it > may make it easier to mechanically identify words whose mark-up > should be converted if we consistently use <placeholder> now, even > if we know it won't be the final mark-up. > > So I am inclined to say that we should first do `length` -> <length> > in the body text in the short term. But I also think we should > *not* do so as part of this patch, whose focus is how the option > enumeration header should mark up the option arguments. > > > Backticks and single quotes are used indistinctively (by the way, > > asciidoctor does not process single quotes as markup) and are not used > > everywhere they should. Using backticks is also a good hint for > > translators to mean "verbatim, do not translate". Obviously, the > > placeholders ask for translation, so the backtick rule should not > > apply to them, even if another formating would be welcome : > > _<placeholder>_ for instance? > > Yes. The way AsciiDoc renders (at least HTML) an unadorned <placeholder> > is not so great. > > In "git-add.html" manual page, we see these examples. The first one > (unadorned) does not make the placeholder word stand out enough; the > second one that does `<file>` makes it stand out better, but as you > said, the `verbatim` mark-up is semantically wrong. > > https://git.github.io/htmldocs/git-add.html#:~:text=For%20more%20details%20about%20the%20%3Cpathspec%3E%20syntax > > https://git.github.io/htmldocs/git-add.html#:~:text=Pathspec%20is%20passed%20in%20%3Cfile%3E%20instead%20of%20commandline%20args.%20If%20%3Cfile%3E%20is%20exactly%20%2D%20then%20standard%20input%20is%20used.%20Pathspec > > The last part of the Documentation/CodingGuidelines document talks > about how to mark up placeholders but it does not go beyond saying > that they are written as <hyphen-in-between-words-in-angle-braket>. > Whatever mark-up rule we decide to use, we should document it there. > > Thanks. > > > > Hi, I just saw that you pushed this series to 'next'. That's embarrassing because I missed other spots in the file were the formating was not correct. I was also preparing the changes of placeholders in paragraphs as suggested. Should I prepare another PR? Thanks
Junio C Hamano <gitster@pobox.com> writes: >> Backticks and single quotes are used indistinctively (by the way, >> asciidoctor does not process single quotes as markup) ... Hmph, it sounds like a bug of asciidoctor we'd need to work around? In any case, I practiced your "_<placeholder>_" rule on git-add.txt and here is how my local HTML rendition of the updated line in the first hunk in the attached patch looks like with "AsciiDoc 10.2.0". https://pasteboard.co/6koO0h0KJAjW.png The actual HTML for the above part looks like this: <div class="paragraph"><p>For more details about the <em><pathspec></em> syntax, see the <em>pathspec</em> entry in <a href="gitglossary.html">gitglossary(7)</a>.</p></div> In the first hunk, the updated "_<pathspec>_" is enclosed inside an <em>..</em> pair, which is made into "font-style: italic" via css, while 'pathspec' that remains is already inside <em>..</em>. By the way, I am getting some typesetting effect from the pair of single quotes with AsciiDoctor. Here is the rendition of the same part: https://pasteboard.co/LbDi95G8BNGv.png The <meta name="generator"> element in the generated HTML claims it is "Asciidoctor 2.0.20". The actual HTML for that piece looks like this: <p>For more details about the <em><pathspec></em> syntax, see the <em>pathspec</em> entry in <a href="gitglossary.html">gitglossary(7)</a>.</p> So, perhaps we do not have to do a lot of 'word' -> _word_ replacements, hopefully? ----- >8 --------- >8 --------- >8 --------- >8 ---- Subject: [PATCH] doc: apply the new placeholder rules to git-add documentation Signed-off-by: Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index ed44c1cb31..b73071ba47 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -63,7 +63,7 @@ OPTIONS to ignore removed files; use `--no-all` option if you want to add modified or new files but ignore removed ones. + -For more details about the <pathspec> syntax, see the 'pathspec' entry +For more details about the _<pathspec>_ syntax, see the 'pathspec' entry in linkgit:gitglossary[7]. -n:: @@ -119,10 +119,10 @@ apply to the index. See EDITING PATCHES below. -u:: --update:: Update the index just where it already has an entry matching - <pathspec>. This removes as well as modifies index entries to + _<pathspec>_. This removes as well as modifies index entries to match the working tree, but adds no new files. + -If no <pathspec> is given when `-u` option is used, all +If no _<pathspec>_ is given when `-u` option is used, all tracked files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories). @@ -131,11 +131,11 @@ subdirectories). --all:: --no-ignore-removal:: Update the index not only where the working tree has a file - matching <pathspec> but also where the index already has an + matching _<pathspec>_ but also where the index already has an entry. This adds, modifies, and removes index entries to match the working tree. + -If no <pathspec> is given when `-A` option is used, all +If no _<pathspec>_ is given when `-A` option is used, all files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories). @@ -145,11 +145,11 @@ subdirectories). Update the index by adding new files that are unknown to the index and files modified in the working tree, but ignore files that have been removed from the working tree. This - option is a no-op when no <pathspec> is used. + option is a no-op when no _<pathspec>_ is used. + This option is primarily to help users who are used to older -versions of Git, whose "git add <pathspec>..." was a synonym -for "git add --no-all <pathspec>...", i.e. ignored removed files. +versions of Git, whose "git add _<pathspec>_..." was a synonym +for "git add --no-all _<pathspec>_...", i.e. ignored removed files. -N:: --intent-to-add:: @@ -198,8 +198,8 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. unchanged. --pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec + Pathspec is passed in _<file>_ instead of commandline args. If + _<file>_ is exactly `-` then standard input is used. Pathspec elements are separated by LF or CR/LF. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
On Wednesday, 21 February 2024 23:36:24 CET Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > > >> Backticks and single quotes are used indistinctively (by the way, > >> asciidoctor does not process single quotes as markup) ... > > Hmph, it sounds like a bug of asciidoctor we'd need to work around? > > In any case, I practiced your "_<placeholder>_" rule on git-add.txt > and here is how my local HTML rendition of the updated line in the > first hunk in the attached patch looks like with "AsciiDoc 10.2.0". > > https://pasteboard.co/6koO0h0KJAjW.png > > The actual HTML for the above part looks like this: > > <div class="paragraph"><p>For more details about the > <em><pathspec></em> syntax, see the <em>pathspec</em> entry > in <a href="gitglossary.html">gitglossary(7)</a>.</p></div> > > In the first hunk, the updated "_<pathspec>_" is enclosed inside an > <em>..</em> pair, which is made into "font-style: italic" via css, > while 'pathspec' that remains is already inside <em>..</em>. > > By the way, I am getting some typesetting effect from the pair of > single quotes with AsciiDoctor. Here is the rendition of the same > part: > > https://pasteboard.co/LbDi95G8BNGv.png > > The <meta name="generator"> element in the generated HTML claims it > is "Asciidoctor 2.0.20". The actual HTML for that piece looks like > this: > > <p>For more details about the <em><pathspec></em> syntax, > see the <em>pathspec</em> entry > in <a href="gitglossary.html">gitglossary(7)</a>.</p> > > So, perhaps we do not have to do a lot of 'word' -> _word_ > replacements, hopefully? > Asciidoctor tries to "normify" the asciidoc format (https://asciidoc-wg.eclipse.org/projects/) and pushes for deprecating the 'word' markup which is a asciidoc.py legacy. See https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/ #updated-and-deprecated-asciidoc-syntax In the transition period (which is lasting), they introduce a compatibility mode with the compat-mode flag in order to support legacy content. For all I know, asciidoc.py has entered a maintenance stage where it will not support the evolutions of the standard. Should the Git documentation migrate to asciidoctor and drop the compat mode is an open question. At least, we should try to stick as much as possible to the common markup _ for emphasis. This would have the added benefit of differentiating single quotes from backticks, because single quotes would completely disappear in the end, except when a real single quote is needed. For the migration to "standard" asciidoc, I would also recommend using "=" prefix for titles instead of underlines which require changing two lines when modifying a title and are a pain for translators in languages with variable width characters. > ----- >8 --------- >8 --------- >8 --------- >8 ---- > > Subject: [PATCH] doc: apply the new placeholder rules to git-add documentation > > Signed-off-by: Junio C Hamano <gitster@pobox.com> > > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt > index ed44c1cb31..b73071ba47 100644 > --- a/Documentation/git-add.txt > +++ b/Documentation/git-add.txt > @@ -63,7 +63,7 @@ OPTIONS > to ignore removed files; use `--no-all` option if you want > to add modified or new files but ignore removed ones. > + > -For more details about the <pathspec> syntax, see the 'pathspec' entry > +For more details about the _<pathspec>_ syntax, see the 'pathspec' entry > in linkgit:gitglossary[7]. > > -n:: > @@ -119,10 +119,10 @@ apply to the index. See EDITING PATCHES below. > -u:: > --update:: > Update the index just where it already has an entry matching > - <pathspec>. This removes as well as modifies index entries to > + _<pathspec>_. This removes as well as modifies index entries to > match the working tree, but adds no new files. > + > -If no <pathspec> is given when `-u` option is used, all > +If no _<pathspec>_ is given when `-u` option is used, all > tracked files in the entire working tree are updated (old versions > of Git used to limit the update to the current directory and its > subdirectories). > @@ -131,11 +131,11 @@ subdirectories). > --all:: > --no-ignore-removal:: > Update the index not only where the working tree has a file > - matching <pathspec> but also where the index already has an > + matching _<pathspec>_ but also where the index already has an > entry. This adds, modifies, and removes index entries to > match the working tree. > + > -If no <pathspec> is given when `-A` option is used, all > +If no _<pathspec>_ is given when `-A` option is used, all > files in the entire working tree are updated (old versions > of Git used to limit the update to the current directory and its > subdirectories). > @@ -145,11 +145,11 @@ subdirectories). > Update the index by adding new files that are unknown to the > index and files modified in the working tree, but ignore > files that have been removed from the working tree. This > - option is a no-op when no <pathspec> is used. > + option is a no-op when no _<pathspec>_ is used. > + > This option is primarily to help users who are used to older > -versions of Git, whose "git add <pathspec>..." was a synonym > -for "git add --no-all <pathspec>...", i.e. ignored removed files. > +versions of Git, whose "git add _<pathspec>_..." was a synonym > +for "git add --no-all _<pathspec>_...", i.e. ignored removed files. > > -N:: > --intent-to-add:: > @@ -198,8 +198,8 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. > unchanged. > > --pathspec-from-file=<file>:: > - Pathspec is passed in `<file>` instead of commandline args. If > - `<file>` is exactly `-` then standard input is used. Pathspec > + Pathspec is passed in _<file>_ instead of commandline args. If > + _<file>_ is exactly `-` then standard input is used. Pathspec > elements are separated by LF or CR/LF. Pathspec elements can be > quoted as explained for the configuration variable `core.quotePath` > (see linkgit:git-config[1]). See also `--pathspec-file-nul` and > > This looks good to me.
Jean-Noël AVILA <jn.avila@free.fr> writes: >> So, perhaps we do not have to do a lot of 'word' -> _word_ >> replacements, hopefully? > ... At least, we > should try to stick as much as possible to the common markup _ for emphasis. OK, that clears up my confusion. Thanks. We do not want to rely on an external party indefinitely maintaining what they consider backward compatibility wart, so the mark-up migration would need to happen before it becomes too late. > This would have the added benefit of differentiating single quotes from > backticks, because single quotes would completely disappear in the end, except > when a real single quote is needed. Given enough time, yes. Or we can actively disable AsciiDoctor's compatibility mode and/or tweak asciidoc.conf to do the equivalent for AsciiDoc, to start early. Until then, we cannot really use "a real single quote", right? > For the migration to "standard" asciidoc, I would also recommend using "=" > prefix for titles instead of underlines which require changing two lines when > modifying a title and are a pain for translators in languages with variable > width characters. I personally strongly prefer the underline format because I care about readability of sources, but that is just me. Is that also getting deprecated? Thanks.
On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote: > Jean-Noël AVILA <jn.avila@free.fr> writes: > > >> So, perhaps we do not have to do a lot of 'word' -> _word_ > >> replacements, hopefully? > > > ... At least, we > > should try to stick as much as possible to the common markup _ for emphasis. > > OK, that clears up my confusion. Thanks. > > We do not want to rely on an external party indefinitely maintaining > what they consider backward compatibility wart, so the mark-up migration > would need to happen before it becomes too late. > > > This would have the added benefit of differentiating single quotes from > > backticks, because single quotes would completely disappear in the end, except > > when a real single quote is needed. > > Given enough time, yes. Or we can actively disable AsciiDoctor's > compatibility mode and/or tweak asciidoc.conf to do the equivalent > for AsciiDoc, to start early. Until then, we cannot really use "a > real single quote", right? The logic for managing single quotes as markup is that there should be a word boundary at the quote <SPC>'<letter> for opening and <letter>'<SPC> for closing, whereas for "real single quote" there's no space. This rule is "natural" when writing in English and writers don't pay attention. > > > For the migration to "standard" asciidoc, I would also recommend using "=" > > prefix for titles instead of underlines which require changing two lines when > > modifying a title and are a pain for translators in languages with variable > > width characters. > > I personally strongly prefer the underline format because I care > about readability of sources, but that is just me. Is that also > getting deprecated? > The underline format is bound to be deprecated. Right now, Asciidoctor detects this formatting to infer a switch to compat-mode. That's why markup-quote works as expected with Asciidoctor in current documents. > Thanks. > >
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 546faf90177..5d83dd36da1 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -9,7 +9,7 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- [verse] -'git rev-parse' [<options>] <args>... +'git rev-parse' [<options>] <arg>... DESCRIPTION ----------- @@ -130,7 +130,7 @@ for another option. 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, the command input is still interpreted as usual. ---short[=length]:: +--short[=<length>]:: Same as `--verify` but shortens the object name to a unique prefix with at least `length` characters. The minimum length is 4, the default is the effective value of the `core.abbrev` @@ -165,9 +165,9 @@ Options for Objects --all:: Show all refs found in `refs/`. ---branches[=pattern]:: ---tags[=pattern]:: ---remotes[=pattern]:: +--branches[=<pattern>]:: +--tags[=<pattern>]:: +--remotes[=<pattern>]:: Show all branches, tags, or remote-tracking branches, respectively (i.e., refs found in `refs/heads`, `refs/tags`, or `refs/remotes`, respectively). @@ -176,7 +176,7 @@ If a `pattern` is given, only refs matching the given shell glob are shown. If the pattern does not contain a globbing character (`?`, `*`, or `[`), it is turned into a prefix match by appending `/*`. ---glob=pattern:: +--glob=<pattern>:: Show all refs matching the shell glob pattern `pattern`. If the pattern does not start with `refs/`, this is automatically prepended. If the pattern does not contain a globbing @@ -197,7 +197,7 @@ respectively, and they must begin with `refs/` when applied to `--glob` or `--all`. If a trailing '/{asterisk}' is intended, it must be given explicitly. ---exclude-hidden=[fetch|receive|uploadpack]:: +--exclude-hidden=(fetch|receive|uploadpack):: Do not include refs that would be hidden by `git-fetch`, `git-receive-pack` or `git-upload-pack` by consulting the appropriate `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` @@ -314,17 +314,17 @@ The following options are unaffected by `--path-format`: Other Options ~~~~~~~~~~~~~ ---since=datestring:: ---after=datestring:: +--since=<datestring>:: +--after=<datestring>:: Parse the date string, and output the corresponding --max-age= parameter for 'git rev-list'. ---until=datestring:: ---before=datestring:: +--until=<datestring>:: +--before=<datestring>:: Parse the date string, and output the corresponding --min-age= parameter for 'git rev-list'. -<args>...:: +<arg>...:: Flags and parameters to be parsed.