| Message ID | pull.1066.git.1635261072531.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: fix grammar rules in commands'syntax | expand |
On Tue, Oct 26, 2021 at 11:11 AM Jean-Noël Avila via GitGitGadget <gitgitgadget@gmail.com> wrote: > doc: fix grammar rules in commands'syntax Missing space. > According to the coding guidelines, the placeholders must: > * be in small letters > * enclosed in angle brackets > > Some other rules are also applied. Perhaps just mention them here? * use hyphens rather than underscores or spaces between words * indicate repetition with `...` rather than `*` were some that I saw while reading. Overall, the patch looks good. One or two notes below... > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> > --- > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > @@ -11,7 +11,7 @@ SYNOPSIS > -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] > +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] Nice to see this attention to detail. > @@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to > -'git checkout' -b|-B <new_branch> [<start point>]:: > +'git checkout' -b|-B <new-branch> [<start-point>]:: Likewise. > @@ -145,11 +145,11 @@ as `ours` (i.e. "our shared canonical history"), while what you did > --b <new_branch>:: > +-b <new-branch>:: > Create a new branch named `<new_branch>` and start it at > `<start_point>`; see linkgit:git-branch[1] for details. The names in the description need fixing too: s/_/-/g > --B <new_branch>:: > +-B <new-branch>:: > Creates the branch `<new_branch>` and start it at `<start_point>`; > if it already exists, then reset it to `<start_point>`. This is > equivalent to running "git branch" with "-f"; see Likewise: s/_/-/g > diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt > @@ -9,20 +9,20 @@ git-config - Get and set repository or global options > -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL > +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL> The commit message talks about using lowercase, so perhaps? s/URL/url/ > @@ -102,7 +102,7 @@ OPTIONS > ---get-urlmatch name URL:: > +--get-urlmatch <name> <URL>:: > When given a two-part name section.key, the value for > section.<url>.key whose <url> part matches the best to the > given URL is returned (if no such key exists, the value for Ditto. In fact, lowercase <url> is already used in the description, but not in the item line. If wanting to match other documentation files, this would also be typeset as `<url>` rather than <url> in the description text, but that change may be well outside the scope of this patch. > @@ -145,7 +145,7 @@ See also <<FILES>>. > --f config-file:: > +-f <config-file>:: > --file config-file:: Need to apply brackets around `config-file` for the `--file` option too, just as you did for short `-f`. > @@ -246,7 +246,7 @@ Valid `<type>`'s include: > ---get-colorbool name [stdout-is-tty]:: > +--get-colorbool <name> [<stdout-is-tty>]:: > > Find the color setting for `name` (e.g. `color.diff`) and output > "true" or "false". `stdout-is-tty` should be either "true" or Should you wrap `stdout-is-tty` within angle brackets within the description too? > @@ -257,7 +257,7 @@ Valid `<type>`'s include: > ---get-color name [default]:: > +--get-color <name> [<default>]:: > > Find the color configured for `name` (e.g. `color.diff.new`) and > output it as the ANSI color escape sequence to the standard And here? <name> rather than `name`? > diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt > @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials > -git credential <fill|approve|reject> > +git credential [fill|approve|reject] The original was indeed wrong but the revised text is also slightly misleading. The square brackets suggest that the "action" is optional, but in fact it's not, so this should be using parentheses: git credential (fill|approve|reject) Also, the usage text in builtin/credential.c is wrong: % git credential usage: git credential [fill|approve|reject] It should be using parentheses, as well, but fixing that may be outside the scope of this patch (and can be done later). > diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt > @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate > -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] > +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] > [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] > - [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] > + [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] > [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] > - [-r <remote>] [-R] [<CVS_module>] > + [-r <remote>] [-R] [<CVS-module>] I wonder if <commitlimit> should be changed to <commit-limit>? > diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt > @@ -12,7 +12,7 @@ SYNOPSIS > 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] > [--[no-]full] [--strict] [--verbose] [--lost-found] > [--[no-]dangling] [--[no-]progress] [--connectivity-only] > - [--[no-]name-objects] [<object>*] > + [--[no-]name-objects] [<object>...] Okay. > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt > @@ -79,7 +79,7 @@ repository. If not specified, fall back to the default name (currently > ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: > +--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]:: This feels slightly unusual; I'd have expected just plain `<octal>` without the leading `0`, and... > @@ -110,13 +110,14 @@ the repository permissions. > -'0xxx':: > +'0<octal>':: .. this would also say just `<octal>`, and... > -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will > -override users' umask(2) value (and not only loosen permissions as 'group' and > -'all' does). '0640' will create a repository which is group-readable, but not > -group-writable or accessible to others. '0660' will create a repo that is > -readable and writable to the current user and group, but inaccessible to others. > +'0<octal>' is an octal number and each file will have mode > +'0<octal>'. '0<octal>' will override users' umask(2) value (and not > +only loosen permissions as 'group' and 'all' does). '0640' will create > +a repository which is group-readable, but not group-writable or > +accessible to others. '0660' will create a repo that is readable and > +writable to the current user and group, but inaccessible to others. ... this would then go on to explain that `<octal>` "... is an octal number starting with literal `0`...". But it's subjective and others might feel differently. > diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt > @@ -81,7 +81,7 @@ produced by `--stat`, etc. > -<revision range>:: > +<revision-range>:: > Show only commits in the specified revision range. When no > <revision range> is specified, it defaults to `HEAD` (i.e. the > whole history leading to the current commit). `origin..HEAD` Also need to fix the description: s/<revision range>/<revision-range>/ > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt > @@ -10,8 +10,8 @@ SYNOPSIS > 'git ls-files' [-z] [-t] [-v] [-f] > - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* > - (-[c|d|o|i|s|u|k|m])* > + [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...] > + [-(c|d|o|i|s|u|k|m)...] I wonder if we could make it easier on users if written like this: [--cached|--deleted|--others|--blah|--blah]... [-c|-d|-o|-i|-s|-u|-k|-m]... But that's subjective. > diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt > @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files > -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > > +'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... ) I'd probably drop the leading dot in <.pack-filename>. It shouldn't be difficult for a reader to figure out that these are the files with `.pack` extension, and if they do need help understanding that, then probably better to explain in prose that <pack-filename> is a pack file with `.pack` extension. > diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt > @@ -89,7 +89,7 @@ counts both authors and co-authors. > -<revision range>:: > +<revision-range>:: > Show only commits in the specified revision range. When no > <revision range> is specified, it defaults to `HEAD` (i.e. the > whole history leading to the current commit). `origin..HEAD` Need to update the description to: s/<revision range>/<revision-range>/ > diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt > @@ -11,7 +11,7 @@ given by a list of patterns. > -'git sparse-checkout <subcommand> [options]' > +'git sparse-checkout <subcommand> [<options>...]' The addition of `...` would make more sense if it was spelled "option", but with it already being plural "options", I have trouble understanding why `...` is added. > diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt > @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area > -'git stage' args... > +'git stage' <arg>... It's subjective, but I find plain `<args>` easier to interpret than `<arg>...`. Does our documentation favor one form over the other, or is there a random mix? > diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt > @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser > -'git web{litdd}browse' [<options>] <url|file>... > +'git web{litdd}browse' [<options>] (<url>|<file>)... Good.
On Tue, Oct 26, 2021, Eric Sunshine wrote: > On Tue, Oct 26, 2021 at 11:11 AM Jean-Noël Avila via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> doc: fix grammar rules in commands'syntax > > Missing space. > >> According to the coding guidelines, the placeholders must: >> * be in small letters >> * enclosed in angle brackets >> >> Some other rules are also applied. > > Perhaps just mention them here? > > * use hyphens rather than underscores or spaces > between words There are a lot more places with spaces within placeholders. Will extend. > * indicate repetition with `...` rather than `*` > > were some that I saw while reading. > > Overall, the patch looks good. One or two notes below... Thanks for taking time to review this cumbersome patch. > >> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> >> --- >> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt >> @@ -11,7 +11,7 @@ SYNOPSIS >> -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] >> +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] > > Nice to see this attention to detail. > >> @@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to >> -'git checkout' -b|-B <new_branch> [<start point>]:: >> +'git checkout' -b|-B <new-branch> [<start-point>]:: > > Likewise. > >> @@ -145,11 +145,11 @@ as `ours` (i.e. "our shared canonical history"), while what you did >> --b <new_branch>:: >> +-b <new-branch>:: >> Create a new branch named `<new_branch>` and start it at >> `<start_point>`; see linkgit:git-branch[1] for details. > > The names in the description need fixing too: s/_/-/g Ack > >> --B <new_branch>:: >> +-B <new-branch>:: >> Creates the branch `<new_branch>` and start it at `<start_point>`; >> if it already exists, then reset it to `<start_point>`. This is >> equivalent to running "git branch" with "-f"; see > > Likewise: s/_/-/g Ack > >> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt >> @@ -9,20 +9,20 @@ git-config - Get and set repository or global options >> -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL >> +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL> > > The commit message talks about using lowercase, so perhaps? s/URL/url/ URL is not a word, but an acronym. Lowercasing it looks weird, but that's personal taste. URL appears with a lot different casings across the documents. > >> @@ -102,7 +102,7 @@ OPTIONS >> ---get-urlmatch name URL:: >> +--get-urlmatch <name> <URL>:: >> When given a two-part name section.key, the value for >> section.<url>.key whose <url> part matches the best to the >> given URL is returned (if no such key exists, the value for > > Ditto. In fact, lowercase <url> is already used in the description, > but not in the item line. > > If wanting to match other documentation files, this would also be > typeset as `<url>` rather than <url> in the description text, but that > change may be well outside the scope of this patch. > >> @@ -145,7 +145,7 @@ See also <<FILES>>. >> --f config-file:: >> +-f <config-file>:: >> --file config-file:: > > Need to apply brackets around `config-file` for the `--file` option > too, just as you did for short `-f`. > >> @@ -246,7 +246,7 @@ Valid `<type>`'s include: >> ---get-colorbool name [stdout-is-tty]:: >> +--get-colorbool <name> [<stdout-is-tty>]:: >> >> Find the color setting for `name` (e.g. `color.diff`) and output >> "true" or "false". `stdout-is-tty` should be either "true" or > > Should you wrap `stdout-is-tty` within angle brackets within the > description too? > The rules for referring to placeholder in text wasn't defined (use angle brackets or not, use monospace or not) . Usage in manpages is diverse. Logically this would be monospace for any token of the synopsis and angle bracket when it's a placeholder. However, this is a larger fixup in manpages, that would require its own patch. >> @@ -257,7 +257,7 @@ Valid `<type>`'s include: >> ---get-color name [default]:: >> +--get-color <name> [<default>]:: >> >> Find the color configured for `name` (e.g. `color.diff.new`) and >> output it as the ANSI color escape sequence to the standard > > And here? <name> rather than `name`? > >> diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt >> @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials >> -git credential <fill|approve|reject> >> +git credential [fill|approve|reject] > > The original was indeed wrong but the revised text is also slightly > misleading. The square brackets suggest that the "action" is optional, > but in fact it's not, so this should be using parentheses: > > git credential (fill|approve|reject) > > Also, the usage text in builtin/credential.c is wrong: > > % git credential > usage: git credential [fill|approve|reject] > > It should be using parentheses, as well, but fixing that may be > outside the scope of this patch (and can be done later). > >> diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt >> @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate >> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] >> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] >> [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] >> - [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] >> + [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] >> [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] >> - [-r <remote>] [-R] [<CVS_module>] >> + [-r <remote>] [-R] [<CVS-module>] > > I wonder if <commitlimit> should be changed to <commit-limit>? > >> diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt >> @@ -12,7 +12,7 @@ SYNOPSIS >> 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] >> [--[no-]full] [--strict] [--verbose] [--lost-found] >> [--[no-]dangling] [--[no-]progress] [--connectivity-only] >> - [--[no-]name-objects] [<object>*] >> + [--[no-]name-objects] [<object>...] > > Okay. > >> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt >> @@ -79,7 +79,7 @@ repository. If not specified, fall back to the default name (currently >> ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: >> +--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]:: > > This feels slightly unusual; I'd have expected just plain `<octal>` > without the leading `0`, and... > >> @@ -110,13 +110,14 @@ the repository permissions. >> -'0xxx':: >> +'0<octal>':: > > .. this would also say just `<octal>`, and... > >> -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will >> -override users' umask(2) value (and not only loosen permissions as 'group' and >> -'all' does). '0640' will create a repository which is group-readable, but not >> -group-writable or accessible to others. '0660' will create a repo that is >> -readable and writable to the current user and group, but inaccessible to others. >> +'0<octal>' is an octal number and each file will have mode >> +'0<octal>'. '0<octal>' will override users' umask(2) value (and not >> +only loosen permissions as 'group' and 'all' does). '0640' will create >> +a repository which is group-readable, but not group-writable or >> +accessible to others. '0660' will create a repo that is readable and >> +writable to the current user and group, but inaccessible to others. > > ... this would then go on to explain that `<octal>` "... is an octal > number starting with literal `0`...". > > But it's subjective and others might feel differently. > >> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt >> @@ -81,7 +81,7 @@ produced by `--stat`, etc. >> -<revision range>:: >> +<revision-range>:: >> Show only commits in the specified revision range. When no >> <revision range> is specified, it defaults to `HEAD` (i.e. the >> whole history leading to the current commit). `origin..HEAD` > > Also need to fix the description: s/<revision range>/<revision-range>/ > >> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt >> @@ -10,8 +10,8 @@ SYNOPSIS >> 'git ls-files' [-z] [-t] [-v] [-f] >> - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* >> - (-[c|d|o|i|s|u|k|m])* >> + [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...] >> + [-(c|d|o|i|s|u|k|m)...] > > I wonder if we could make it easier on users if written like this: > > [--cached|--deleted|--others|--blah|--blah]... > [-c|-d|-o|-i|-s|-u|-k|-m]... > > But that's subjective. It would better match synopsis of other commands with the following grammar which expresses alternative options as explained in the remainder of the manpage: [-c|--cached] [-d|--deleted] [-m|--modified] and so on. > >> diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt >> @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files >> -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > >> +'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... ) > > I'd probably drop the leading dot in <.pack-filename>. It shouldn't be > difficult for a reader to figure out that these are the files with > `.pack` extension, and if they do need help understanding that, then > probably better to explain in prose that <pack-filename> is a pack > file with `.pack` extension. > >> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt >> @@ -89,7 +89,7 @@ counts both authors and co-authors. >> -<revision range>:: >> +<revision-range>:: >> Show only commits in the specified revision range. When no >> <revision range> is specified, it defaults to `HEAD` (i.e. the >> whole history leading to the current commit). `origin..HEAD` > > Need to update the description to: s/<revision range>/<revision-range>/ Ack > >> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt >> @@ -11,7 +11,7 @@ given by a list of patterns. >> -'git sparse-checkout <subcommand> [options]' >> +'git sparse-checkout <subcommand> [<options>...]' > > The addition of `...` would make more sense if it was spelled > "option", but with it already being plural "options", I have trouble > understanding why `...` is added. > >> diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt >> @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area >> -'git stage' args... >> +'git stage' <arg>... > > It's subjective, but I find plain `<args>` easier to interpret than > `<arg>...`. Does our documentation favor one form over the other, or > is there a random mix? > >> diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt >> @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser >> -'git web{litdd}browse' [<options>] <url|file>... >> +'git web{litdd}browse' [<options>] (<url>|<file>)... > > Good. >
On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget <gitgitgadget@gmail.com> wrote: > > --- a/Documentation/git-archimport.txt > +++ b/Documentation/git-archimport.txt > @@ -9,8 +9,8 @@ git-archimport - Import a GNU Arch repository into Git > SYNOPSIS > -------- > [verse] > -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] > - <archive/branch>[:<git-branch>] ... > +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>] > + <archive>/<branch>[:<git-branch>]... Your rewrite makes it seem like one would write, e.g., "myarch/master" with a literal slash, whereas my initial thought was that the original tried to express something like "(<archive> | <branch>)". But I have zero experience with "GNU Arch" and git-archimport, so I can't really tell whether your rewrite is for the better or not. :-) In any case, this document goes on to write "<archive/branch>" several times. Supposedly, they would all want to be changed as well. There's also an instance of "Archive/branch identifier ..." to maybe look into. > --- a/Documentation/git-cvsimport.txt > +++ b/Documentation/git-cvsimport.txt > @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate > SYNOPSIS > -------- > [verse] > -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] > +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] > -<CVS_module>:: > +<CVS-module>:: > The CVS module you want to import. Relative to <CVSROOT>. Here's another "<CVSROOT>". > --- a/Documentation/git-http-push.txt > +++ b/Documentation/git-http-push.txt > @@ -63,16 +63,15 @@ of such patterns separated by a colon ":" (this means that a ref name > -Each pattern pair consists of the source side (before the colon) > -and the destination side (after the colon). The ref to be > -pushed is determined by finding a match that matches the source > -side, and where it is pushed is determined by using the > -destination side. > +Each pattern pair '<src>:<dst>' consists of the source side (before > +the colon) and the destination side (after the colon). The ref to be > +pushed is determined by finding a match that matches the source side, > +and where it is pushed is determined by using the destination side. This looks like the insertion of "'<src>:<dst>' early on, where the rest of the changes are just follow-on line-wrapping. I wonder if this patch could benefit from being broken into smaller pieces. Maybe a few preliminaries like "change <foo|bar|baz> to (foo|bar|baz)" and the like, then even if the final patch is "large", it will not be *as large*? But there are clearly sub-topics here, such as "change <some_arg> to <some-arg>" and "change arg to <arg>". Or maybe this doesn't make sense as an approach to cutting this patch into smaller pieces, but I thought I'd mention it. > - - It is an error if <src> does not match exactly one of the > + - It is an error if '<src>' does not match exactly one of the > local refs. > > - - If <dst> does not match any remote ref, either > + - If '<dst>' does not match any remote ref, either I believe these match Junio's preference, so ok. But again, this looks like it could go in a separate patch from a lot of these other changes as a way of keeping to somewhat focused changes. > - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* > - (-[c|d|o|i|s|u|k|m])* > + [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...] > + [-(c|d|o|i|s|u|k|m)...] Sort of cute how this saves on repeating the "--" by pulling it out. Anyway, nothing new in your patch. :-) Thanks for unifying these things. Martin
On Wed, Oct 27, 2021 at 2:56 PM Martin Ågren <martin.agren@gmail.com> wrote: > On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget > <gitgitgadget@gmail.com> wrote: > > -<CVS_module>:: > > +<CVS-module>:: > > The CVS module you want to import. Relative to <CVSROOT>. > > Here's another "<CVSROOT>". This one might need a bit of special consideration. Not only is `<CVSROOT>` an argument to the `-d` option, but CVSROOT is also an environment variable (which can be overridden by `-d`). So, perhaps this particular instance ought to be simply `CVSROOT` (with the backticks).
Le 27/10/2021 à 20:56, Martin Ågren a écrit : > On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> >> --- a/Documentation/git-archimport.txt >> +++ b/Documentation/git-archimport.txt >> @@ -9,8 +9,8 @@ git-archimport - Import a GNU Arch repository into Git >> SYNOPSIS >> -------- >> [verse] >> -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] >> - <archive/branch>[:<git-branch>] ... >> +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>] >> + <archive>/<branch>[:<git-branch>]... > > Your rewrite makes it seem like one would write, e.g., "myarch/master" > with a literal slash, whereas my initial thought was that the original > tried to express something like "(<archive> | <branch>)". But I have > zero experience with "GNU Arch" and git-archimport, so I can't really > tell whether your rewrite is for the better or not. :-) The <archive>/<branch> grammar is the one available in the usage of the command. > > In any case, this document goes on to write "<archive/branch>" several > times. Supposedly, they would all want to be changed as well. There's > also an instance of "Archive/branch identifier ..." to maybe look into. Ack. All the changes in a single commit > >> --- a/Documentation/git-cvsimport.txt >> +++ b/Documentation/git-cvsimport.txt >> @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate >> SYNOPSIS >> -------- >> [verse] >> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] >> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] > >> -<CVS_module>:: >> +<CVS-module>:: >> The CVS module you want to import. Relative to <CVSROOT>. > > Here's another "<CVSROOT>". Is this an environment variable or a placeholder? > >> --- a/Documentation/git-http-push.txt >> +++ b/Documentation/git-http-push.txt >> @@ -63,16 +63,15 @@ of such patterns separated by a colon ":" (this means that a ref name > >> -Each pattern pair consists of the source side (before the colon) >> -and the destination side (after the colon). The ref to be >> -pushed is determined by finding a match that matches the source >> -side, and where it is pushed is determined by using the >> -destination side. >> +Each pattern pair '<src>:<dst>' consists of the source side (before >> +the colon) and the destination side (after the colon). The ref to be >> +pushed is determined by finding a match that matches the source side, >> +and where it is pushed is determined by using the destination side. > > This looks like the insertion of "'<src>:<dst>' early on, where the rest > of the changes are just follow-on line-wrapping. > Strict line-wrapping doesn't work well with version control in free text. And it doesn't work well either with asciidoc, where some unlucky wrapping can generate spurious formatting. > I wonder if this patch could benefit from being broken into smaller > pieces. Maybe a few preliminaries like "change <foo|bar|baz> to > (foo|bar|baz)" and the like, then even if the final patch is "large", it > will not be *as large*? But there are clearly sub-topics here, such as > "change <some_arg> to <some-arg>" and "change arg to <arg>". Or maybe > this doesn't make sense as an approach to cutting this patch into > smaller pieces, but I thought I'd mention it. The changes are muliplying. I will split them. > >> - - It is an error if <src> does not match exactly one of the >> + - It is an error if '<src>' does not match exactly one of the >> local refs. >> >> - - If <dst> does not match any remote ref, either >> + - If '<dst>' does not match any remote ref, either > > I believe these match Junio's preference, so ok. But again, this looks > like it could go in a separate patch from a lot of these other changes > as a way of keeping to somewhat focused changes. > >> - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* >> - (-[c|d|o|i|s|u|k|m])* >> + [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...] >> + [-(c|d|o|i|s|u|k|m)...] > > Sort of cute how this saves on repeating the "--" by pulling it out. > Anyway, nothing new in your patch. :-) To me, the grammar should express at the token level (not like here), and anyway, this synopsis is not correct: even if these options are allowed to be repeated several times on the command line, this is useless and some of them have the same meaning (and this should be shown). This way of expressing the grammar induce the reader into thinking that this is some kind of inner grammar to the command. Jean-Noël
On Thu, 28 Oct 2021 at 11:32, Jean-Noël Avila <jn.avila@free.fr> wrote: > > Le 27/10/2021 à 20:56, Martin Ågren a écrit : > > On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget > > <gitgitgadget@gmail.com> wrote: > >> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] > >> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] > > > >> -<CVS_module>:: > >> +<CVS-module>:: > >> The CVS module you want to import. Relative to <CVSROOT>. > > > > Here's another "<CVSROOT>". > > Is this an environment variable or a placeholder? I don't know. I see that you've dropped this from v2. Makes sense. Martin
diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index a595a0ffeee..25d8bd2b08c 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -9,8 +9,8 @@ git-archimport - Import a GNU Arch repository into Git SYNOPSIS -------- [verse] -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] - <archive/branch>[:<git-branch>] ... +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>] + <archive>/<branch>[:<git-branch>]... DESCRIPTION ----------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index d473c9bf387..5964dcc25ed 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git checkout' [-q] [-f] [-m] [<branch>] 'git checkout' [-q] [-f] [-m] --detach [<branch>] 'git checkout' [-q] [-f] [-m] [--detach] <commit> -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>... 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul] 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] @@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to rather expensive side-effects to show only the tracking information, if exists, for the current branch. -'git checkout' -b|-B <new_branch> [<start point>]:: +'git checkout' -b|-B <new-branch> [<start-point>]:: Specifying `-b` causes a new branch to be created as if linkgit:git-branch[1] were called and then checked out. In @@ -145,11 +145,11 @@ as `ours` (i.e. "our shared canonical history"), while what you did on your side branch as `theirs` (i.e. "one contributor's work on top of it"). --b <new_branch>:: +-b <new-branch>:: Create a new branch named `<new_branch>` and start it at `<start_point>`; see linkgit:git-branch[1] for details. --B <new_branch>:: +-B <new-branch>:: Creates the branch `<new_branch>` and start it at `<start_point>`; if it already exists, then reset it to `<start_point>`. This is equivalent to running "git branch" with "-f"; see diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 5d750314b29..78dcc9171fb 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- [verse] -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] +'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff] [-S[<keyid>]] <commit>... 'git cherry-pick' (--continue | --skip | --abort | --quit) @@ -81,8 +81,8 @@ OPTIONS described above, and `-r` was to disable it. Now the default is not to do `-x` so this option is a no-op. --m parent-number:: ---mainline parent-number:: +-m <parent-number>:: +--mainline <parent-number>:: Usually you cannot cherry-pick a merge because you do not know which side of the merge should be considered the mainline. This option specifies the parent number (starting from 1) of diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 992225f6129..96330bf4001 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,20 +9,20 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]] -'git config' [<file-option>] [--type=<type>] --add name value -'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern] -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL -'git config' [<file-option>] [--fixed-value] --unset name [value-pattern] -'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern] -'git config' [<file-option>] --rename-section old_name new_name -'git config' [<file-option>] --remove-section name +'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]] +'git config' [<file-option>] [--type=<type>] --add <name> <value> +'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL> +'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>] +'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>] +'git config' [<file-option>] --rename-section <old-name> <new-name> +'git config' [<file-option>] --remove-section <name> 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [<file-option>] --get-color name [default] -'git config' [<file-option>] --get-colorbool name [stdout-is-tty] +'git config' [<file-option>] --get-color <name> [<default>] +'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>] 'git config' [<file-option>] -e | --edit DESCRIPTION @@ -102,7 +102,7 @@ OPTIONS in which section and variable names are lowercased, but subsection names are not. ---get-urlmatch name URL:: +--get-urlmatch <name> <URL>:: When given a two-part name section.key, the value for section.<url>.key whose <url> part matches the best to the given URL is returned (if no such key exists, the value for @@ -145,7 +145,7 @@ See also <<FILES>>. read from or written to if `extensions.worktreeConfig` is present. If not it's the same as `--local`. --f config-file:: +-f <config-file>:: --file config-file:: For writing options: write to the specified file rather than the repository `.git/config`. @@ -155,7 +155,7 @@ available files. + See also <<FILES>>. ---blob blob:: +--blob <blob>:: Similar to `--file` but use the given blob instead of a file. E.g. you can use 'master:.gitmodules' to read values from the file '.gitmodules' in the master branch. See "SPECIFYING REVISIONS" @@ -246,7 +246,7 @@ Valid `<type>`'s include: all queried config options with the scope of that value (local, global, system, command). ---get-colorbool name [stdout-is-tty]:: +--get-colorbool <name> [<stdout-is-tty>]:: Find the color setting for `name` (e.g. `color.diff`) and output "true" or "false". `stdout-is-tty` should be either "true" or @@ -257,7 +257,7 @@ Valid `<type>`'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color name [default]:: +--get-color <name> [<default>]:: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 206e3c5f407..fc1733a6163 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -git credential <fill|approve|reject> +git credential [fill|approve|reject] ------------------ DESCRIPTION diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 00154b6c85a..41c8a8a05c1 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- [verse] -'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] - [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID +'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>] + [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id> DESCRIPTION diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index de1ebed67d7..f47416d1c44 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate SYNOPSIS -------- [verse] -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>] [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] - [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] + [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [-r <remote>] [-R] [<CVS_module>] + [-r <remote>] [-R] [<CVS-module>] DESCRIPTION @@ -52,14 +52,14 @@ OPTIONS -v:: Verbosity: let 'cvsimport' report what it is doing. --d <CVSROOT>:: +-d <cvsroot>:: The root of the CVS archive. May be local (a simple path) or remote; currently, only the :local:, :ext: and :pserver: access methods are supported. If not given, 'git cvsimport' will try to read it from `CVS/Root`. If no such file exists, it checks for the `CVSROOT` environment variable. -<CVS_module>:: +<CVS-module>:: The CVS module you want to import. Relative to <CVSROOT>. If not given, 'git cvsimport' tries to read it from `CVS/Repository`. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bd596619c0d..5088783dccb 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] [--[no-]dangling] [--[no-]progress] [--connectivity-only] - [--[no-]name-objects] [<object>*] + [--[no-]name-objects] [<object>...] DESCRIPTION ----------- diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index c9d7e96214f..e8f3ccb4337 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- [verse] -'git gui' [<command>] [arguments] +'git gui' [<command>] [<arguments>] DESCRIPTION ----------- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 96d5f598b4b..44ea63cc6d3 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,14 +9,14 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all [--[no-]verbose]] - [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE] + [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>] 'git help' [-g|--guides] 'git help' [-c|--config] DESCRIPTION ----------- -With no options and no COMMAND or GUIDE given, the synopsis of the 'git' +With no options and no '<command>' or '<guide>' given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. @@ -33,7 +33,7 @@ variables. If an alias is given, git shows the definition of the alias on standard output. To get the manual page for the aliased command, use -`git COMMAND --help`. +`git <command> --help`. Note that `git --help ...` is identical to `git help ...` because the former is internally converted into the latter. diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index 9fa17b60e43..fa4bb6cbc3e 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP SYNOPSIS -------- [verse] -'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url> +'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url> DESCRIPTION ----------- diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index ea03a4eeb0f..6b29d38a2a6 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -63,16 +63,15 @@ of such patterns separated by a colon ":" (this means that a ref name cannot have a colon in it). A single pattern '<name>' is just a shorthand for '<name>:<name>'. -Each pattern pair consists of the source side (before the colon) -and the destination side (after the colon). The ref to be -pushed is determined by finding a match that matches the source -side, and where it is pushed is determined by using the -destination side. +Each pattern pair '<src>:<dst>' consists of the source side (before +the colon) and the destination side (after the colon). The ref to be +pushed is determined by finding a match that matches the source side, +and where it is pushed is determined by using the destination side. - - It is an error if <src> does not match exactly one of the + - It is an error if '<src>' does not match exactly one of the local refs. - - If <dst> does not match any remote ref, either + - If '<dst>' does not match any remote ref, either * it has to start with "refs/"; <dst> is used as the destination literally in this case. diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index 648a6cd78ad..18bf1a3c8ce 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository SYNOPSIS -------- [verse] -'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]] +'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]] DESCRIPTION diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index b611d80697d..99bcfc9f2c9 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -9,10 +9,10 @@ git-init - Create an empty Git repository or reinitialize an existing one SYNOPSIS -------- [verse] -'git init' [-q | --quiet] [--bare] [--template=<template_directory>] - [--separate-git-dir <git dir>] [--object-format=<format>] +'git init' [-q | --quiet] [--bare] [--template=<template-directory>] + [--separate-git-dir <git-dir>] [--object-format=<format>] [-b <branch-name> | --initial-branch=<branch-name>] - [--shared[=<permissions>]] [directory] + [--shared[=<permissions>]] [<directory>] DESCRIPTION @@ -57,12 +57,12 @@ values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. + include::object-format-disclaimer.txt[] ---template=<template_directory>:: +--template=<template-directory>:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=<git dir>:: +--separate-git-dir=<git-dir>:: Instead of initializing the repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file there containing the path to the actual @@ -79,7 +79,7 @@ repository. If not specified, fall back to the default name (currently `master`, but this is subject to change in the future; the name can be customized via the `init.defaultBranch` configuration variable). ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: +--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]:: Specify that the Git repository is to be shared amongst several users. This allows users belonging to the same group to push into that @@ -110,13 +110,14 @@ the repository permissions. Same as 'group', but make the repository readable by all users. -'0xxx':: +'0<octal>':: -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will -override users' umask(2) value (and not only loosen permissions as 'group' and -'all' does). '0640' will create a repository which is group-readable, but not -group-writable or accessible to others. '0660' will create a repo that is -readable and writable to the current user and group, but inaccessible to others. +'0<octal>' is an octal number and each file will have mode +'0<octal>'. '0<octal>' will override users' umask(2) value (and not +only loosen permissions as 'group' and 'all' does). '0640' will create +a repository which is group-readable, but not group-writable or +accessible to others. '0660' will create a repo that is readable and +writable to the current user and group, but inaccessible to others. -- By default, the configuration flag `receive.denyNonFastForwards` is enabled diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0498e7bacbe..ac8e96265c3 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -9,7 +9,7 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [<options>] [<revision range>] [[--] <path>...] +'git log' [<options>] [<revision-range>] [[--] <path>...] DESCRIPTION ----------- @@ -81,7 +81,7 @@ produced by `--stat`, etc. include::line-range-options.txt[] -<revision range>:: +<revision-range>:: Show only commits in the specified revision range. When no <revision range> is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 6d11ab506b7..64dcedce97d 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] [-f] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* - (-[c|d|o|i|s|u|k|m])* + [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...] + [-(c|d|o|i|s|u|k|m)...] [--eol] [--deduplicate] [-x <pattern>|--exclude=<pattern>] diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 2ab84a91e53..eea56b3154e 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- [verse] -'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) +'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) ) DESCRIPTION ----------- diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 38e5257b2a4..f2de6400302 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories SYNOPSIS -------- [verse] -'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>... -'git p4 sync' [<sync options>] [<p4 depot path>...] +'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>... +'git p4 sync' [<sync-options>] [<p4-depot-path>...] 'git p4 rebase' -'git p4 submit' [<submit options>] [<master branch name>] +'git p4 submit' [<submit-options>] [<master-branch-name>] DESCRIPTION diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index dbfd1f90175..f8344e1e5ba 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -13,8 +13,8 @@ SYNOPSIS [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] - [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list + [--stdout [--filter=<filter-spec>] | <base-name>] + [--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list> DESCRIPTION diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index f2869da5728..7c55c476b65 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- [verse] -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... > +'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... ) DESCRIPTION ----------- diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index ff487ff77d3..5ced7ad4f8b 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -17,12 +17,12 @@ The command takes various subcommands, and different options depending on the subcommand: [verse] -'git reflog' ['show'] [log-options] [<ref>] +'git reflog' ['show'] [<log-options>] [<ref>] 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] ref@\{specifier\}... + [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index c9c7f3065ca..5babc07f094 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] -'git shortlog' [<options>] [<revision range>] [[--] <path>...] +'git shortlog' [<options>] [<revision-range>] [[--] <path>...] git log --pretty=short | 'git shortlog' [<options>] DESCRIPTION @@ -89,7 +89,7 @@ counts both authors and co-authors. If width is `0` (zero) then indent the lines of the output without wrapping them. -<revision range>:: +<revision-range>:: Show only commits in the specified revision range. When no <revision range> is specified, it defaults to `HEAD` (i.e. the whole history leading to the current commit). `origin..HEAD` diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 42056ee9ff9..92b2ca374df 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -11,7 +11,7 @@ given by a list of patterns. SYNOPSIS -------- [verse] -'git sparse-checkout <subcommand> [options]' +'git sparse-checkout <subcommand> [<options>...]' DESCRIPTION diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt index 25bcda936db..2f6aaa75b9a 100644 --- a/Documentation/git-stage.txt +++ b/Documentation/git-stage.txt @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area SYNOPSIS -------- [verse] -'git stage' args... +'git stage' <arg>... DESCRIPTION diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 8d162b56c59..3cf0b3df04f 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser SYNOPSIS -------- [verse] -'git web{litdd}browse' [<options>] <url|file>... +'git web{litdd}browse' [<options>] (<url>|<file>)... DESCRIPTION -----------