doc: fix grammar rules in commands' syntax

There are command expressions which do not follow the grammar syntax rules.

According to the coding guidelines, the placeholders must:

* be in small letters
* enclosed in angle brackets
* use hyphens as spaces

They also must represent tokens' meaning as atomic entities.

Some fixups for git-credential, git-ls-files, git-init and git-http-push.

changes since v1:

* split changes across simpler commits

Jean-Noël Avila (9):
doc: fix git credential synopsis
doc: split placeholders as individual tokens
doc: express grammar placeholders between angle brackets
doc: use only hyphens as word separators in placeholders
doc: git-ls-files: express options as optional alternatives
doc: use three dots for indicating repetition instead of star
doc: uniformize <URL> placeholders' case
doc: git-http-push: describe the refs as pattern pairs
doc: git-init: clarify file modes in octal.

 Documentation/date-formats.txt        |  4 +--
 Documentation/git-archimport.txt      | 14 ++++----
 Documentation/git-checkout.txt        | 36 +++++++++----------
 Documentation/git-cherry-pick.txt     |  6 ++--
 Documentation/git-clone.txt           |  8 ++---
 Documentation/git-config.txt          | 46 ++++++++++++------------
 Documentation/git-credential.txt      |  2 +-
 Documentation/git-cvsexportcommit.txt |  4 +--
 Documentation/git-cvsimport.txt       |  8 ++---
 Documentation/git-diff-files.txt      |  2 +-
 Documentation/git-diff-index.txt      |  2 +-
 Documentation/git-diff-tree.txt       |  2 +-
 Documentation/git-fsck.txt            |  2 +-
 Documentation/git-gui.txt             |  2 +-
 Documentation/git-help.txt            |  6 ++--
 Documentation/git-http-fetch.txt      |  2 +-
 Documentation/git-http-push.txt       | 15 ++++----
 Documentation/git-init-db.txt         |  2 +-
 Documentation/git-init.txt            | 26 +++++++-------
 Documentation/git-log.txt             |  8 ++---
 Documentation/git-ls-files.txt        |  6 ++--
 Documentation/git-merge-index.txt     |  2 +-
 Documentation/git-p4.txt              |  8 ++---
 Documentation/git-pack-objects.txt    |  4 +--
 Documentation/git-pack-redundant.txt  |  2 +-
 Documentation/git-reflog.txt          |  4 +--
 Documentation/git-remote.txt          |  8 ++---
 Documentation/git-request-pull.txt    |  8 ++---
 Documentation/git-shortlog.txt        |  8 ++---
 Documentation/git-sparse-checkout.txt |  2 +-
 Documentation/git-stage.txt           |  2 +-
 Documentation/git-svn.txt             |  2 +-
 Documentation/git-web--browse.txt     |  2 +-
 Documentation/gitcredentials.txt      |  4 +--
 Documentation/gitsubmodules.txt       |  2 +-
 Documentation/gitworkflows.txt        |  6 ++--
 Documentation/pretty-formats.txt      | 52 +++++++++++++--------------
 Documentation/urls-remotes.txt        |  8 ++---
 builtin/credential.c                  |  2 +-
 39 files changed, 165 insertions(+), 164 deletions(-)

base-commit: 9d530dc0024503ab4218fe6c4395b8a0aa245478
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1066%2Fjnavila%2Ffix_manpages_placeholders-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1066/jnavila/fix_manpages_placeholders-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1066

Range-diff vs v1:

  -:  ----------- >  1:  4d1fa80d471 doc: fix git credential synopsis
  -:  ----------- >  2:  0045fe6faea doc: split placeholders as individual tokens
  1:  605236f6d49 !  3:  4d2d198f572 doc: fix grammar rules in commands'syntax

@@ Metadata
Author: Jean-Noël Avila <[email protected]>

## Commit message ##
- doc: fix grammar rules in commands'syntax
+ doc: express grammar placeholders between angle brackets

- According to the coding guidelines, the placeholders must:
- * be in small letters
- * enclosed in angle brackets
-
- Some other rules are also applied.
+ This rules discerns user inputs from verbatim options in the
+ synopsis.

- ## Documentation/git-archimport.txt ##
-@@ Documentation/git-archimport.txt: 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
- -----------
-
- ## Documentation/git-checkout.txt ##
-@@ Documentation/git-checkout.txt: 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>...]
-@@ Documentation/git-checkout.txt: 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
-@@ Documentation/git-checkout.txt: 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
-
## Documentation/git-cherry-pick.txt ##
@@ Documentation/git-cherry-pick.txt: git-cherry-pick - Apply the changes introduced by some existing commits
SYNOPSIS
@@ Documentation/git-config.txt: 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
+- section.<url>.key whose <url> part matches the best to the
++ section.<URL>.key whose <URL> part matches the best to the
given URL is returned (if no such key exists, the value for
+ section.key is used as a fallback). When given just the
+ section as name, do so for all the keys in the section and
@@ Documentation/git-config.txt: See also <<FILES>>.
read from or written to if extensions.worktreeConfig is
present. If not it's the same as --local.
@@ Documentation/git-config.txt: 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
-@@ Documentation/git-config.txt: Valid <type>'s include:
+- Find the color setting for name (e.g. color.diff) and output
+- "true" or "false". stdout-is-tty should be either "true" or
++ Find the color setting for <name> (e.g. color.diff) and output
++ "true" or "false". <stdout-is-tty> should be either "true" or
+ "false", and is taken into account when configuration says
+- "auto". If stdout-is-tty is missing, then checks the standard
++ "auto". If <stdout-is-tty> is missing, then checks the standard
+ output of the command itself, and exits with status 0 if color
+ is to be used, or exits with status 1 otherwise.
When the color setting for name is undefined, the command uses color.ui as fallback.

@@ Documentation/git-config.txt: Valid <type>'s include:

Find the color configured for name (e.g. color.diff.new) and
output it as the ANSI color escape sequence to the standard
-
- ## Documentation/git-credential.txt ##
-@@ Documentation/git-credential.txt: git-credential - Retrieve and store user credentials
- SYNOPSIS
- --------
- ------------------
--git credential <fill|approve|reject>
-+git credential [fill|approve|reject]
- ------------------
+@@ Documentation/git-config.txt: Valid <type>'s include:

- DESCRIPTION
+ --default <value>::
+ When using --get, and the requested variable is not found, behave as if
+- <value> were the value assigned to the that variable. ++ <value> were the value assigned to the that variable. +
+ CONFIGURATION
+ -------------

## Documentation/git-cvsexportcommit.txt ##
@@ Documentation/git-cvsexportcommit.txt: git-cvsexportcommit - Export a single commit to a CVS checkout
@@ Documentation/git-cvsexportcommit.txt: git-cvsexportcommit - Export a single com

DESCRIPTION

- ## Documentation/git-cvsimport.txt ##
-@@ Documentation/git-cvsimport.txt: 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
-@@ Documentation/git-cvsimport.txt: 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.
-
- ## Documentation/git-fsck.txt ##
-@@ Documentation/git-fsck.txt: 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
- -----------
-
## Documentation/git-gui.txt ##
@@ Documentation/git-gui.txt: git-gui - A portable graphical interface to Git
SYNOPSIS
@@ Documentation/git-http-fetch.txt: git-http-fetch - Download from a remote Git re
DESCRIPTION
-----------

- ## Documentation/git-http-push.txt ##
-@@ Documentation/git-http-push.txt: 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.
-
- ## Documentation/git-init-db.txt ##
-@@ Documentation/git-init-db.txt: 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
-
## Documentation/git-init.txt ##
-@@ Documentation/git-init.txt: 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>]
+@@ Documentation/git-init.txt: SYNOPSIS
+ '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
-@@ Documentation/git-init.txt: 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
-@@ Documentation/git-init.txt: 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
-@@ Documentation/git-init.txt: 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
-
- ## Documentation/git-log.txt ##
-@@ Documentation/git-log.txt: git-log - Show commit logs
- SYNOPSIS
- --------
- [verse]
--'git log' [<options>] [<revision range>] [[--] <path>...]
-+'git log' [<options>] [<revision-range>] [[--] <path>...]
-
- DESCRIPTION
- -----------
-@@ Documentation/git-log.txt: 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
-
- ## Documentation/git-ls-files.txt ##
-@@ Documentation/git-ls-files.txt: 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>]
-
- ## Documentation/git-merge-index.txt ##
-@@ Documentation/git-merge-index.txt: 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
- -----------
-
- ## Documentation/git-p4.txt ##
-@@ Documentation/git-p4.txt: 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

## Documentation/git-pack-objects.txt ##
@@ Documentation/git-pack-redundant.txt: git-pack-redundant - Find redundant pack f
--------
[verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >
-+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... ) ++'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )

DESCRIPTION
-----------
@@ Documentation/git-reflog.txt: The command takes various subcommands, and differe

Reference logs, or "reflogs", record when the tips of branches and

- ## Documentation/git-shortlog.txt ##
-@@ Documentation/git-shortlog.txt: 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
-@@ Documentation/git-shortlog.txt: 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
-
## Documentation/git-sparse-checkout.txt ##
@@ Documentation/git-sparse-checkout.txt: given by a list of patterns.
SYNOPSIS
--------
[verse]
-'git sparse-checkout <subcommand> [options]'
-+'git sparse-checkout <subcommand> [<options>...]'
++'git sparse-checkout <subcommand> [<options>]'

DESCRIPTION
@@ Documentation/git-stage.txt: git-stage - Add file contents to the staging area

DESCRIPTION
-
- ## Documentation/git-web--browse.txt ##
-@@ Documentation/git-web--browse.txt: 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
- -----------

  -:  ----------- >  4:  984b6d687a2 doc: use only hyphens as word separators in placeholders
  -:  ----------- >  5:  8e078e6ea17 doc: git-ls-files: express options as optional alternatives
  -:  ----------- >  6:  0c7b1d53808 doc: use three dots for indicating repetition instead of star
  -:  ----------- >  7:  8f85da3bb4a doc: uniformize <URL> placeholders' case
  -:  ----------- >  8:  20900b019f8 doc: git-http-push: describe the refs as pattern pairs
  -:  ----------- >  9:  7eef3538f3c doc: git-init: clarify file modes in octal.

gitgitgadget