{"thread":{"id":"56788","subject":"[PATCH] doc: fix grammar rules in commands'syntax","startedAt":"2021-10-26T15:11:19Z","lastAt":"2021-11-09T17:32:16Z","messageCount":49,"participants":["Jean-Noël Avila via GitGitGadget","Eric Sunshine","Jean-Noël Avila","Martin Ågren","Junio C Hamano","Eli Schwartz","Jean-Noël AVILA","Johannes Schindelin","Johannes Altmanninger"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"439648","messageId":"pull.1066.git.1635261072531.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":null,"subject":"[PATCH] doc: fix grammar rules in commands'syntax","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-26T15:11:12Z","receivedAt":"2021-10-26T15:11:19Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nAccording to the coding guidelines, the placeholders must:\n * be in small letters\n * enclosed in angle brackets\n\nSome other rules are also applied.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n    doc: fix grammar rules in commands'syntax\n    \n    There are command expressions which do not follow the grammar syntax\n    rules.\n    \n    According to the coding guidelines, the placeholders must:\n    \n     * be in small letters\n     * enclosed in angle brackets\n    \n    Some other rules are also applied.\n    \n    Signed-off-by: Jean-Noël Avila jn.avila@free.fr\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1066%2Fjnavila%2Ffix_manpages_placeholders-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1066/jnavila/fix_manpages_placeholders-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1066\n\n Documentation/git-archimport.txt      |  4 +--\n Documentation/git-checkout.txt        |  8 +++---\n Documentation/git-cherry-pick.txt     |  6 ++---\n Documentation/git-config.txt          | 36 +++++++++++++--------------\n Documentation/git-credential.txt      |  2 +-\n Documentation/git-cvsexportcommit.txt |  4 +--\n Documentation/git-cvsimport.txt       | 10 ++++----\n Documentation/git-fsck.txt            |  2 +-\n Documentation/git-gui.txt             |  2 +-\n Documentation/git-help.txt            |  6 ++---\n Documentation/git-http-fetch.txt      |  2 +-\n Documentation/git-http-push.txt       | 13 +++++-----\n Documentation/git-init-db.txt         |  2 +-\n Documentation/git-init.txt            | 25 ++++++++++---------\n Documentation/git-log.txt             |  4 +--\n Documentation/git-ls-files.txt        |  4 +--\n Documentation/git-merge-index.txt     |  2 +-\n Documentation/git-p4.txt              |  6 ++---\n Documentation/git-pack-objects.txt    |  4 +--\n Documentation/git-pack-redundant.txt  |  2 +-\n Documentation/git-reflog.txt          |  4 +--\n Documentation/git-shortlog.txt        |  4 +--\n Documentation/git-sparse-checkout.txt |  2 +-\n Documentation/git-stage.txt           |  2 +-\n Documentation/git-web--browse.txt     |  2 +-\n 25 files changed, 79 insertions(+), 79 deletions(-)\n\ndiff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt\nindex a595a0ffeee..25d8bd2b08c 100644\n--- a/Documentation/git-archimport.txt\n+++ b/Documentation/git-archimport.txt\n@@ -9,8 +9,8 @@ git-archimport - Import a GNU Arch repository into Git\n SYNOPSIS\n --------\n [verse]\n-'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]\n-               <archive/branch>[:<git-branch>] ...\n+'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]\n+\t       <archive>/<branch>[:<git-branch>]...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d473c9bf387..5964dcc25ed 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n 'git checkout' [-q] [-f] [-m] [<branch>]\n 'git checkout' [-q] [-f] [-m] --detach [<branch>]\n 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]\n 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n@@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to\n rather expensive side-effects to show only the tracking information,\n if exists, for the current branch.\n \n-'git checkout' -b|-B <new_branch> [<start point>]::\n+'git checkout' -b|-B <new-branch> [<start-point>]::\n \n \tSpecifying `-b` causes a new branch to be created as if\n \tlinkgit:git-branch[1] were called and then checked out.  In\n@@ -145,11 +145,11 @@ as `ours` (i.e. \"our shared canonical history\"), while what you did\n on your side branch as `theirs` (i.e. \"one contributor's work on top\n of it\").\n \n--b <new_branch>::\n+-b <new-branch>::\n \tCreate a new branch named `<new_branch>` and start it at\n \t`<start_point>`; see linkgit:git-branch[1] for details.\n \n--B <new_branch>::\n+-B <new-branch>::\n \tCreates the branch `<new_branch>` and start it at `<start_point>`;\n \tif it already exists, then reset it to `<start_point>`. This is\n \tequivalent to running \"git branch\" with \"-f\"; see\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 5d750314b29..78dcc9171fb 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits\n SYNOPSIS\n --------\n [verse]\n-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]\n+'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n \t\t  [-S[<keyid>]] <commit>...\n 'git cherry-pick' (--continue | --skip | --abort | --quit)\n \n@@ -81,8 +81,8 @@ OPTIONS\n \tdescribed above, and `-r` was to disable it.  Now the\n \tdefault is not to do `-x` so this option is a no-op.\n \n--m parent-number::\n---mainline parent-number::\n+-m <parent-number>::\n+--mainline <parent-number>::\n \tUsually you cannot cherry-pick a merge because you do not know which\n \tside of the merge should be considered the mainline.  This\n \toption specifies the parent number (starting from 1) of\ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 992225f6129..96330bf4001 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -9,20 +9,20 @@ git-config - Get and set repository or global options\n SYNOPSIS\n --------\n [verse]\n-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]\n-'git config' [<file-option>] [--type=<type>] --add name value\n-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL\n-'git config' [<file-option>] [--fixed-value] --unset name [value-pattern]\n-'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern]\n-'git config' [<file-option>] --rename-section old_name new_name\n-'git config' [<file-option>] --remove-section name\n+'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]\n+'git config' [<file-option>] [--type=<type>] --add <name> <value>\n+'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>\n+'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]\n+'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]\n+'git config' [<file-option>] --rename-section <old-name> <new-name>\n+'git config' [<file-option>] --remove-section <name>\n 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list\n-'git config' [<file-option>] --get-color name [default]\n-'git config' [<file-option>] --get-colorbool name [stdout-is-tty]\n+'git config' [<file-option>] --get-color <name> [<default>]\n+'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]\n 'git config' [<file-option>] -e | --edit\n \n DESCRIPTION\n@@ -102,7 +102,7 @@ OPTIONS\n \tin which section and variable names are lowercased, but subsection\n \tnames are not.\n \n---get-urlmatch name URL::\n+--get-urlmatch <name> <URL>::\n \tWhen given a two-part name section.key, the value for\n \tsection.<url>.key whose <url> part matches the best to the\n \tgiven URL is returned (if no such key exists, the value for\n@@ -145,7 +145,7 @@ See also <<FILES>>.\n \tread from or written to if `extensions.worktreeConfig` is\n \tpresent. If not it's the same as `--local`.\n \n--f config-file::\n+-f <config-file>::\n --file config-file::\n \tFor writing options: write to the specified file rather than the\n \trepository `.git/config`.\n@@ -155,7 +155,7 @@ available files.\n +\n See also <<FILES>>.\n \n---blob blob::\n+--blob <blob>::\n \tSimilar to `--file` but use the given blob instead of a file. E.g.\n \tyou can use 'master:.gitmodules' to read values from the file\n \t'.gitmodules' in the master branch. See \"SPECIFYING REVISIONS\"\n@@ -246,7 +246,7 @@ Valid `<type>`'s include:\n \tall queried config options with the scope of that value\n \t(local, global, system, command).\n \n---get-colorbool name [stdout-is-tty]::\n+--get-colorbool <name> [<stdout-is-tty>]::\n \n \tFind the color setting for `name` (e.g. `color.diff`) and output\n \t\"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n@@ -257,7 +257,7 @@ Valid `<type>`'s include:\n \tWhen the color setting for `name` is undefined, the command uses\n \t`color.ui` as fallback.\n \n---get-color name [default]::\n+--get-color <name> [<default>]::\n \n \tFind the color configured for `name` (e.g. `color.diff.new`) and\n \toutput it as the ANSI color escape sequence to the standard\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 206e3c5f407..fc1733a6163 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials\n SYNOPSIS\n --------\n ------------------\n-git credential <fill|approve|reject>\n+git credential [fill|approve|reject]\n ------------------\n \n DESCRIPTION\ndiff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt\nindex 00154b6c85a..41c8a8a05c1 100644\n--- a/Documentation/git-cvsexportcommit.txt\n+++ b/Documentation/git-cvsexportcommit.txt\n@@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout\n SYNOPSIS\n --------\n [verse]\n-'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]\n-\t[-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID\n+'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]\n+\t[-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\nindex de1ebed67d7..f47416d1c44 100644\n--- a/Documentation/git-cvsimport.txt\n+++ b/Documentation/git-cvsimport.txt\n@@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate\n SYNOPSIS\n --------\n [verse]\n-'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n+'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n \t      [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]\n-\t      [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n+\t      [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n \t      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]\n-\t      [-r <remote>] [-R] [<CVS_module>]\n+\t      [-r <remote>] [-R] [<CVS-module>]\n \n \n DESCRIPTION\n@@ -52,14 +52,14 @@ OPTIONS\n -v::\n \tVerbosity: let 'cvsimport' report what it is doing.\n \n--d <CVSROOT>::\n+-d <cvsroot>::\n \tThe root of the CVS archive. May be local (a simple path) or remote;\n \tcurrently, only the :local:, :ext: and :pserver: access methods\n \tare supported. If not given, 'git cvsimport' will try to read it\n \tfrom `CVS/Root`. If no such file exists, it checks for the\n \t`CVSROOT` environment variable.\n \n-<CVS_module>::\n+<CVS-module>::\n \tThe CVS module you want to import. Relative to <CVSROOT>.\n \tIf not given, 'git cvsimport' tries to read it from\n \t`CVS/Repository`.\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex bd596619c0d..5088783dccb 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n \t [--[no-]full] [--strict] [--verbose] [--lost-found]\n \t [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n-\t [--[no-]name-objects] [<object>*]\n+\t [--[no-]name-objects] [<object>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt\nindex c9d7e96214f..e8f3ccb4337 100644\n--- a/Documentation/git-gui.txt\n+++ b/Documentation/git-gui.txt\n@@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git\n SYNOPSIS\n --------\n [verse]\n-'git gui' [<command>] [arguments]\n+'git gui' [<command>] [<arguments>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 96d5f598b4b..44ea63cc6d3 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all [--[no-]verbose]]\n-\t   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]\n+\t   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'\n+With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -33,7 +33,7 @@ variables.\n \n If an alias is given, git shows the definition of the alias on\n standard output. To get the manual page for the aliased command, use\n-`git COMMAND --help`.\n+`git <command> --help`.\n \n Note that `git --help ...` is identical to `git help ...` because the\n former is internally converted into the latter.\ndiff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt\nindex 9fa17b60e43..fa4bb6cbc3e 100644\n--- a/Documentation/git-http-fetch.txt\n+++ b/Documentation/git-http-fetch.txt\n@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP\n SYNOPSIS\n --------\n [verse]\n-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt\nindex ea03a4eeb0f..6b29d38a2a6 100644\n--- a/Documentation/git-http-push.txt\n+++ b/Documentation/git-http-push.txt\n@@ -63,16 +63,15 @@ of such patterns separated by a colon \":\" (this means that a ref name\n cannot have a colon in it).  A single pattern '<name>' is just a\n shorthand for '<name>:<name>'.\n \n-Each pattern pair consists of the source side (before the colon)\n-and the destination side (after the colon).  The ref to be\n-pushed is determined by finding a match that matches the source\n-side, and where it is pushed is determined by using the\n-destination side.\n+Each pattern pair '<src>:<dst>' consists of the source side (before\n+the colon) and the destination side (after the colon).  The ref to be\n+pushed is determined by finding a match that matches the source side,\n+and where it is pushed is determined by using the destination side.\n \n- - It is an error if <src> does not match exactly one of the\n+ - It is an error if '<src>' does not match exactly one of the\n    local refs.\n \n- - If <dst> does not match any remote ref, either\n+ - If '<dst>' does not match any remote ref, either\n \n    * it has to start with \"refs/\"; <dst> is used as the\n      destination literally in this case.\ndiff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt\nindex 648a6cd78ad..18bf1a3c8ce 100644\n--- a/Documentation/git-init-db.txt\n+++ b/Documentation/git-init-db.txt\n@@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository\n SYNOPSIS\n --------\n [verse]\n-'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]\n+'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex b611d80697d..99bcfc9f2c9 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -9,10 +9,10 @@ git-init - Create an empty Git repository or reinitialize an existing one\n SYNOPSIS\n --------\n [verse]\n-'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n-\t  [--separate-git-dir <git dir>] [--object-format=<format>]\n+'git init' [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t  [--separate-git-dir <git-dir>] [--object-format=<format>]\n \t  [-b <branch-name> | --initial-branch=<branch-name>]\n-\t  [--shared[=<permissions>]] [directory]\n+\t  [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\n@@ -57,12 +57,12 @@ values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.\n +\n include::object-format-disclaimer.txt[]\n \n---template=<template_directory>::\n+--template=<template-directory>::\n \n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n---separate-git-dir=<git dir>::\n+--separate-git-dir=<git-dir>::\n \n Instead of initializing the repository as a directory to either `$GIT_DIR` or\n `./.git/`, create a text file there containing the path to the actual\n@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n+--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\n@@ -110,13 +110,14 @@ the repository permissions.\n \n Same as 'group', but make the repository readable by all users.\n \n-'0xxx'::\n+'0<octal>'::\n \n-'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n-override users' umask(2) value (and not only loosen permissions as 'group' and\n-'all' does). '0640' will create a repository which is group-readable, but not\n-group-writable or accessible to others. '0660' will create a repo that is\n-readable and writable to the current user and group, but inaccessible to others.\n+'0<octal>' is an octal number and each file will have mode\n+'0<octal>'. '0<octal>' will override users' umask(2) value (and not\n+only loosen permissions as 'group' and 'all' does). '0640' will create\n+a repository which is group-readable, but not group-writable or\n+accessible to others. '0660' will create a repo that is readable and\n+writable to the current user and group, but inaccessible to others.\n --\n \n By default, the configuration flag `receive.denyNonFastForwards` is enabled\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 0498e7bacbe..ac8e96265c3 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -9,7 +9,7 @@ git-log - Show commit logs\n SYNOPSIS\n --------\n [verse]\n-'git log' [<options>] [<revision range>] [[--] <path>...]\n+'git log' [<options>] [<revision-range>] [[--] <path>...]\n \n DESCRIPTION\n -----------\n@@ -81,7 +81,7 @@ produced by `--stat`, etc.\n \n include::line-range-options.txt[]\n \n-<revision range>::\n+<revision-range>::\n \tShow only commits in the specified revision range.  When no\n \t<revision range> is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 6d11ab506b7..64dcedce97d 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -10,8 +10,8 @@ SYNOPSIS\n --------\n [verse]\n 'git ls-files' [-z] [-t] [-v] [-f]\n-\t\t(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n-\t\t(-[c|d|o|i|s|u|k|m])*\n+\t\t[--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...]\n+\t\t[-(c|d|o|i|s|u|k|m)...]\n \t\t[--eol]\n \t\t[--deduplicate]\n \t\t[-x <pattern>|--exclude=<pattern>]\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 2ab84a91e53..eea56b3154e 100644\n--- a/Documentation/git-merge-index.txt\n+++ b/Documentation/git-merge-index.txt\n@@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging\n SYNOPSIS\n --------\n [verse]\n-'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)\n+'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) )\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex 38e5257b2a4..f2de6400302 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories\n SYNOPSIS\n --------\n [verse]\n-'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...\n-'git p4 sync' [<sync options>] [<p4 depot path>...]\n+'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>...\n+'git p4 sync' [<sync-options>] [<p4-depot-path>...]\n 'git p4 rebase'\n-'git p4 submit' [<submit options>] [<master branch name>]\n+'git p4 submit' [<submit-options>] [<master-branch-name>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex dbfd1f90175..f8344e1e5ba 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -13,8 +13,8 @@ SYNOPSIS\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n \t[--local] [--incremental] [--window=<n>] [--depth=<n>]\n \t[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]\n-\t[--stdout [--filter=<filter-spec>] | base-name]\n-\t[--shallow] [--keep-true-parents] [--[no-]sparse] < object-list\n+\t[--stdout [--filter=<filter-spec>] | <base-name>]\n+\t[--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex f2869da5728..7c55c476b65 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >\n+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... )\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex ff487ff77d3..5ced7ad4f8b 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,12 +17,12 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [log-options] [<ref>]\n+'git reflog' ['show'] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\n 'git reflog delete' [--rewrite] [--updateref]\n-\t[--dry-run | -n] [--verbose] ref@\\{specifier\\}...\n+\t[--dry-run | -n] [--verbose] <ref>@\\{<specifier>\\}...\n 'git reflog exists' <ref>\n \n Reference logs, or \"reflogs\", record when the tips of branches and\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex c9c7f3065ca..5babc07f094 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output\n SYNOPSIS\n --------\n [verse]\n-'git shortlog' [<options>] [<revision range>] [[--] <path>...]\n+'git shortlog' [<options>] [<revision-range>] [[--] <path>...]\n git log --pretty=short | 'git shortlog' [<options>]\n \n DESCRIPTION\n@@ -89,7 +89,7 @@ counts both authors and co-authors.\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\n \n-<revision range>::\n+<revision-range>::\n \tShow only commits in the specified revision range.  When no\n \t<revision range> is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 42056ee9ff9..92b2ca374df 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -11,7 +11,7 @@ given by a list of patterns.\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [options]'\n+'git sparse-checkout <subcommand> [<options>...]'\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 25bcda936db..2f6aaa75b9a 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area\n SYNOPSIS\n --------\n [verse]\n-'git stage' args...\n+'git stage' <arg>...\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex 8d162b56c59..3cf0b3df04f 100644\n--- a/Documentation/git-web--browse.txt\n+++ b/Documentation/git-web--browse.txt\n@@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser\n SYNOPSIS\n --------\n [verse]\n-'git web{litdd}browse' [<options>] <url|file>...\n+'git web{litdd}browse' [<options>] (<url>|<file>)...\n \n DESCRIPTION\n -----------\n\nbase-commit: 9d530dc0024503ab4218fe6c4395b8a0aa245478\n-- \ngitgitgadget\n"},{"id":"439662","messageId":"CAPig+cQVChdH6eJGKPuRExt5TpfNWDwY95bge01dixr7jkiUuQ@mail.gmail.com","threadId":"56788","inReplyTo":"pull.1066.git.1635261072531.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: fix grammar rules in commands'syntax","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-10-26T18:21:10Z","receivedAt":"2021-10-26T18:21:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Oct 26, 2021 at 11:11 AM Jean-Noël Avila via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n> doc: fix grammar rules in commands'syntax\n\nMissing space.\n\n> According to the coding guidelines, the placeholders must:\n>  * be in small letters\n>  * enclosed in angle brackets\n>\n> Some other rules are also applied.\n\nPerhaps just mention them here?\n\n    * use hyphens rather than underscores or spaces\n      between words\n    * indicate repetition with `...` rather than `*`\n\nwere some that I saw while reading.\n\nOverall, the patch looks good. One or two notes below...\n\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> @@ -11,7 +11,7 @@ SYNOPSIS\n> -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n> +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n\nNice to see this attention to detail.\n\n> @@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to\n> -'git checkout' -b|-B <new_branch> [<start point>]::\n> +'git checkout' -b|-B <new-branch> [<start-point>]::\n\nLikewise.\n\n> @@ -145,11 +145,11 @@ as `ours` (i.e. \"our shared canonical history\"), while what you did\n> --b <new_branch>::\n> +-b <new-branch>::\n>         Create a new branch named `<new_branch>` and start it at\n>         `<start_point>`; see linkgit:git-branch[1] for details.\n\nThe names in the description need fixing too: s/_/-/g\n\n> --B <new_branch>::\n> +-B <new-branch>::\n>         Creates the branch `<new_branch>` and start it at `<start_point>`;\n>         if it already exists, then reset it to `<start_point>`. This is\n>         equivalent to running \"git branch\" with \"-f\"; see\n\nLikewise: s/_/-/g\n\n> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\n> @@ -9,20 +9,20 @@ git-config - Get and set repository or global options\n> -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL\n> +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>\n\nThe commit message talks about using lowercase, so perhaps? s/URL/url/\n\n> @@ -102,7 +102,7 @@ OPTIONS\n> ---get-urlmatch name URL::\n> +--get-urlmatch <name> <URL>::\n>         When given a two-part name section.key, the value for\n>         section.<url>.key whose <url> part matches the best to the\n>         given URL is returned (if no such key exists, the value for\n\nDitto. In fact, lowercase <url> is already used in the description,\nbut not in the item line.\n\nIf wanting to match other documentation files, this would also be\ntypeset as `<url>` rather than <url> in the description text, but that\nchange may be well outside the scope of this patch.\n\n> @@ -145,7 +145,7 @@ See also <<FILES>>.\n> --f config-file::\n> +-f <config-file>::\n>  --file config-file::\n\nNeed to apply brackets around `config-file` for the `--file` option\ntoo, just as you did for short `-f`.\n\n> @@ -246,7 +246,7 @@ Valid `<type>`'s include:\n> ---get-colorbool name [stdout-is-tty]::\n> +--get-colorbool <name> [<stdout-is-tty>]::\n>\n>         Find the color setting for `name` (e.g. `color.diff`) and output\n>         \"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n\nShould you wrap `stdout-is-tty` within angle brackets within the\ndescription too?\n\n> @@ -257,7 +257,7 @@ Valid `<type>`'s include:\n> ---get-color name [default]::\n> +--get-color <name> [<default>]::\n>\n>         Find the color configured for `name` (e.g. `color.diff.new`) and\n>         output it as the ANSI color escape sequence to the standard\n\nAnd here? <name> rather than `name`?\n\n> diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\n> @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials\n> -git credential <fill|approve|reject>\n> +git credential [fill|approve|reject]\n\nThe original was indeed wrong but the revised text is also slightly\nmisleading. The square brackets suggest that the \"action\" is optional,\nbut in fact it's not, so this should be using parentheses:\n\n    git credential (fill|approve|reject)\n\nAlso, the usage text in builtin/credential.c is wrong:\n\n    % git credential\n    usage: git credential [fill|approve|reject]\n\nIt should be using parentheses, as well, but fixing that may be\noutside the scope of this patch (and can be done later).\n\n> diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\n> @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate\n> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n>               [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]\n> -             [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n> +             [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n>               [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]\n> -             [-r <remote>] [-R] [<CVS_module>]\n> +             [-r <remote>] [-R] [<CVS-module>]\n\nI wonder if <commitlimit> should be changed to <commit-limit>?\n\n> diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\n> @@ -12,7 +12,7 @@ SYNOPSIS\n>  'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n>          [--[no-]full] [--strict] [--verbose] [--lost-found]\n>          [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n> -        [--[no-]name-objects] [<object>*]\n> +        [--[no-]name-objects] [<object>...]\n\nOkay.\n\n> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\n> @@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n> ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n> +--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]::\n\nThis feels slightly unusual; I'd have expected just plain `<octal>`\nwithout the leading `0`, and...\n\n> @@ -110,13 +110,14 @@ the repository permissions.\n> -'0xxx'::\n> +'0<octal>'::\n\n.. this would also say just `<octal>`, and...\n\n> -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n> -override users' umask(2) value (and not only loosen permissions as 'group' and\n> -'all' does). '0640' will create a repository which is group-readable, but not\n> -group-writable or accessible to others. '0660' will create a repo that is\n> -readable and writable to the current user and group, but inaccessible to others.\n> +'0<octal>' is an octal number and each file will have mode\n> +'0<octal>'. '0<octal>' will override users' umask(2) value (and not\n> +only loosen permissions as 'group' and 'all' does). '0640' will create\n> +a repository which is group-readable, but not group-writable or\n> +accessible to others. '0660' will create a repo that is readable and\n> +writable to the current user and group, but inaccessible to others.\n\n... this would then go on to explain that `<octal>` \"... is an octal\nnumber starting with literal `0`...\".\n\nBut it's subjective and others might feel differently.\n\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> @@ -81,7 +81,7 @@ produced by `--stat`, etc.\n> -<revision range>::\n> +<revision-range>::\n>         Show only commits in the specified revision range.  When no\n>         <revision range> is specified, it defaults to `HEAD` (i.e. the\n>         whole history leading to the current commit).  `origin..HEAD`\n\nAlso need to fix the description: s/<revision range>/<revision-range>/\n\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> @@ -10,8 +10,8 @@ SYNOPSIS\n>  'git ls-files' [-z] [-t] [-v] [-f]\n> -               (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n> -               (-[c|d|o|i|s|u|k|m])*\n> +               [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...]\n> +               [-(c|d|o|i|s|u|k|m)...]\n\nI wonder if we could make it easier on users if written like this:\n\n    [--cached|--deleted|--others|--blah|--blah]...\n    [-c|-d|-o|-i|-s|-u|-k|-m]...\n\nBut that's subjective.\n\n> diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\n> @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n> -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >\n> +'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... )\n\nI'd probably drop the leading dot in <.pack-filename>. It shouldn't be\ndifficult for a reader to figure out that these are the files with\n`.pack` extension, and if they do need help understanding that, then\nprobably better to explain in prose that <pack-filename> is a pack\nfile with `.pack` extension.\n\n> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\n> @@ -89,7 +89,7 @@ counts both authors and co-authors.\n> -<revision range>::\n> +<revision-range>::\n>         Show only commits in the specified revision range.  When no\n>         <revision range> is specified, it defaults to `HEAD` (i.e. the\n>         whole history leading to the current commit).  `origin..HEAD`\n\nNeed to update the description to: s/<revision range>/<revision-range>/\n\n> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\n> @@ -11,7 +11,7 @@ given by a list of patterns.\n> -'git sparse-checkout <subcommand> [options]'\n> +'git sparse-checkout <subcommand> [<options>...]'\n\nThe addition of `...` would make more sense if it was spelled\n\"option\", but with it already being plural \"options\", I have trouble\nunderstanding why `...` is added.\n\n> diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\n> @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area\n> -'git stage' args...\n> +'git stage' <arg>...\n\nIt's subjective, but I find plain `<args>` easier to interpret than\n`<arg>...`. Does our documentation favor one form over the other, or\nis there a random mix?\n\n> diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\n> @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser\n> -'git web{litdd}browse' [<options>] <url|file>...\n> +'git web{litdd}browse' [<options>] (<url>|<file>)...\n\nGood.\n"},{"id":"439773","messageId":"76e58ef5-62c4-ae9e-2557-40345734de25@free.fr","threadId":"56788","inReplyTo":"CAPig+cQVChdH6eJGKPuRExt5TpfNWDwY95bge01dixr7jkiUuQ@mail.gmail.com","subject":"Re: [PATCH] doc: fix grammar rules in commands'syntax","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-10-27T13:01:04Z","receivedAt":"2021-10-27T13:01:14Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Tue, Oct 26, 2021, Eric Sunshine wrote:\n> On Tue, Oct 26, 2021 at 11:11 AM Jean-Noël Avila via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>> doc: fix grammar rules in commands'syntax\n> \n> Missing space.\n> \n>> According to the coding guidelines, the placeholders must:\n>>  * be in small letters\n>>  * enclosed in angle brackets\n>>\n>> Some other rules are also applied.\n> \n> Perhaps just mention them here?\n> \n>     * use hyphens rather than underscores or spaces\n>       between words\n\nThere are a lot more places with spaces within placeholders. Will extend.\n\n>     * indicate repetition with `...` rather than `*`\n> \n> were some that I saw while reading.\n> \n> Overall, the patch looks good. One or two notes below...\n\nThanks for taking time to review this cumbersome patch.\n\n> \n>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>> ---\n>> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n>> @@ -11,7 +11,7 @@ SYNOPSIS\n>> -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n>> +'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n> \n> Nice to see this attention to detail.\n> \n>> @@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to\n>> -'git checkout' -b|-B <new_branch> [<start point>]::\n>> +'git checkout' -b|-B <new-branch> [<start-point>]::\n> \n> Likewise.\n> \n>> @@ -145,11 +145,11 @@ as `ours` (i.e. \"our shared canonical history\"), while what you did\n>> --b <new_branch>::\n>> +-b <new-branch>::\n>>         Create a new branch named `<new_branch>` and start it at\n>>         `<start_point>`; see linkgit:git-branch[1] for details.\n> \n> The names in the description need fixing too: s/_/-/g\n\nAck\n\n> \n>> --B <new_branch>::\n>> +-B <new-branch>::\n>>         Creates the branch `<new_branch>` and start it at `<start_point>`;\n>>         if it already exists, then reset it to `<start_point>`. This is\n>>         equivalent to running \"git branch\" with \"-f\"; see\n> \n> Likewise: s/_/-/g\n\nAck\n\n> \n>> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\n>> @@ -9,20 +9,20 @@ git-config - Get and set repository or global options\n>> -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL\n>> +'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>\n> \n> The commit message talks about using lowercase, so perhaps? s/URL/url/\n\n\nURL is not a word, but an acronym. Lowercasing it looks weird, but\nthat's personal taste. URL appears with a lot different casings across\nthe documents.\n\n\n> \n>> @@ -102,7 +102,7 @@ OPTIONS\n>> ---get-urlmatch name URL::\n>> +--get-urlmatch <name> <URL>::\n>>         When given a two-part name section.key, the value for\n>>         section.<url>.key whose <url> part matches the best to the\n>>         given URL is returned (if no such key exists, the value for\n> \n> Ditto. In fact, lowercase <url> is already used in the description,\n> but not in the item line.\n> \n> If wanting to match other documentation files, this would also be\n> typeset as `<url>` rather than <url> in the description text, but that\n> change may be well outside the scope of this patch.\n> \n>> @@ -145,7 +145,7 @@ See also <<FILES>>.\n>> --f config-file::\n>> +-f <config-file>::\n>>  --file config-file::\n> \n> Need to apply brackets around `config-file` for the `--file` option\n> too, just as you did for short `-f`.\n> \n>> @@ -246,7 +246,7 @@ Valid `<type>`'s include:\n>> ---get-colorbool name [stdout-is-tty]::\n>> +--get-colorbool <name> [<stdout-is-tty>]::\n>>\n>>         Find the color setting for `name` (e.g. `color.diff`) and output\n>>         \"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n> \n> Should you wrap `stdout-is-tty` within angle brackets within the\n> description too?\n> \n\nThe rules for referring to placeholder in text wasn't defined (use angle\nbrackets or not, use monospace or not) . Usage in manpages is diverse.\nLogically this would be monospace for any token of the synopsis and\nangle bracket when it's a placeholder.\n\nHowever, this is a larger fixup in manpages, that would require its own\npatch.\n\n>> @@ -257,7 +257,7 @@ Valid `<type>`'s include:\n>> ---get-color name [default]::\n>> +--get-color <name> [<default>]::\n>>\n>>         Find the color configured for `name` (e.g. `color.diff.new`) and\n>>         output it as the ANSI color escape sequence to the standard\n> \n> And here? <name> rather than `name`?\n> \n>> diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\n>> @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials\n>> -git credential <fill|approve|reject>\n>> +git credential [fill|approve|reject]\n> \n> The original was indeed wrong but the revised text is also slightly\n> misleading. The square brackets suggest that the \"action\" is optional,\n> but in fact it's not, so this should be using parentheses:\n> \n>     git credential (fill|approve|reject)\n> \n> Also, the usage text in builtin/credential.c is wrong:\n> \n>     % git credential\n>     usage: git credential [fill|approve|reject]\n> \n> It should be using parentheses, as well, but fixing that may be\n> outside the scope of this patch (and can be done later).\n> \n>> diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\n>> @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate\n>> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n>> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n>>               [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]\n>> -             [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n>> +             [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n>>               [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]\n>> -             [-r <remote>] [-R] [<CVS_module>]\n>> +             [-r <remote>] [-R] [<CVS-module>]\n> \n> I wonder if <commitlimit> should be changed to <commit-limit>?\n> \n>> diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\n>> @@ -12,7 +12,7 @@ SYNOPSIS\n>>  'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n>>          [--[no-]full] [--strict] [--verbose] [--lost-found]\n>>          [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n>> -        [--[no-]name-objects] [<object>*]\n>> +        [--[no-]name-objects] [<object>...]\n> \n> Okay.\n> \n>> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\n>> @@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n>> ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n>> +--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]::\n> \n> This feels slightly unusual; I'd have expected just plain `<octal>`\n> without the leading `0`, and...\n> \n>> @@ -110,13 +110,14 @@ the repository permissions.\n>> -'0xxx'::\n>> +'0<octal>'::\n> \n> .. this would also say just `<octal>`, and...\n> \n>> -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n>> -override users' umask(2) value (and not only loosen permissions as 'group' and\n>> -'all' does). '0640' will create a repository which is group-readable, but not\n>> -group-writable or accessible to others. '0660' will create a repo that is\n>> -readable and writable to the current user and group, but inaccessible to others.\n>> +'0<octal>' is an octal number and each file will have mode\n>> +'0<octal>'. '0<octal>' will override users' umask(2) value (and not\n>> +only loosen permissions as 'group' and 'all' does). '0640' will create\n>> +a repository which is group-readable, but not group-writable or\n>> +accessible to others. '0660' will create a repo that is readable and\n>> +writable to the current user and group, but inaccessible to others.\n> \n> ... this would then go on to explain that `<octal>` \"... is an octal\n> number starting with literal `0`...\".\n> \n> But it's subjective and others might feel differently.\n> \n>> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n>> @@ -81,7 +81,7 @@ produced by `--stat`, etc.\n>> -<revision range>::\n>> +<revision-range>::\n>>         Show only commits in the specified revision range.  When no\n>>         <revision range> is specified, it defaults to `HEAD` (i.e. the\n>>         whole history leading to the current commit).  `origin..HEAD`\n> \n> Also need to fix the description: s/<revision range>/<revision-range>/\n> \n>> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n>> @@ -10,8 +10,8 @@ SYNOPSIS\n>>  'git ls-files' [-z] [-t] [-v] [-f]\n>> -               (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n>> -               (-[c|d|o|i|s|u|k|m])*\n>> +               [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...]\n>> +               [-(c|d|o|i|s|u|k|m)...]\n> \n> I wonder if we could make it easier on users if written like this:\n> \n>     [--cached|--deleted|--others|--blah|--blah]...\n>     [-c|-d|-o|-i|-s|-u|-k|-m]...\n> \n> But that's subjective.\n\nIt would better match synopsis of other commands with the following\ngrammar which expresses alternative options as explained in the\nremainder of the manpage:\n\n[-c|--cached] [-d|--deleted] [-m|--modified] and so on.\n\n> \n>> diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\n>> @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n>> -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >\n>> +'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... )\n> \n> I'd probably drop the leading dot in <.pack-filename>. It shouldn't be\n> difficult for a reader to figure out that these are the files with\n> `.pack` extension, and if they do need help understanding that, then\n> probably better to explain in prose that <pack-filename> is a pack\n> file with `.pack` extension.\n> \n>> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\n>> @@ -89,7 +89,7 @@ counts both authors and co-authors.\n>> -<revision range>::\n>> +<revision-range>::\n>>         Show only commits in the specified revision range.  When no\n>>         <revision range> is specified, it defaults to `HEAD` (i.e. the\n>>         whole history leading to the current commit).  `origin..HEAD`\n> \n> Need to update the description to: s/<revision range>/<revision-range>/\n\nAck\n\n> \n>> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\n>> @@ -11,7 +11,7 @@ given by a list of patterns.\n>> -'git sparse-checkout <subcommand> [options]'\n>> +'git sparse-checkout <subcommand> [<options>...]'\n> \n> The addition of `...` would make more sense if it was spelled\n> \"option\", but with it already being plural \"options\", I have trouble\n> understanding why `...` is added.\n> \n>> diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\n>> @@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area\n>> -'git stage' args...\n>> +'git stage' <arg>...\n> \n> It's subjective, but I find plain `<args>` easier to interpret than\n> `<arg>...`. Does our documentation favor one form over the other, or\n> is there a random mix?\n> \n>> diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\n>> @@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser\n>> -'git web{litdd}browse' [<options>] <url|file>...\n>> +'git web{litdd}browse' [<options>] (<url>|<file>)...\n> \n> Good.\n> \n\n"},{"id":"439810","messageId":"CAN0heSpRZy3+jyc09NEj4NJk4zN4X_RyVk33F5c6tyUE2qMGzQ@mail.gmail.com","threadId":"56788","inReplyTo":"pull.1066.git.1635261072531.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: fix grammar rules in commands'syntax","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-10-27T18:56:07Z","receivedAt":"2021-10-27T18:56:22Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> --- a/Documentation/git-archimport.txt\n> +++ b/Documentation/git-archimport.txt\n> @@ -9,8 +9,8 @@ git-archimport - Import a GNU Arch repository into Git\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]\n> -               <archive/branch>[:<git-branch>] ...\n> +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]\n> +              <archive>/<branch>[:<git-branch>]...\n\nYour rewrite makes it seem like one would write, e.g., \"myarch/master\"\nwith a literal slash, whereas my initial thought was that the original\ntried to express something like \"(<archive> | <branch>)\". But I have\nzero experience with \"GNU Arch\" and git-archimport, so I can't really\ntell whether your rewrite is for the better or not. :-)\n\nIn any case, this document goes on to write \"<archive/branch>\" several\ntimes. Supposedly, they would all want to be changed as well. There's\nalso an instance of \"Archive/branch identifier ...\" to maybe look into.\n\n> --- a/Documentation/git-cvsimport.txt\n> +++ b/Documentation/git-cvsimport.txt\n> @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n\n> -<CVS_module>::\n> +<CVS-module>::\n>         The CVS module you want to import. Relative to <CVSROOT>.\n\nHere's another \"<CVSROOT>\".\n\n> --- a/Documentation/git-http-push.txt\n> +++ b/Documentation/git-http-push.txt\n> @@ -63,16 +63,15 @@ of such patterns separated by a colon \":\" (this means that a ref name\n\n> -Each pattern pair consists of the source side (before the colon)\n> -and the destination side (after the colon).  The ref to be\n> -pushed is determined by finding a match that matches the source\n> -side, and where it is pushed is determined by using the\n> -destination side.\n> +Each pattern pair '<src>:<dst>' consists of the source side (before\n> +the colon) and the destination side (after the colon).  The ref to be\n> +pushed is determined by finding a match that matches the source side,\n> +and where it is pushed is determined by using the destination side.\n\nThis looks like the insertion of \"'<src>:<dst>' early on, where the rest\nof the changes are just follow-on line-wrapping.\n\nI wonder if this patch could benefit from being broken into smaller\npieces. Maybe a few preliminaries like \"change <foo|bar|baz> to\n(foo|bar|baz)\" and the like, then even if the final patch is \"large\", it\nwill not be *as large*? But there are clearly sub-topics here, such as\n\"change <some_arg> to <some-arg>\" and \"change arg to <arg>\". Or maybe\nthis doesn't make sense as an approach to cutting this patch into\nsmaller pieces, but I thought I'd mention it.\n\n> - - It is an error if <src> does not match exactly one of the\n> + - It is an error if '<src>' does not match exactly one of the\n>     local refs.\n>\n> - - If <dst> does not match any remote ref, either\n> + - If '<dst>' does not match any remote ref, either\n\nI believe these match Junio's preference, so ok. But again, this looks\nlike it could go in a separate patch from a lot of these other changes\nas a way of keeping to somewhat focused changes.\n\n> -               (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n> -               (-[c|d|o|i|s|u|k|m])*\n> +               [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...]\n> +               [-(c|d|o|i|s|u|k|m)...]\n\nSort of cute how this saves on repeating the \"--\" by pulling it out.\nAnyway, nothing new in your patch. :-)\n\nThanks for unifying these things.\n\nMartin\n"},{"id":"439825","messageId":"CAPig+cRUz1x7v=CRseWrLiN2nHX-sE=pMeMH1gqW0z5ZZTt0kw@mail.gmail.com","threadId":"56788","inReplyTo":"CAN0heSpRZy3+jyc09NEj4NJk4zN4X_RyVk33F5c6tyUE2qMGzQ@mail.gmail.com","subject":"Re: [PATCH] doc: fix grammar rules in commands'syntax","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-10-27T20:08:18Z","receivedAt":"2021-10-27T20:08:32Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Oct 27, 2021 at 2:56 PM Martin Ågren <martin.agren@gmail.com> wrote:\n> On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n> > -<CVS_module>::\n> > +<CVS-module>::\n> >         The CVS module you want to import. Relative to <CVSROOT>.\n>\n> Here's another \"<CVSROOT>\".\n\nThis one might need a bit of special consideration. Not only is\n`<CVSROOT>` an argument to the `-d` option, but CVSROOT is also an\nenvironment variable (which can be overridden by `-d`). So, perhaps\nthis particular instance ought to be simply `CVSROOT` (with the\nbackticks).\n"},{"id":"439866","messageId":"819ab0ed-8a99-2987-79c9-88cd1118b51b@free.fr","threadId":"56788","inReplyTo":"CAN0heSpRZy3+jyc09NEj4NJk4zN4X_RyVk33F5c6tyUE2qMGzQ@mail.gmail.com","subject":"Re: [PATCH] doc: fix grammar rules in commands'syntax","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-10-28T09:31:57Z","receivedAt":"2021-10-28T09:32:06Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 27/10/2021 à 20:56, Martin Ågren a écrit :\n> On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>>\n>> --- a/Documentation/git-archimport.txt\n>> +++ b/Documentation/git-archimport.txt\n>> @@ -9,8 +9,8 @@ git-archimport - Import a GNU Arch repository into Git\n>>  SYNOPSIS\n>>  --------\n>>  [verse]\n>> -'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]\n>> -               <archive/branch>[:<git-branch>] ...\n>> +'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]\n>> +              <archive>/<branch>[:<git-branch>]...\n> \n> Your rewrite makes it seem like one would write, e.g., \"myarch/master\"\n> with a literal slash, whereas my initial thought was that the original\n> tried to express something like \"(<archive> | <branch>)\". But I have\n> zero experience with \"GNU Arch\" and git-archimport, so I can't really\n> tell whether your rewrite is for the better or not. :-)\n\nThe <archive>/<branch> grammar is the one available in the usage of the\ncommand.\n\n\n> \n> In any case, this document goes on to write \"<archive/branch>\" several\n> times. Supposedly, they would all want to be changed as well. There's\n> also an instance of \"Archive/branch identifier ...\" to maybe look into.\n\nAck. All the changes in a single commit\n\n> \n>> --- a/Documentation/git-cvsimport.txt\n>> +++ b/Documentation/git-cvsimport.txt\n>> @@ -9,11 +9,11 @@ git-cvsimport - Salvage your data out of another SCM people love to hate\n>>  SYNOPSIS\n>>  --------\n>>  [verse]\n>> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n>> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n> \n>> -<CVS_module>::\n>> +<CVS-module>::\n>>         The CVS module you want to import. Relative to <CVSROOT>.\n> \n> Here's another \"<CVSROOT>\".\n\nIs this an environment variable or a placeholder?\n\n> \n>> --- a/Documentation/git-http-push.txt\n>> +++ b/Documentation/git-http-push.txt\n>> @@ -63,16 +63,15 @@ of such patterns separated by a colon \":\" (this means that a ref name\n> \n>> -Each pattern pair consists of the source side (before the colon)\n>> -and the destination side (after the colon).  The ref to be\n>> -pushed is determined by finding a match that matches the source\n>> -side, and where it is pushed is determined by using the\n>> -destination side.\n>> +Each pattern pair '<src>:<dst>' consists of the source side (before\n>> +the colon) and the destination side (after the colon).  The ref to be\n>> +pushed is determined by finding a match that matches the source side,\n>> +and where it is pushed is determined by using the destination side.\n> \n> This looks like the insertion of \"'<src>:<dst>' early on, where the rest\n> of the changes are just follow-on line-wrapping.\n> \n\nStrict line-wrapping doesn't work well with version control in free\ntext. And it doesn't work well either with asciidoc, where some unlucky\nwrapping can generate spurious formatting.\n\n> I wonder if this patch could benefit from being broken into smaller\n> pieces. Maybe a few preliminaries like \"change <foo|bar|baz> to\n> (foo|bar|baz)\" and the like, then even if the final patch is \"large\", it\n> will not be *as large*? But there are clearly sub-topics here, such as\n> \"change <some_arg> to <some-arg>\" and \"change arg to <arg>\". Or maybe\n> this doesn't make sense as an approach to cutting this patch into\n> smaller pieces, but I thought I'd mention it.\n\nThe changes are muliplying. I will split them.\n\n> \n>> - - It is an error if <src> does not match exactly one of the\n>> + - It is an error if '<src>' does not match exactly one of the\n>>     local refs.\n>>\n>> - - If <dst> does not match any remote ref, either\n>> + - If '<dst>' does not match any remote ref, either\n> \n> I believe these match Junio's preference, so ok. But again, this looks\n> like it could go in a separate patch from a lot of these other changes\n> as a way of keeping to somewhat focused changes.\n> \n>> -               (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n>> -               (-[c|d|o|i|s|u|k|m])*\n>> +               [--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...]\n>> +               [-(c|d|o|i|s|u|k|m)...]\n> \n> Sort of cute how this saves on repeating the \"--\" by pulling it out.\n> Anyway, nothing new in your patch. :-)\n\nTo me, the grammar should express at the token level (not like here),\nand anyway, this synopsis is not correct: even if these options are\nallowed to be repeated several times on the command line, this is\nuseless and some of them have the same meaning (and this should be\nshown). This way of expressing the grammar induce the reader into\nthinking that this is some kind of inner grammar to the command.\n\n\nJean-Noël\n"},{"id":"439882","messageId":"4d1fa80d471e02f79803330dfff886e400fffdff.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 1/9] doc: fix git credential synopsis","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:21:56Z","receivedAt":"2021-10-28T16:22:09Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThe subcommand of git credential is not optional.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-credential.txt | 2 +-\n builtin/credential.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 206e3c5f407..f18673017f5 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials\n SYNOPSIS\n --------\n ------------------\n-git credential <fill|approve|reject>\n+'git credential' (fill|approve|reject)\n ------------------\n \n DESCRIPTION\ndiff --git a/builtin/credential.c b/builtin/credential.c\nindex d75dcdc64aa..d7b304fa084 100644\n--- a/builtin/credential.c\n+++ b/builtin/credential.c\n@@ -4,7 +4,7 @@\n #include \"config.h\"\n \n static const char usage_msg[] =\n-\t\"git credential [fill|approve|reject]\";\n+\t\"git credential (fill|approve|reject)\";\n \n int cmd_credential(int argc, const char **argv, const char *prefix)\n {\n-- \ngitgitgadget\n\n"},{"id":"439883","messageId":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.git.1635261072531.gitgitgadget@gmail.com","subject":"[PATCH v2 0/9] doc: fix grammar rules in commands' syntax","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:21:55Z","receivedAt":"2021-10-28T16:22:10Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"There are command expressions which do not follow the grammar syntax rules.\n\nAccording to the coding guidelines, the placeholders must:\n\n * be in small letters\n * enclosed in angle brackets\n * use hyphens as spaces\n\nThey also must represent tokens' meaning as atomic entities.\n\nSome fixups for git-credential, git-ls-files, git-init and git-http-push.\n\nchanges since v1:\n\n * split changes across simpler commits\n\nSigned-off-by: Jean-Noël Avila jn.avila@free.fr\n\nJean-Noël Avila (9):\n  doc: fix git credential synopsis\n  doc: split placeholders as individual tokens\n  doc: express grammar placeholders between angle brackets\n  doc: use only hyphens as word separators in placeholders\n  doc: git-ls-files: express options as optional alternatives\n  doc: use three dots for indicating repetition instead of star\n  doc: uniformize <URL> placeholders' case\n  doc: git-http-push: describe the refs as pattern pairs\n  doc: git-init: clarify file modes in octal.\n\n Documentation/date-formats.txt        |  4 +--\n Documentation/git-archimport.txt      | 14 ++++----\n Documentation/git-checkout.txt        | 36 +++++++++----------\n Documentation/git-cherry-pick.txt     |  6 ++--\n Documentation/git-clone.txt           |  8 ++---\n Documentation/git-config.txt          | 46 ++++++++++++------------\n Documentation/git-credential.txt      |  2 +-\n Documentation/git-cvsexportcommit.txt |  4 +--\n Documentation/git-cvsimport.txt       |  8 ++---\n Documentation/git-diff-files.txt      |  2 +-\n Documentation/git-diff-index.txt      |  2 +-\n Documentation/git-diff-tree.txt       |  2 +-\n Documentation/git-fsck.txt            |  2 +-\n Documentation/git-gui.txt             |  2 +-\n Documentation/git-help.txt            |  6 ++--\n Documentation/git-http-fetch.txt      |  2 +-\n Documentation/git-http-push.txt       | 15 ++++----\n Documentation/git-init-db.txt         |  2 +-\n Documentation/git-init.txt            | 26 +++++++-------\n Documentation/git-log.txt             |  8 ++---\n Documentation/git-ls-files.txt        |  6 ++--\n Documentation/git-merge-index.txt     |  2 +-\n Documentation/git-p4.txt              |  8 ++---\n Documentation/git-pack-objects.txt    |  4 +--\n Documentation/git-pack-redundant.txt  |  2 +-\n Documentation/git-reflog.txt          |  4 +--\n Documentation/git-remote.txt          |  8 ++---\n Documentation/git-request-pull.txt    |  8 ++---\n Documentation/git-shortlog.txt        |  8 ++---\n Documentation/git-sparse-checkout.txt |  2 +-\n Documentation/git-stage.txt           |  2 +-\n Documentation/git-svn.txt             |  2 +-\n Documentation/git-web--browse.txt     |  2 +-\n Documentation/gitcredentials.txt      |  4 +--\n Documentation/gitsubmodules.txt       |  2 +-\n Documentation/gitworkflows.txt        |  6 ++--\n Documentation/pretty-formats.txt      | 52 +++++++++++++--------------\n Documentation/urls-remotes.txt        |  8 ++---\n builtin/credential.c                  |  2 +-\n 39 files changed, 165 insertions(+), 164 deletions(-)\n\n\nbase-commit: 9d530dc0024503ab4218fe6c4395b8a0aa245478\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1066%2Fjnavila%2Ffix_manpages_placeholders-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1066/jnavila/fix_manpages_placeholders-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1066\n\nRange-diff vs v1:\n\n  -:  ----------- >  1:  4d1fa80d471 doc: fix git credential synopsis\n  -:  ----------- >  2:  0045fe6faea doc: split placeholders as individual tokens\n  1:  605236f6d49 !  3:  4d2d198f572 doc: fix grammar rules in commands'syntax\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -    doc: fix grammar rules in commands'syntax\n     +    doc: express grammar placeholders between angle brackets\n      \n     -    According to the coding guidelines, the placeholders must:\n     -     * be in small letters\n     -     * enclosed in angle brackets\n     -\n     -    Some other rules are also applied.\n     +    This rules discerns user inputs from verbatim options in the\n     +    synopsis.\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n     - ## Documentation/git-archimport.txt ##\n     -@@ Documentation/git-archimport.txt: git-archimport - Import a GNU Arch repository into Git\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]\n     --               <archive/branch>[:<git-branch>] ...\n     -+'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]\n     -+\t       <archive>/<branch>[:<git-branch>]...\n     - \n     - DESCRIPTION\n     - -----------\n     -\n     - ## Documentation/git-checkout.txt ##\n     -@@ Documentation/git-checkout.txt: SYNOPSIS\n     - 'git checkout' [-q] [-f] [-m] [<branch>]\n     - 'git checkout' [-q] [-f] [-m] --detach [<branch>]\n     - 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n     --'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n     -+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n     - 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...\n     - 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]\n     - 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n     -@@ Documentation/git-checkout.txt: You could omit `<branch>`, in which case the command degenerates to\n     - rather expensive side-effects to show only the tracking information,\n     - if exists, for the current branch.\n     - \n     --'git checkout' -b|-B <new_branch> [<start point>]::\n     -+'git checkout' -b|-B <new-branch> [<start-point>]::\n     - \n     - \tSpecifying `-b` causes a new branch to be created as if\n     - \tlinkgit:git-branch[1] were called and then checked out.  In\n     -@@ Documentation/git-checkout.txt: as `ours` (i.e. \"our shared canonical history\"), while what you did\n     - on your side branch as `theirs` (i.e. \"one contributor's work on top\n     - of it\").\n     - \n     ---b <new_branch>::\n     -+-b <new-branch>::\n     - \tCreate a new branch named `<new_branch>` and start it at\n     - \t`<start_point>`; see linkgit:git-branch[1] for details.\n     - \n     ---B <new_branch>::\n     -+-B <new-branch>::\n     - \tCreates the branch `<new_branch>` and start it at `<start_point>`;\n     - \tif it already exists, then reset it to `<start_point>`. This is\n     - \tequivalent to running \"git branch\" with \"-f\"; see\n     -\n       ## Documentation/git-cherry-pick.txt ##\n      @@ Documentation/git-cherry-pick.txt: git-cherry-pick - Apply the changes introduced by some existing commits\n       SYNOPSIS\n     @@ Documentation/git-config.txt: OPTIONS\n      ---get-urlmatch name URL::\n      +--get-urlmatch <name> <URL>::\n       \tWhen given a two-part name section.key, the value for\n     - \tsection.<url>.key whose <url> part matches the best to the\n     +-\tsection.<url>.key whose <url> part matches the best to the\n     ++\tsection.<URL>.key whose <URL> part matches the best to the\n       \tgiven URL is returned (if no such key exists, the value for\n     + \tsection.key is used as a fallback).  When given just the\n     + \tsection as name, do so for all the keys in the section and\n      @@ Documentation/git-config.txt: See also <<FILES>>.\n       \tread from or written to if `extensions.worktreeConfig` is\n       \tpresent. If not it's the same as `--local`.\n     @@ Documentation/git-config.txt: Valid `<type>`'s include:\n      ---get-colorbool name [stdout-is-tty]::\n      +--get-colorbool <name> [<stdout-is-tty>]::\n       \n     - \tFind the color setting for `name` (e.g. `color.diff`) and output\n     - \t\"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n     -@@ Documentation/git-config.txt: Valid `<type>`'s include:\n     +-\tFind the color setting for `name` (e.g. `color.diff`) and output\n     +-\t\"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n     ++\tFind the color setting for `<name>` (e.g. `color.diff`) and output\n     ++\t\"true\" or \"false\".  `<stdout-is-tty>` should be either \"true\" or\n     + \t\"false\", and is taken into account when configuration says\n     +-\t\"auto\".  If `stdout-is-tty` is missing, then checks the standard\n     ++\t\"auto\".  If `<stdout-is-tty>` is missing, then checks the standard\n     + \toutput of the command itself, and exits with status 0 if color\n     + \tis to be used, or exits with status 1 otherwise.\n       \tWhen the color setting for `name` is undefined, the command uses\n       \t`color.ui` as fallback.\n       \n     @@ Documentation/git-config.txt: Valid `<type>`'s include:\n       \n       \tFind the color configured for `name` (e.g. `color.diff.new`) and\n       \toutput it as the ANSI color escape sequence to the standard\n     -\n     - ## Documentation/git-credential.txt ##\n     -@@ Documentation/git-credential.txt: git-credential - Retrieve and store user credentials\n     - SYNOPSIS\n     - --------\n     - ------------------\n     --git credential <fill|approve|reject>\n     -+git credential [fill|approve|reject]\n     - ------------------\n     +@@ Documentation/git-config.txt: Valid `<type>`'s include:\n       \n     - DESCRIPTION\n     + --default <value>::\n     +   When using `--get`, and the requested variable is not found, behave as if\n     +-  <value> were the value assigned to the that variable.\n     ++  `<value>` were the value assigned to the that variable.\n     + \n     + CONFIGURATION\n     + -------------\n      \n       ## Documentation/git-cvsexportcommit.txt ##\n      @@ Documentation/git-cvsexportcommit.txt: git-cvsexportcommit - Export a single commit to a CVS checkout\n     @@ Documentation/git-cvsexportcommit.txt: git-cvsexportcommit - Export a single com\n       \n       DESCRIPTION\n      \n     - ## Documentation/git-cvsimport.txt ##\n     -@@ Documentation/git-cvsimport.txt: git-cvsimport - Salvage your data out of another SCM people love to hate\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n     -+'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n     - \t      [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]\n     --\t      [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n     -+\t      [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n     - \t      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]\n     --\t      [-r <remote>] [-R] [<CVS_module>]\n     -+\t      [-r <remote>] [-R] [<CVS-module>]\n     - \n     - \n     - DESCRIPTION\n     -@@ Documentation/git-cvsimport.txt: OPTIONS\n     - -v::\n     - \tVerbosity: let 'cvsimport' report what it is doing.\n     - \n     ---d <CVSROOT>::\n     -+-d <cvsroot>::\n     - \tThe root of the CVS archive. May be local (a simple path) or remote;\n     - \tcurrently, only the :local:, :ext: and :pserver: access methods\n     - \tare supported. If not given, 'git cvsimport' will try to read it\n     - \tfrom `CVS/Root`. If no such file exists, it checks for the\n     - \t`CVSROOT` environment variable.\n     - \n     --<CVS_module>::\n     -+<CVS-module>::\n     - \tThe CVS module you want to import. Relative to <CVSROOT>.\n     - \tIf not given, 'git cvsimport' tries to read it from\n     - \t`CVS/Repository`.\n     -\n     - ## Documentation/git-fsck.txt ##\n     -@@ Documentation/git-fsck.txt: SYNOPSIS\n     - 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n     - \t [--[no-]full] [--strict] [--verbose] [--lost-found]\n     - \t [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n     --\t [--[no-]name-objects] [<object>*]\n     -+\t [--[no-]name-objects] [<object>...]\n     - \n     - DESCRIPTION\n     - -----------\n     -\n       ## Documentation/git-gui.txt ##\n      @@ Documentation/git-gui.txt: git-gui - A portable graphical interface to Git\n       SYNOPSIS\n     @@ Documentation/git-http-fetch.txt: git-http-fetch - Download from a remote Git re\n       DESCRIPTION\n       -----------\n      \n     - ## Documentation/git-http-push.txt ##\n     -@@ Documentation/git-http-push.txt: of such patterns separated by a colon \":\" (this means that a ref name\n     - cannot have a colon in it).  A single pattern '<name>' is just a\n     - shorthand for '<name>:<name>'.\n     - \n     --Each pattern pair consists of the source side (before the colon)\n     --and the destination side (after the colon).  The ref to be\n     --pushed is determined by finding a match that matches the source\n     --side, and where it is pushed is determined by using the\n     --destination side.\n     -+Each pattern pair '<src>:<dst>' consists of the source side (before\n     -+the colon) and the destination side (after the colon).  The ref to be\n     -+pushed is determined by finding a match that matches the source side,\n     -+and where it is pushed is determined by using the destination side.\n     - \n     -- - It is an error if <src> does not match exactly one of the\n     -+ - It is an error if '<src>' does not match exactly one of the\n     -    local refs.\n     - \n     -- - If <dst> does not match any remote ref, either\n     -+ - If '<dst>' does not match any remote ref, either\n     - \n     -    * it has to start with \"refs/\"; <dst> is used as the\n     -      destination literally in this case.\n     -\n     - ## Documentation/git-init-db.txt ##\n     -@@ Documentation/git-init-db.txt: git-init-db - Creates an empty Git repository\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]\n     -+'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]\n     - \n     - \n     - DESCRIPTION\n     -\n       ## Documentation/git-init.txt ##\n     -@@ Documentation/git-init.txt: git-init - Create an empty Git repository or reinitialize an existing one\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n     --\t  [--separate-git-dir <git dir>] [--object-format=<format>]\n     -+'git init' [-q | --quiet] [--bare] [--template=<template-directory>]\n     -+\t  [--separate-git-dir <git-dir>] [--object-format=<format>]\n     +@@ Documentation/git-init.txt: SYNOPSIS\n     + 'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n     + \t  [--separate-git-dir <git dir>] [--object-format=<format>]\n       \t  [-b <branch-name> | --initial-branch=<branch-name>]\n      -\t  [--shared[=<permissions>]] [directory]\n      +\t  [--shared[=<permissions>]] [<directory>]\n       \n       \n     - DESCRIPTION\n     -@@ Documentation/git-init.txt: values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.\n     - +\n     - include::object-format-disclaimer.txt[]\n     - \n     ----template=<template_directory>::\n     -+--template=<template-directory>::\n     - \n     - Specify the directory from which templates will be used.  (See the \"TEMPLATE\n     - DIRECTORY\" section below.)\n     - \n     ----separate-git-dir=<git dir>::\n     -+--separate-git-dir=<git-dir>::\n     - \n     - Instead of initializing the repository as a directory to either `$GIT_DIR` or\n     - `./.git/`, create a text file there containing the path to the actual\n     -@@ Documentation/git-init.txt: repository.  If not specified, fall back to the default name (currently\n     - `master`, but this is subject to change in the future; the name can be\n     - customized via the `init.defaultBranch` configuration variable).\n     - \n     ----shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n     -+--shared[=(false|true|umask|group|all|world|everybody|0<octal>)]::\n     - \n     - Specify that the Git repository is to be shared amongst several users.  This\n     - allows users belonging to the same group to push into that\n     -@@ Documentation/git-init.txt: the repository permissions.\n     - \n     - Same as 'group', but make the repository readable by all users.\n     - \n     --'0xxx'::\n     -+'0<octal>'::\n     - \n     --'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n     --override users' umask(2) value (and not only loosen permissions as 'group' and\n     --'all' does). '0640' will create a repository which is group-readable, but not\n     --group-writable or accessible to others. '0660' will create a repo that is\n     --readable and writable to the current user and group, but inaccessible to others.\n     -+'0<octal>' is an octal number and each file will have mode\n     -+'0<octal>'. '0<octal>' will override users' umask(2) value (and not\n     -+only loosen permissions as 'group' and 'all' does). '0640' will create\n     -+a repository which is group-readable, but not group-writable or\n     -+accessible to others. '0660' will create a repo that is readable and\n     -+writable to the current user and group, but inaccessible to others.\n     - --\n     - \n     - By default, the configuration flag `receive.denyNonFastForwards` is enabled\n     -\n     - ## Documentation/git-log.txt ##\n     -@@ Documentation/git-log.txt: git-log - Show commit logs\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git log' [<options>] [<revision range>] [[--] <path>...]\n     -+'git log' [<options>] [<revision-range>] [[--] <path>...]\n     - \n     - DESCRIPTION\n     - -----------\n     -@@ Documentation/git-log.txt: produced by `--stat`, etc.\n     - \n     - include::line-range-options.txt[]\n     - \n     --<revision range>::\n     -+<revision-range>::\n     - \tShow only commits in the specified revision range.  When no\n     - \t<revision range> is specified, it defaults to `HEAD` (i.e. the\n     - \twhole history leading to the current commit).  `origin..HEAD`\n     -\n     - ## Documentation/git-ls-files.txt ##\n     -@@ Documentation/git-ls-files.txt: SYNOPSIS\n     - --------\n     - [verse]\n     - 'git ls-files' [-z] [-t] [-v] [-f]\n     --\t\t(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n     --\t\t(-[c|d|o|i|s|u|k|m])*\n     -+\t\t[--(cached|deleted|others|ignored|stage|unmerged|killed|modified)...]\n     -+\t\t[-(c|d|o|i|s|u|k|m)...]\n     - \t\t[--eol]\n     - \t\t[--deduplicate]\n     - \t\t[-x <pattern>|--exclude=<pattern>]\n     -\n     - ## Documentation/git-merge-index.txt ##\n     -@@ Documentation/git-merge-index.txt: git-merge-index - Run a merge for files needing merging\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)\n     -+'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) )\n     - \n     - DESCRIPTION\n     - -----------\n     -\n     - ## Documentation/git-p4.txt ##\n     -@@ Documentation/git-p4.txt: git-p4 - Import from and submit to Perforce repositories\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...\n     --'git p4 sync' [<sync options>] [<p4 depot path>...]\n     -+'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>...\n     -+'git p4 sync' [<sync-options>] [<p4-depot-path>...]\n     - 'git p4 rebase'\n     --'git p4 submit' [<submit options>] [<master branch name>]\n     -+'git p4 submit' [<submit-options>] [<master-branch-name>]\n     - \n     - \n       DESCRIPTION\n      \n       ## Documentation/git-pack-objects.txt ##\n     @@ Documentation/git-pack-redundant.txt: git-pack-redundant - Find redundant pack f\n       --------\n       [verse]\n      -'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >\n     -+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <.pack-filename>... )\n     ++'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n       \n       DESCRIPTION\n       -----------\n     @@ Documentation/git-reflog.txt: The command takes various subcommands, and differe\n       \n       Reference logs, or \"reflogs\", record when the tips of branches and\n      \n     - ## Documentation/git-shortlog.txt ##\n     -@@ Documentation/git-shortlog.txt: git-shortlog - Summarize 'git log' output\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git shortlog' [<options>] [<revision range>] [[--] <path>...]\n     -+'git shortlog' [<options>] [<revision-range>] [[--] <path>...]\n     - git log --pretty=short | 'git shortlog' [<options>]\n     - \n     - DESCRIPTION\n     -@@ Documentation/git-shortlog.txt: counts both authors and co-authors.\n     - If width is `0` (zero) then indent the lines of the output without wrapping\n     - them.\n     - \n     --<revision range>::\n     -+<revision-range>::\n     - \tShow only commits in the specified revision range.  When no\n     - \t<revision range> is specified, it defaults to `HEAD` (i.e. the\n     - \twhole history leading to the current commit).  `origin..HEAD`\n     -\n       ## Documentation/git-sparse-checkout.txt ##\n      @@ Documentation/git-sparse-checkout.txt: given by a list of patterns.\n       SYNOPSIS\n       --------\n       [verse]\n      -'git sparse-checkout <subcommand> [options]'\n     -+'git sparse-checkout <subcommand> [<options>...]'\n     ++'git sparse-checkout <subcommand> [<options>]'\n       \n       \n       DESCRIPTION\n     @@ Documentation/git-stage.txt: git-stage - Add file contents to the staging area\n       \n       \n       DESCRIPTION\n     -\n     - ## Documentation/git-web--browse.txt ##\n     -@@ Documentation/git-web--browse.txt: git-web--browse - Git helper script to launch a web browser\n     - SYNOPSIS\n     - --------\n     - [verse]\n     --'git web{litdd}browse' [<options>] <url|file>...\n     -+'git web{litdd}browse' [<options>] (<url>|<file>)...\n     - \n     - DESCRIPTION\n     - -----------\n  -:  ----------- >  4:  984b6d687a2 doc: use only hyphens as word separators in placeholders\n  -:  ----------- >  5:  8e078e6ea17 doc: git-ls-files: express options as optional alternatives\n  -:  ----------- >  6:  0c7b1d53808 doc: use three dots for indicating repetition instead of star\n  -:  ----------- >  7:  8f85da3bb4a doc: uniformize <URL> placeholders' case\n  -:  ----------- >  8:  20900b019f8 doc: git-http-push: describe the refs as pattern pairs\n  -:  ----------- >  9:  7eef3538f3c doc: git-init: clarify file modes in octal.\n\n-- \ngitgitgadget\n"},{"id":"439884","messageId":"0045fe6faeaa2beb63a1e63b3b7573ae06cfba38.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 2/9] doc: split placeholders as individual tokens","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:21:57Z","receivedAt":"2021-10-28T16:22:10Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThe placeholders represent atoms of tokens and must not be\naggregates.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-archimport.txt  | 14 +++++++-------\n Documentation/git-p4.txt          |  2 +-\n Documentation/git-web--browse.txt |  2 +-\n 3 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt\nindex a595a0ffeee..847777fd172 100644\n--- a/Documentation/git-archimport.txt\n+++ b/Documentation/git-archimport.txt\n@@ -9,14 +9,14 @@ git-archimport - Import a GNU Arch repository into Git\n SYNOPSIS\n --------\n [verse]\n-'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]\n-               <archive/branch>[:<git-branch>] ...\n+'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]\n+\t       <archive>/<branch>[:<git-branch>]...\n \n DESCRIPTION\n -----------\n Imports a project from one or more GNU Arch repositories.\n It will follow branches\n-and repositories within the namespaces defined by the <archive/branch>\n+and repositories within the namespaces defined by the <archive>/<branch>\n parameters supplied. If it cannot find the remote branch a merge comes from\n it will just import it as a regular commit. If it can find it, it will mark it\n as a merge whenever possible (see discussion below).\n@@ -27,7 +27,7 @@ import new branches within the provided roots.\n \n It expects to be dealing with one project only. If it sees\n branches that have different roots, it will refuse to run. In that case,\n-edit your <archive/branch> parameters to define clearly the scope of the\n+edit your <archive>/<branch> parameters to define clearly the scope of the\n import.\n \n 'git archimport' uses `tla` extensively in the background to access the\n@@ -42,7 +42,7 @@ incremental imports.\n \n While 'git archimport' will try to create sensible branch names for the\n archives that it imports, it is also possible to specify Git branch names\n-manually.  To do so, write a Git branch name after each <archive/branch>\n+manually.  To do so, write a Git branch name after each <archive>/<branch>\n parameter, separated by a colon.  This way, you can shorten the Arch\n branch names and convert Arch jargon to Git jargon, for example mapping a\n \"PROJECT{litdd}devo{litdd}VERSION\" branch to \"master\".\n@@ -104,8 +104,8 @@ OPTIONS\n \tOverride the default tempdir.\n \n \n-<archive/branch>::\n-\tArchive/branch identifier in a format that `tla log` understands.\n+<archive>/<branch>::\n+\t<archive>/<branch> identifier in a format that `tla log` understands.\n \n \n GIT\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex 38e5257b2a4..8a6addcf72f 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -361,7 +361,7 @@ These options can be used to modify 'git p4 submit' behavior.\n \tp4/master.  See the \"Sync options\" section above for more\n \tinformation.\n \n---commit <sha1>|<sha1..sha1>::\n+--commit (<sha1>|<sha1>..<sha1>)::\n     Submit only the specified commit or range of commits, instead of the full\n     list of changes that are in the current Git branch.\n \ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex 8d162b56c59..f2f996cbe16 100644\n--- a/Documentation/git-web--browse.txt\n+++ b/Documentation/git-web--browse.txt\n@@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser\n SYNOPSIS\n --------\n [verse]\n-'git web{litdd}browse' [<options>] <url|file>...\n+'git web{litdd}browse' [<options>] (<URL>|<file>)...\n \n DESCRIPTION\n -----------\n-- \ngitgitgadget\n\n"},{"id":"439885","messageId":"4d2d198f57294d8307453bda784bf5efe5905f45.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 3/9] doc: express grammar placeholders between angle brackets","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:21:58Z","receivedAt":"2021-10-28T16:22:13Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThis rules discerns user inputs from verbatim options in the\nsynopsis.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-cherry-pick.txt     |  6 ++--\n Documentation/git-config.txt          | 46 +++++++++++++--------------\n Documentation/git-cvsexportcommit.txt |  4 +--\n Documentation/git-gui.txt             |  2 +-\n Documentation/git-help.txt            |  6 ++--\n Documentation/git-http-fetch.txt      |  2 +-\n Documentation/git-init.txt            |  2 +-\n Documentation/git-pack-objects.txt    |  4 +--\n Documentation/git-pack-redundant.txt  |  2 +-\n Documentation/git-reflog.txt          |  4 +--\n Documentation/git-sparse-checkout.txt |  2 +-\n Documentation/git-stage.txt           |  2 +-\n 12 files changed, 41 insertions(+), 41 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 5d750314b29..78dcc9171fb 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits\n SYNOPSIS\n --------\n [verse]\n-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]\n+'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n \t\t  [-S[<keyid>]] <commit>...\n 'git cherry-pick' (--continue | --skip | --abort | --quit)\n \n@@ -81,8 +81,8 @@ OPTIONS\n \tdescribed above, and `-r` was to disable it.  Now the\n \tdefault is not to do `-x` so this option is a no-op.\n \n--m parent-number::\n---mainline parent-number::\n+-m <parent-number>::\n+--mainline <parent-number>::\n \tUsually you cannot cherry-pick a merge because you do not know which\n \tside of the merge should be considered the mainline.  This\n \toption specifies the parent number (starting from 1) of\ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 992225f6129..0e58970289b 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -9,20 +9,20 @@ git-config - Get and set repository or global options\n SYNOPSIS\n --------\n [verse]\n-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]\n-'git config' [<file-option>] [--type=<type>] --add name value\n-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL\n-'git config' [<file-option>] [--fixed-value] --unset name [value-pattern]\n-'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern]\n-'git config' [<file-option>] --rename-section old_name new_name\n-'git config' [<file-option>] --remove-section name\n+'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]\n+'git config' [<file-option>] [--type=<type>] --add <name> <value>\n+'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>\n+'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]\n+'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]\n+'git config' [<file-option>] --rename-section <old-name> <new-name>\n+'git config' [<file-option>] --remove-section <name>\n 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list\n-'git config' [<file-option>] --get-color name [default]\n-'git config' [<file-option>] --get-colorbool name [stdout-is-tty]\n+'git config' [<file-option>] --get-color <name> [<default>]\n+'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]\n 'git config' [<file-option>] -e | --edit\n \n DESCRIPTION\n@@ -102,9 +102,9 @@ OPTIONS\n \tin which section and variable names are lowercased, but subsection\n \tnames are not.\n \n---get-urlmatch name URL::\n+--get-urlmatch <name> <URL>::\n \tWhen given a two-part name section.key, the value for\n-\tsection.<url>.key whose <url> part matches the best to the\n+\tsection.<URL>.key whose <URL> part matches the best to the\n \tgiven URL is returned (if no such key exists, the value for\n \tsection.key is used as a fallback).  When given just the\n \tsection as name, do so for all the keys in the section and\n@@ -145,7 +145,7 @@ See also <<FILES>>.\n \tread from or written to if `extensions.worktreeConfig` is\n \tpresent. If not it's the same as `--local`.\n \n--f config-file::\n+-f <config-file>::\n --file config-file::\n \tFor writing options: write to the specified file rather than the\n \trepository `.git/config`.\n@@ -155,7 +155,7 @@ available files.\n +\n See also <<FILES>>.\n \n---blob blob::\n+--blob <blob>::\n \tSimilar to `--file` but use the given blob instead of a file. E.g.\n \tyou can use 'master:.gitmodules' to read values from the file\n \t'.gitmodules' in the master branch. See \"SPECIFYING REVISIONS\"\n@@ -246,18 +246,18 @@ Valid `<type>`'s include:\n \tall queried config options with the scope of that value\n \t(local, global, system, command).\n \n---get-colorbool name [stdout-is-tty]::\n+--get-colorbool <name> [<stdout-is-tty>]::\n \n-\tFind the color setting for `name` (e.g. `color.diff`) and output\n-\t\"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n+\tFind the color setting for `<name>` (e.g. `color.diff`) and output\n+\t\"true\" or \"false\".  `<stdout-is-tty>` should be either \"true\" or\n \t\"false\", and is taken into account when configuration says\n-\t\"auto\".  If `stdout-is-tty` is missing, then checks the standard\n+\t\"auto\".  If `<stdout-is-tty>` is missing, then checks the standard\n \toutput of the command itself, and exits with status 0 if color\n \tis to be used, or exits with status 1 otherwise.\n \tWhen the color setting for `name` is undefined, the command uses\n \t`color.ui` as fallback.\n \n---get-color name [default]::\n+--get-color <name> [<default>]::\n \n \tFind the color configured for `name` (e.g. `color.diff.new`) and\n \toutput it as the ANSI color escape sequence to the standard\n@@ -281,7 +281,7 @@ Valid `<type>`'s include:\n \n --default <value>::\n   When using `--get`, and the requested variable is not found, behave as if\n-  <value> were the value assigned to the that variable.\n+  `<value>` were the value assigned to the that variable.\n \n CONFIGURATION\n -------------\ndiff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt\nindex 00154b6c85a..41c8a8a05c1 100644\n--- a/Documentation/git-cvsexportcommit.txt\n+++ b/Documentation/git-cvsexportcommit.txt\n@@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout\n SYNOPSIS\n --------\n [verse]\n-'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]\n-\t[-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID\n+'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]\n+\t[-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt\nindex c9d7e96214f..e8f3ccb4337 100644\n--- a/Documentation/git-gui.txt\n+++ b/Documentation/git-gui.txt\n@@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git\n SYNOPSIS\n --------\n [verse]\n-'git gui' [<command>] [arguments]\n+'git gui' [<command>] [<arguments>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 96d5f598b4b..44ea63cc6d3 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all [--[no-]verbose]]\n-\t   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]\n+\t   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'\n+With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -33,7 +33,7 @@ variables.\n \n If an alias is given, git shows the definition of the alias on\n standard output. To get the manual page for the aliased command, use\n-`git COMMAND --help`.\n+`git <command> --help`.\n \n Note that `git --help ...` is identical to `git help ...` because the\n former is internally converted into the latter.\ndiff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt\nindex 9fa17b60e43..fa4bb6cbc3e 100644\n--- a/Documentation/git-http-fetch.txt\n+++ b/Documentation/git-http-fetch.txt\n@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP\n SYNOPSIS\n --------\n [verse]\n-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex b611d80697d..7781d0b3545 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n \t  [--separate-git-dir <git dir>] [--object-format=<format>]\n \t  [-b <branch-name> | --initial-branch=<branch-name>]\n-\t  [--shared[=<permissions>]] [directory]\n+\t  [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex dbfd1f90175..f8344e1e5ba 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -13,8 +13,8 @@ SYNOPSIS\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n \t[--local] [--incremental] [--window=<n>] [--depth=<n>]\n \t[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]\n-\t[--stdout [--filter=<filter-spec>] | base-name]\n-\t[--shallow] [--keep-true-parents] [--[no-]sparse] < object-list\n+\t[--stdout [--filter=<filter-spec>] | <base-name>]\n+\t[--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex f2869da5728..ee7034b5e52 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >\n+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex ff487ff77d3..5ced7ad4f8b 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,12 +17,12 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [log-options] [<ref>]\n+'git reflog' ['show'] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\n 'git reflog delete' [--rewrite] [--updateref]\n-\t[--dry-run | -n] [--verbose] ref@\\{specifier\\}...\n+\t[--dry-run | -n] [--verbose] <ref>@\\{<specifier>\\}...\n 'git reflog exists' <ref>\n \n Reference logs, or \"reflogs\", record when the tips of branches and\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 42056ee9ff9..9a78dd721e8 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -11,7 +11,7 @@ given by a list of patterns.\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [options]'\n+'git sparse-checkout <subcommand> [<options>]'\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 25bcda936db..2f6aaa75b9a 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area\n SYNOPSIS\n --------\n [verse]\n-'git stage' args...\n+'git stage' <arg>...\n \n \n DESCRIPTION\n-- \ngitgitgadget\n\n"},{"id":"439886","messageId":"984b6d687a2e779c775de6ea80536afe6ecc0aaf.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:21:59Z","receivedAt":"2021-10-28T16:22:14Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nAccording to CodingGuidelines, spaces and underscores are not\nallowed in placeholders.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/date-formats.txt   |  4 +--\n Documentation/git-checkout.txt   | 36 +++++++++++-----------\n Documentation/git-clone.txt      |  8 ++---\n Documentation/git-cvsimport.txt  |  8 ++---\n Documentation/git-diff-files.txt |  2 +-\n Documentation/git-diff-index.txt |  2 +-\n Documentation/git-diff-tree.txt  |  2 +-\n Documentation/git-init-db.txt    |  2 +-\n Documentation/git-init.txt       |  8 ++---\n Documentation/git-log.txt        |  8 ++---\n Documentation/git-p4.txt         |  6 ++--\n Documentation/git-shortlog.txt   |  8 ++---\n Documentation/git-svn.txt        |  2 +-\n Documentation/pretty-formats.txt | 52 ++++++++++++++++----------------\n 14 files changed, 74 insertions(+), 74 deletions(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex 99c455f51c0..4a1e7bd43bf 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -5,9 +5,9 @@ The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \n Git internal format::\n-\tIt is `<unix timestamp> <time zone offset>`, where `<unix\n+\tIt is `<unix-timestamp> <time-zone-offset>`, where `<unix-\n \ttimestamp>` is the number of seconds since the UNIX epoch.\n-\t`<time zone offset>` is a positive or negative offset from UTC.\n+\t`<time-zone-offset>` is a positive or negative offset from UTC.\n \tFor example CET (which is 1 hour ahead of UTC) is `+0100`.\n \n RFC 2822::\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d473c9bf387..a52dc49a3dc 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n 'git checkout' [-q] [-f] [-m] [<branch>]\n 'git checkout' [-q] [-f] [-m] --detach [<branch>]\n 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]\n 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n@@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to\n rather expensive side-effects to show only the tracking information,\n if exists, for the current branch.\n \n-'git checkout' -b|-B <new_branch> [<start point>]::\n+'git checkout' -b|-B <new-branch> [<start-point>]::\n \n \tSpecifying `-b` causes a new branch to be created as if\n \tlinkgit:git-branch[1] were called and then checked out.  In\n@@ -52,11 +52,11 @@ if exists, for the current branch.\n \t`--track` without `-b` implies branch creation; see the\n \tdescription of `--track` below.\n +\n-If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it\n+If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it\n is reset. This is the transactional equivalent of\n +\n ------------\n-$ git branch -f <branch> [<start point>]\n+$ git branch -f <branch> [<start-point>]\n $ git checkout <branch>\n ------------\n +\n@@ -145,13 +145,13 @@ as `ours` (i.e. \"our shared canonical history\"), while what you did\n on your side branch as `theirs` (i.e. \"one contributor's work on top\n of it\").\n \n--b <new_branch>::\n-\tCreate a new branch named `<new_branch>` and start it at\n-\t`<start_point>`; see linkgit:git-branch[1] for details.\n+-b <new-branch>::\n+\tCreate a new branch named `<new-branch>` and start it at\n+\t`<start-point>`; see linkgit:git-branch[1] for details.\n \n--B <new_branch>::\n-\tCreates the branch `<new_branch>` and start it at `<start_point>`;\n-\tif it already exists, then reset it to `<start_point>`. This is\n+-B <new-branch>::\n+\tCreates the branch `<new-branch>` and start it at `<start-point>`;\n+\tif it already exists, then reset it to `<start-point>`. This is\n \tequivalent to running \"git branch\" with \"-f\"; see\n \tlinkgit:git-branch[1] for details.\n \n@@ -210,16 +210,16 @@ variable.\n \t`<commit>` is not a branch name.  See the \"DETACHED HEAD\" section\n \tbelow for details.\n \n---orphan <new_branch>::\n-\tCreate a new 'orphan' branch, named `<new_branch>`, started from\n-\t`<start_point>` and switch to it.  The first commit made on this\n+--orphan <new-branch>::\n+\tCreate a new 'orphan' branch, named `<new-branch>`, started from\n+\t`<start-point>` and switch to it.  The first commit made on this\n \tnew branch will have no parents and it will be the root of a new\n \thistory totally disconnected from all the other branches and\n \tcommits.\n +\n The index and the working tree are adjusted as if you had previously run\n-`git checkout <start_point>`.  This allows you to start a new history\n-that records a set of paths similar to `<start_point>` by easily running\n+`git checkout <start-point>`.  This allows you to start a new history\n+that records a set of paths similar to `<start-point>` by easily running\n `git commit -a` to make the root commit.\n +\n This can be useful when you want to publish the tree from a commit\n@@ -229,7 +229,7 @@ whose full history contains proprietary or otherwise encumbered bits of\n code.\n +\n If you want to start a disconnected history that records a set of paths\n-that is totally different from the one of `<start_point>`, then you should\n+that is totally different from the one of `<start-point>`, then you should\n clear the index and the working tree right after creating the orphan\n branch by running `git rm -rf .` from the top level of the working tree.\n Afterwards you will be ready to prepare your new files, repopulating the\n@@ -341,10 +341,10 @@ As a special case, you may use `A...B` as a shortcut for the\n merge base of `A` and `B` if there is exactly one merge base. You can\n leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n \n-<new_branch>::\n+<new-branch>::\n \tName for the new branch.\n \n-<start_point>::\n+<start-point>::\n \tThe name of a commit at which to start the new branch; see\n \tlinkgit:git-branch[1] for details. Defaults to `HEAD`.\n +\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 3fe3810f1ce..9685ea06915 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -9,10 +9,10 @@ git-clone - Clone a repository into a new directory\n SYNOPSIS\n --------\n [verse]\n-'git clone' [--template=<template_directory>]\n+'git clone' [--template=<template-directory>]\n \t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n \t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n-\t  [--dissociate] [--separate-git-dir <git dir>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n \t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n \t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n \t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n@@ -211,7 +211,7 @@ objects from the source repository into a pack in the cloned repository.\n \tvia ssh, this specifies a non-default path for the command\n \trun on the other end.\n \n---template=<template_directory>::\n+--template=<template-directory>::\n \tSpecify the directory from which templates will be used;\n \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n \n@@ -294,7 +294,7 @@ or `--mirror` is given)\n \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n \t`git submodule update`.\n \n---separate-git-dir=<git dir>::\n+--separate-git-dir=<git-dir>::\n \tInstead of placing the cloned repository where it is supposed\n \tto be, place the cloned repository at the specified directory,\n \tthen make a filesystem-agnostic Git symbolic link to there.\ndiff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\nindex de1ebed67d7..b3f27671a0c 100644\n--- a/Documentation/git-cvsimport.txt\n+++ b/Documentation/git-cvsimport.txt\n@@ -11,9 +11,9 @@ SYNOPSIS\n [verse]\n 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n \t      [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]\n-\t      [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n-\t      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]\n-\t      [-r <remote>] [-R] [<CVS_module>]\n+\t      [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n+\t      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>]\n+\t      [-r <remote>] [-R] [<CVS-module>]\n \n \n DESCRIPTION\n@@ -59,7 +59,7 @@ OPTIONS\n \tfrom `CVS/Root`. If no such file exists, it checks for the\n \t`CVSROOT` environment variable.\n \n-<CVS_module>::\n+<CVS-module>::\n \tThe CVS module you want to import. Relative to <CVSROOT>.\n \tIf not given, 'git cvsimport' tries to read it from\n \t`CVS/Repository`.\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex 906774f0f7e..bf1febb9ae7 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...]\n+'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt\nindex 27acb31cbf2..679cae27d9b 100644\n--- a/Documentation/git-diff-index.txt\n+++ b/Documentation/git-diff-index.txt\n@@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index\n SYNOPSIS\n --------\n [verse]\n-'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...]\n+'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 2fc24c542f8..274d5eaba93 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\n \t      [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\n-\t      [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\n+\t      [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt\nindex 648a6cd78ad..18bf1a3c8ce 100644\n--- a/Documentation/git-init-db.txt\n+++ b/Documentation/git-init-db.txt\n@@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository\n SYNOPSIS\n --------\n [verse]\n-'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]\n+'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 7781d0b3545..fdb7b3f367d 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -9,8 +9,8 @@ git-init - Create an empty Git repository or reinitialize an existing one\n SYNOPSIS\n --------\n [verse]\n-'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n-\t  [--separate-git-dir <git dir>] [--object-format=<format>]\n+'git init' [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t  [--separate-git-dir <git-dir>] [--object-format=<format>]\n \t  [-b <branch-name> | --initial-branch=<branch-name>]\n \t  [--shared[=<permissions>]] [<directory>]\n \n@@ -57,12 +57,12 @@ values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.\n +\n include::object-format-disclaimer.txt[]\n \n---template=<template_directory>::\n+--template=<template-directory>::\n \n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n---separate-git-dir=<git dir>::\n+--separate-git-dir=<git-dir>::\n \n Instead of initializing the repository as a directory to either `$GIT_DIR` or\n `./.git/`, create a text file there containing the path to the actual\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 0498e7bacbe..20e87cecf49 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -9,7 +9,7 @@ git-log - Show commit logs\n SYNOPSIS\n --------\n [verse]\n-'git log' [<options>] [<revision range>] [[--] <path>...]\n+'git log' [<options>] [<revision-range>] [[--] <path>...]\n \n DESCRIPTION\n -----------\n@@ -81,13 +81,13 @@ produced by `--stat`, etc.\n \n include::line-range-options.txt[]\n \n-<revision range>::\n+<revision-range>::\n \tShow only commits in the specified revision range.  When no\n-\t<revision range> is specified, it defaults to `HEAD` (i.e. the\n+\t<revision-range> is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n \t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell <revision range>, see the 'Specifying Ranges'\n+\tways to spell <revision-range>, see the 'Specifying Ranges'\n \tsection of linkgit:gitrevisions[7].\n \n [--] <path>...::\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex 8a6addcf72f..e21fcd8f712 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories\n SYNOPSIS\n --------\n [verse]\n-'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...\n-'git p4 sync' [<sync options>] [<p4 depot path>...]\n+'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>...\n+'git p4 sync' [<sync-options>] [<p4-depot-path>...]\n 'git p4 rebase'\n-'git p4 submit' [<submit options>] [<master branch name>]\n+'git p4 submit' [<submit-options>] [<master-branch-name>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex c9c7f3065ca..f64e77047b2 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output\n SYNOPSIS\n --------\n [verse]\n-'git shortlog' [<options>] [<revision range>] [[--] <path>...]\n+'git shortlog' [<options>] [<revision-range>] [[--] <path>...]\n git log --pretty=short | 'git shortlog' [<options>]\n \n DESCRIPTION\n@@ -89,13 +89,13 @@ counts both authors and co-authors.\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\n \n-<revision range>::\n+<revision-range>::\n \tShow only commits in the specified revision range.  When no\n-\t<revision range> is specified, it defaults to `HEAD` (i.e. the\n+\t<revision-range> is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n \t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell <revision range>, see the \"Specifying Ranges\"\n+\tways to spell <revision-range>, see the \"Specifying Ranges\"\n \tsection of linkgit:gitrevisions[7].\n \n [--] <path>...::\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 222b556d7a9..4e92308e85d 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -575,7 +575,7 @@ OPTIONS\n -------\n \n --shared[=(false|true|umask|group|all|world|everybody)]::\n---template=<template_directory>::\n+--template=<template-directory>::\n \tOnly used with the 'init' command.\n \tThese are passed directly to 'git init'.\n \ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex ef6bd420ae6..d61606caf41 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -20,7 +20,7 @@ built-in formats:\n \n * 'oneline'\n \n-\t  <hash> <title line>\n+\t  <hash> <title-line>\n +\n This is designed to be as compact as possible.\n \n@@ -29,17 +29,17 @@ This is designed to be as compact as possible.\n \t  commit <hash>\n \t  Author: <author>\n \n-\t      <title line>\n+\t      <title-line>\n \n * 'medium'\n \n \t  commit <hash>\n \t  Author: <author>\n-\t  Date:   <author date>\n+\t  Date:   <author-date>\n \n-\t      <title line>\n+\t      <title-line>\n \n-\t      <full commit message>\n+\t      <full-commit-message>\n \n * 'full'\n \n@@ -47,25 +47,25 @@ This is designed to be as compact as possible.\n \t  Author: <author>\n \t  Commit: <committer>\n \n-\t      <title line>\n+\t      <title-line>\n \n-\t      <full commit message>\n+\t      <full-commit-message>\n \n * 'fuller'\n \n \t  commit <hash>\n \t  Author:     <author>\n-\t  AuthorDate: <author date>\n+\t  AuthorDate: <author-date>\n \t  Commit:     <committer>\n-\t  CommitDate: <committer date>\n+\t  CommitDate: <committer-date>\n \n-\t       <title line>\n+\t       <title-line>\n \n-\t       <full commit message>\n+\t       <full-commit-message>\n \n * 'reference'\n \n-\t  <abbrev hash> (<title line>, <short author date>)\n+\t  <abbrev-hash> (<title-line>, <short-author-date>)\n +\n This format is used to refer to another commit in a commit message and\n is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,\n@@ -78,10 +78,10 @@ placeholders, its output is not affected by other options like\n \n \t  From <hash> <date>\n \t  From: <author>\n-\t  Date: <author date>\n-\t  Subject: [PATCH] <title line>\n+\t  Date: <author-date>\n+\t  Subject: [PATCH] <title-line>\n \n-\t  <full commit message>\n+\t  <full-commit-message>\n \n * 'mboxrd'\n +\n@@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is shown e.g. with\n `git log --raw`. To get full object names in a raw diff format,\n use `--no-abbrev`.\n \n-* 'format:<string>'\n+* 'format:<format-string>'\n +\n-The 'format:<string>' format allows you to specify which information\n+The 'format:<format-string>' format allows you to specify which information\n you want to show. It works a little bit like printf format,\n with the notable exception that you get a newline with '%n'\n instead of '\\n'.\n@@ -273,12 +273,12 @@ endif::git-rev-list[]\n \t\t\t  If any option is provided multiple times the\n \t\t\t  last occurrence wins.\n +\n-The boolean options accept an optional value `[=<BOOL>]`. The values\n+The boolean options accept an optional value `[=<value>]`. The values\n `true`, `false`, `on`, `off` etc. are all accepted. See the \"boolean\"\n sub-section in \"EXAMPLES\" in linkgit:git-config[1]. If a boolean\n option is given with no value, it's enabled.\n +\n-** 'key=<K>': only show trailers with specified key. Matching is done\n+** 'key=<key>': only show trailers with specified <key>. Matching is done\n    case-insensitively and trailing colon is optional. If option is\n    given multiple times trailer lines matching any of the keys are\n    shown. This option automatically enables the `only` option so that\n@@ -286,9 +286,9 @@ option is given with no value, it's enabled.\n    desired it can be disabled with `only=false`.  E.g.,\n    `%(trailers:key=Reviewed-by)` shows trailer lines with key\n    `Reviewed-by`.\n-** 'only[=<BOOL>]': select whether non-trailer lines from the trailer\n+** 'only[=<bool-value>]': select whether non-trailer lines from the trailer\n    block should be included.\n-** 'separator=<SEP>': specify a separator inserted between trailer\n+** 'separator=<sep>': specify a separator inserted between trailer\n    lines. When this option is not given each trailer line is\n    terminated with a line feed character. The string SEP may contain\n    the literal formatting codes described above. To use comma as\n@@ -296,15 +296,15 @@ option is given with no value, it's enabled.\n    next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`\n    shows all trailer lines whose key is \"Ticket\" separated by a comma\n    and a space.\n-** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`\n+** 'unfold[=<bool-value>]': make it behave as if interpret-trailer's `--unfold`\n    option was given. E.g.,\n    `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.\n-** 'keyonly[=<BOOL>]': only show the key part of the trailer.\n-** 'valueonly[=<BOOL>]': only show the value part of the trailer.\n-** 'key_value_separator=<SEP>': specify a separator inserted between\n+** 'keyonly[=<bool-value>]': only show the key part of the trailer.\n+** 'valueonly[=<bool-value>]': only show the value part of the trailer.\n+** 'key_value_separator=<sep>': specify a separator inserted between\n    trailer lines. When this option is not given each trailer key-value\n    pair is separated by \": \". Otherwise it shares the same semantics\n-   as 'separator=<SEP>' above.\n+   as 'separator=<sep>' above.\n \n NOTE: Some placeholders may depend on other options given to the\n revision traversal engine. For example, the `%g*` reflog options will\n-- \ngitgitgadget\n\n"},{"id":"439887","messageId":"8e078e6ea17b51766256e427e7bca5ce7d9af809.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 5/9] doc: git-ls-files: express options as optional alternatives","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:22:00Z","receivedAt":"2021-10-28T16:22:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThat's how alternative options are expressed in general.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-ls-files.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 6d11ab506b7..2e3d695fa21 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -10,9 +10,9 @@ SYNOPSIS\n --------\n [verse]\n 'git ls-files' [-z] [-t] [-v] [-f]\n-\t\t(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n-\t\t(-[c|d|o|i|s|u|k|m])*\n-\t\t[--eol]\n+\t\t[-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored]\n+\t\t[-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified]\n+\t\t[--directory [--no-empty-directory]] [--eol]\n \t\t[--deduplicate]\n \t\t[-x <pattern>|--exclude=<pattern>]\n \t\t[-X <file>|--exclude-from=<file>]\n-- \ngitgitgadget\n\n"},{"id":"439888","messageId":"8f85da3bb4ad1ca0c864d925b621426bb38ca5bb.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 7/9] doc: uniformize <URL> placeholders' case","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:22:02Z","receivedAt":"2021-10-28T16:22:17Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nURL being an acronym, it deserves to be kept uppercase.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-http-fetch.txt   | 2 +-\n Documentation/git-http-push.txt    | 2 +-\n Documentation/git-remote.txt       | 8 ++++----\n Documentation/git-request-pull.txt | 8 ++++----\n Documentation/gitcredentials.txt   | 4 ++--\n Documentation/gitsubmodules.txt    | 2 +-\n Documentation/gitworkflows.txt     | 6 +++---\n Documentation/urls-remotes.txt     | 8 ++++----\n 8 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt\nindex fa4bb6cbc3e..319062c021b 100644\n--- a/Documentation/git-http-fetch.txt\n+++ b/Documentation/git-http-fetch.txt\n@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP\n SYNOPSIS\n --------\n [verse]\n-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt\nindex ea03a4eeb0f..78f2bb75523 100644\n--- a/Documentation/git-http-push.txt\n+++ b/Documentation/git-http-push.txt\n@@ -9,7 +9,7 @@ git-http-push - Push objects over HTTP/DAV to another repository\n SYNOPSIS\n --------\n [verse]\n-'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...]\n+'git http-push' [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex 31c29c9b31b..2bebc32566b 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git remote' [-v | --verbose]\n-'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url>\n+'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>\n 'git remote rename' <old> <new>\n 'git remote remove' <name>\n 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>)\n@@ -18,7 +18,7 @@ SYNOPSIS\n 'git remote get-url' [--push] [--all] <name>\n 'git remote set-url' [--push] <name> <newurl> [<oldurl>]\n 'git remote set-url --add' [--push] <name> <newurl>\n-'git remote set-url --delete' [--push] <name> <url>\n+'git remote set-url --delete' [--push] <name> <URL>\n 'git remote' [-v | --verbose] 'show' [-n] <name>...\n 'git remote prune' [-n | --dry-run] <name>...\n 'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]\n@@ -47,7 +47,7 @@ subcommands are available to perform operations on the remotes.\n 'add'::\n \n Add a remote named <name> for the repository at\n-<url>.  The command `git fetch <name>` can then be used to create and\n+<URL>.  The command `git fetch <name>` can then be used to create and\n update remote-tracking branches <name>/<branch>.\n +\n With `-f` option, `git fetch <name>` is run immediately after\n@@ -152,7 +152,7 @@ With `--push`, push URLs are manipulated instead of fetch URLs.\n With `--add`, instead of changing existing URLs, new URL is added.\n +\n With `--delete`, instead of changing existing URLs, all URLs matching\n-regex <url> are deleted for remote <name>.  Trying to delete all\n+regex <URL> are deleted for remote <name>.  Trying to delete all\n non-push URLs is an error.\n +\n Note that the push URL and the fetch URL, even though they can\ndiff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt\nindex 4d4392d0f84..fa5a4267092 100644\n--- a/Documentation/git-request-pull.txt\n+++ b/Documentation/git-request-pull.txt\n@@ -8,7 +8,7 @@ git-request-pull - Generates a summary of pending changes\n SYNOPSIS\n --------\n [verse]\n-'git request-pull' [-p] <start> <url> [<end>]\n+'git request-pull' [-p] <start> <URL> [<end>]\n \n DESCRIPTION\n -----------\n@@ -21,7 +21,7 @@ the changes and indicates from where they can be pulled.\n The upstream project is expected to have the commit named by\n `<start>` and the output asks it to integrate the changes you made\n since that commit, up to the commit named by `<end>`, by visiting\n-the repository named by `<url>`.\n+the repository named by `<URL>`.\n \n \n OPTIONS\n@@ -33,14 +33,14 @@ OPTIONS\n \tCommit to start at.  This names a commit that is already in\n \tthe upstream history.\n \n-<url>::\n+<URL>::\n \tThe repository URL to be pulled from.\n \n <end>::\n \tCommit to end at (defaults to HEAD).  This names the commit\n \tat the tip of the history you are asking to be pulled.\n +\n-When the repository named by `<url>` has the commit at a tip of a\n+When the repository named by `<URL>` has the commit at a tip of a\n ref that is different from the ref you have locally, you can use the\n `<local>:<remote>` syntax, to have its local name, a colon `:`, and\n its remote name.\ndiff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt\nindex 758bf39ba38..80517b4eb2c 100644\n--- a/Documentation/gitcredentials.txt\n+++ b/Documentation/gitcredentials.txt\n@@ -132,7 +132,7 @@ because the hostnames differ. Nor would it match `foo.example.com`; Git\n compares hostnames exactly, without considering whether two hosts are part of\n the same domain. Likewise, a config entry for `http://example.com` would not\n match: Git compares the protocols exactly.  However, you may use wildcards in\n-the domain name and other pattern matching techniques as with the `http.<url>.*`\n+the domain name and other pattern matching techniques as with the `http.<URL>.*`\n options.\n \n If the \"pattern\" URL does include a path component, then this too must match\n@@ -147,7 +147,7 @@ CONFIGURATION OPTIONS\n \n Options for a credential context can be configured either in\n `credential.*` (which applies to all credentials), or\n-`credential.<url>.*`, where <url> matches the context as described\n+`credential.<URL>.*`, where <URL> matches the context as described\n above.\n \n The following options are available in either location:\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 891c8da4fdf..941858a6ecc 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -226,7 +226,7 @@ Workflow for a third party library\n ----------------------------------\n \n   # Add a submodule\n-  git submodule add <url> <path>\n+  git submodule add <URL> <path>\n \n   # Occasionally update the submodule to a new version:\n   git -C <path> checkout <new version>\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 47cf97f9bea..59305265c5a 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -394,7 +394,7 @@ request to do so by mail.  Such a request looks like\n \n -------------------------------------\n Please pull from\n-    <url> <branch>\n+    <URL> <branch>\n -------------------------------------\n \n In that case, 'git pull' can do the fetch and merge in one go, as\n@@ -403,7 +403,7 @@ follows.\n .Push/pull: Merging remote topics\n [caption=\"Recipe: \"]\n =====================================\n-`git pull <url> <branch>`\n+`git pull <URL> <branch>`\n =====================================\n \n Occasionally, the maintainer may get merge conflicts when they try to\n@@ -440,7 +440,7 @@ merge because you cannot format-patch merges):\n .format-patch/am: Keeping topics up to date\n [caption=\"Recipe: \"]\n =====================================\n-`git pull --rebase <url> <branch>`\n+`git pull --rebase <URL> <branch>`\n =====================================\n \n You can then fix the conflicts during the rebase.  Presumably you have\ndiff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt\nindex bd184cd6539..86d0008f94d 100644\n--- a/Documentation/urls-remotes.txt\n+++ b/Documentation/urls-remotes.txt\n@@ -26,14 +26,14 @@ config file would appear like this:\n \n ------------\n \t[remote \"<name>\"]\n-\t\turl = <url>\n+\t\turl = <URL>\n \t\tpushurl = <pushurl>\n \t\tpush = <refspec>\n \t\tfetch = <refspec>\n ------------\n \n The `<pushurl>` is used for pushes only. It is optional and defaults\n-to `<url>`.\n+to `<URL>`.\n \n Named file in `$GIT_DIR/remotes`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -67,10 +67,10 @@ This file should have the following format:\n \n \n ------------\n-\t<url>#<head>\n+\t<URL>#<head>\n ------------\n \n-`<url>` is required; `#<head>` is optional.\n+`<URL>` is required; `#<head>` is optional.\n \n Depending on the operation, git will use one of the following\n refspecs, if you don't provide one on the command line.\n-- \ngitgitgadget\n\n"},{"id":"439889","messageId":"0c7b1d53808b091ce54490b3c73a26b31a350e4d.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 6/9] doc: use three dots for indicating repetition instead of star","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:22:01Z","receivedAt":"2021-10-28T16:22:18Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThis is how it is specified in CodingGuidelines.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-fsck.txt        | 2 +-\n Documentation/git-merge-index.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex bd596619c0d..5088783dccb 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n \t [--[no-]full] [--strict] [--verbose] [--lost-found]\n \t [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n-\t [--[no-]name-objects] [<object>*]\n+\t [--[no-]name-objects] [<object>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 2ab84a91e53..eea56b3154e 100644\n--- a/Documentation/git-merge-index.txt\n+++ b/Documentation/git-merge-index.txt\n@@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging\n SYNOPSIS\n --------\n [verse]\n-'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)\n+'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) )\n \n DESCRIPTION\n -----------\n-- \ngitgitgadget\n\n"},{"id":"439890","messageId":"20900b019f835e9293fb5d70ae8dbdced3b781c0.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 8/9] doc: git-http-push: describe the refs as pattern pairs","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:22:03Z","receivedAt":"2021-10-28T16:22:24Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nEach member of the pair is explained but they are not defined\nbeforehand.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-http-push.txt | 13 ++++++-------\n 1 file changed, 6 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt\nindex 78f2bb75523..7c6a6dd7f6a 100644\n--- a/Documentation/git-http-push.txt\n+++ b/Documentation/git-http-push.txt\n@@ -63,16 +63,15 @@ of such patterns separated by a colon \":\" (this means that a ref name\n cannot have a colon in it).  A single pattern '<name>' is just a\n shorthand for '<name>:<name>'.\n \n-Each pattern pair consists of the source side (before the colon)\n-and the destination side (after the colon).  The ref to be\n-pushed is determined by finding a match that matches the source\n-side, and where it is pushed is determined by using the\n-destination side.\n+Each pattern pair '<src>:<dst>' consists of the source side (before\n+the colon) and the destination side (after the colon).  The ref to be\n+pushed is determined by finding a match that matches the source side,\n+and where it is pushed is determined by using the destination side.\n \n- - It is an error if <src> does not match exactly one of the\n+ - It is an error if '<src>' does not match exactly one of the\n    local refs.\n \n- - If <dst> does not match any remote ref, either\n+ - If '<dst>' does not match any remote ref, either\n \n    * it has to start with \"refs/\"; <dst> is used as the\n      destination literally in this case.\n-- \ngitgitgadget\n\n"},{"id":"439891","messageId":"7eef3538f3c3015c4f446961ddca78e2868fe644.1635438124.git.gitgitgadget@gmail.com","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"[PATCH v2 9/9] doc: git-init: clarify file modes in octal.","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2021-10-28T16:22:04Z","receivedAt":"2021-10-28T16:22:28Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThe previous explanation was mixing the format with the identity of\nthe field.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-init.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex fdb7b3f367d..af0d2ee1825 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n+--shared[=(false|true|umask|group|all|world|everybody|<umask>)]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\n@@ -110,13 +110,15 @@ the repository permissions.\n \n Same as 'group', but make the repository readable by all users.\n \n-'0xxx'::\n+'<umask>'::\n \n-'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n-override users' umask(2) value (and not only loosen permissions as 'group' and\n-'all' does). '0640' will create a repository which is group-readable, but not\n-group-writable or accessible to others. '0660' will create a repo that is\n-readable and writable to the current user and group, but inaccessible to others.\n+'<umask>' is an 3-digit octal number prefixed with `0` and each file\n+will have mode '<umask>'. '<umask>' will override users' umask(2)\n+value (and not only loosen permissions as 'group' and 'all'\n+does). '0640' will create a repository which is group-readable, but\n+not group-writable or accessible to others. '0660' will create a repo\n+that is readable and writable to the current user and group, but\n+inaccessible to others.\n --\n \n By default, the configuration flag `receive.denyNonFastForwards` is enabled\n-- \ngitgitgadget\n"},{"id":"439900","messageId":"xmqqilxhrrva.fsf@gitster.g","threadId":"56788","inReplyTo":"7eef3538f3c3015c4f446961ddca78e2868fe644.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 9/9] doc: git-init: clarify file modes in octal.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T17:17:29Z","receivedAt":"2021-10-28T17:17:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\"  <gitgitgadget@gmail.com> writes:\n\n> ---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n> +--shared[=(false|true|umask|group|all|world|everybody|<umask>)]::\n>  \n>  Specify that the Git repository is to be shared amongst several users.  This\n>  allows users belonging to the same group to push into that\n> @@ -110,13 +110,15 @@ the repository permissions.\n>  \n>  Same as 'group', but make the repository readable by all users.\n>  \n> -'0xxx'::\n> +'<umask>'::\n>  \n> -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n> -override users' umask(2) value (and not only loosen permissions as 'group' and\n> -'all' does). '0640' will create a repository which is group-readable, but not\n> -group-writable or accessible to others. '0660' will create a repo that is\n> -readable and writable to the current user and group, but inaccessible to others.\n> +'<umask>' is an 3-digit octal number prefixed with `0` and each file\n> +will have mode '<umask>'. '<umask>' will override users' umask(2)\n> +value (and not only loosen permissions as 'group' and 'all'\n> +does). '0640' will create a repository which is group-readable, but\n> +not group-writable or accessible to others. '0660' will create a repo\n> +that is readable and writable to the current user and group, but\n> +inaccessible to others.\n\nGiving it a name that reflects the meaning is a great change.\n\nUnfortunately, I think the original text is wrong to call it umask,\nas this is bitwise opposite of umask(2).  umask 027 for example\nmeans that we *drop* bits 020 and 007, causing the group members\n*losing* write access, and other folks *losing* all access, from the\nresulting filesystem entity.  But with this, as the description\nsays, you would write \"0640\" to mean \"group members cannot write,\nothers have no access\".\n\nHow about calling it <perm> (or <perm-bits>)?\n\n----- >8 --------- >8 --------- >8 --------- >8 -----\nFrom: Jean-Noël Avila <jn.avila@free.fr>\nSubject: [PATCH] doc: git-init: clarify file modes in octal.\n\nThe previous explanation was mixing the format with the identity of\nthe field.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n * Giving a \"3-digit octal prefixed with `0`\" would work fine, but\n   technically, the value is parsed as an octal without the `0`\n   prefix and there is no requirement for the number of digits,\n   either.  But giving a stricter-than-necessary instruction is\n   probably a good idea in this case.  It makes the description\n   simpler.\n\n Documentation/git-init.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex fdb7b3f367..af0d2ee182 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n+--shared[=(false|true|umask|group|all|world|everybody|<perm>)]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\n@@ -110,13 +110,15 @@ the repository permissions.\n \n Same as 'group', but make the repository readable by all users.\n \n-'0xxx'::\n+'<perm>'::\n \n-'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n-override users' umask(2) value (and not only loosen permissions as 'group' and\n-'all' does). '0640' will create a repository which is group-readable, but not\n-group-writable or accessible to others. '0660' will create a repo that is\n-readable and writable to the current user and group, but inaccessible to others.\n+'<perm>' is an 3-digit octal number prefixed with `0` and each file\n+will have mode '<perm>'. '<perm>' will override users' umask(2)\n+value (and not only loosen permissions as 'group' and 'all'\n+does). '0640' will create a repository which is group-readable, but\n+not group-writable or accessible to others. '0660' will create a repo\n+that is readable and writable to the current user and group, but\n+inaccessible to others.\n --\n \n By default, the configuration flag `receive.denyNonFastForwards` is enabled\n-- \n2.33.1-984-g9137471b0c\n"},{"id":"439901","messageId":"xmqqcznprrik.fsf@gitster.g","threadId":"56788","inReplyTo":"xmqqilxhrrva.fsf@gitster.g","subject":"Re: [PATCH v2 9/9] doc: git-init: clarify file modes in octal.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T17:25:07Z","receivedAt":"2021-10-28T17:25:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> How about calling it <perm> (or <perm-bits>)?\n\nI think it is better to queue your original as-is, as a part of the\ntopic whose theme is to correct the formatting and phrasing without\nchanging the spirit of the existing text.\n\nFixing the \"umask confusion\" should be left to a separate patch on\ntop.\n\n----- >8 --------- >8 --------- >8 --------- >8 -----\nSubject: init doc: --shared=0xxx does not give umask but perm bits\n\nThe description that 0640 makes sure that the group members can read\nthe repository is correct, but calling that octal number a <umask>\nis wrong.  Let's call it <perm>, as the value is used to set the\npermission bits.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-init.txt | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git c/Documentation/git-init.txt w/Documentation/git-init.txt\nindex af0d2ee182..42268ada22 100644\n--- c/Documentation/git-init.txt\n+++ w/Documentation/git-init.txt\n@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n---shared[=(false|true|umask|group|all|world|everybody|<umask>)]::\n+--shared[=(false|true|umask|group|all|world|everybody|<perm>)]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\n@@ -110,15 +110,16 @@ the repository permissions.\n \n Same as 'group', but make the repository readable by all users.\n \n-'<umask>'::\n+'<perm>'::\n \n-'<umask>' is an 3-digit octal number prefixed with `0` and each file\n-will have mode '<umask>'. '<umask>' will override users' umask(2)\n+'<perm>' is an 3-digit octal number prefixed with `0` and each file\n+will have mode '<perm>'. '<perm>' will override users' umask(2)\n value (and not only loosen permissions as 'group' and 'all'\n does). '0640' will create a repository which is group-readable, but\n not group-writable or accessible to others. '0660' will create a repo\n that is readable and writable to the current user and group, but\n-inaccessible to others.\n+inaccessible to others (directories and executable files get their\n+`x` bit from the `r` bit for corresponding classes of uses).\n --\n \n By default, the configuration flag `receive.denyNonFastForwards` is enabled\n"},{"id":"439905","messageId":"CAPig+cR4j_jPLJs-sQAAuNQ5cEqbO0ibck-czOBy=difgi50VQ@mail.gmail.com","threadId":"56788","inReplyTo":"4d2d198f57294d8307453bda784bf5efe5905f45.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/9] doc: express grammar placeholders between angle brackets","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-10-28T17:46:17Z","receivedAt":"2021-10-28T17:46:31Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, Oct 28, 2021 at 12:22 PM Jean-Noël Avila via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n> doc: express grammar placeholders between angle brackets\n>\n> This rules discerns user inputs from verbatim options in the\n> synopsis.\n\nMaybe: s/rules//\n\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\n> @@ -145,7 +145,7 @@ See also <<FILES>>.\n> --f config-file::\n> +-f <config-file>::\n>  --file config-file::\n\nYou need to fix the `--file` item as well (mentioned in my v1 review):\n\n    --file <config-file>::\n\n> @@ -281,7 +281,7 @@ Valid `<type>`'s include:\n>  --default <value>::\n>    When using `--get`, and the requested variable is not found, behave as if\n> -  <value> were the value assigned to the that variable.\n> +  `<value>` were the value assigned to the that variable.\n\nThis change seems out of place in this patch which claims only to be\nadding angle brackets.\n"},{"id":"439906","messageId":"xmqq8rydrq7p.fsf@gitster.g","threadId":"56788","inReplyTo":"8f85da3bb4ad1ca0c864d925b621426bb38ca5bb.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 7/9] doc: uniformize <URL> placeholders' case","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T17:53:14Z","receivedAt":"2021-10-28T17:53:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\"  <gitgitgadget@gmail.com> writes:\n\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>\n> URL being an acronym, it deserves to be kept uppercase.\n\nYes!  Thanks.\n"},{"id":"439907","messageId":"xmqq4k91rq42.fsf@gitster.g","threadId":"56788","inReplyTo":"20900b019f835e9293fb5d70ae8dbdced3b781c0.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 8/9] doc: git-http-push: describe the refs as pattern pairs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T17:55:25Z","receivedAt":"2021-10-28T17:55:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\"  <gitgitgadget@gmail.com> writes:\n\n> -Each pattern pair consists of the source side (before the colon)\n> -and the destination side (after the colon).  The ref to be\n> -pushed is determined by finding a match that matches the source\n> -side, and where it is pushed is determined by using the\n> -destination side.\n> +Each pattern pair '<src>:<dst>' consists of the source side (before\n> +the colon) and the destination side (after the colon).  The ref to be\n> +pushed is determined by finding a match that matches the source side,\n> +and where it is pushed is determined by using the destination side.\n\nLooks good.  It is unfortunate that this does not share the text\nwith description of refspec in \"git push\" documentation page, but\nlet's not worry about it too much.  I think we will probably start\ntalking about deprecating \"git http-push\".  Who still uses it and\nwhy, I do not think of a good reason offhand.\n\nThanks.\n"},{"id":"439917","messageId":"CAN0heSqFNULMRGCHGAWfSj6cQ_N2-OoGm3KTc3Kzy=MwzJQWxw@mail.gmail.com","threadId":"56788","inReplyTo":"0045fe6faeaa2beb63a1e63b3b7573ae06cfba38.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/9] doc: split placeholders as individual tokens","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-10-28T18:45:46Z","receivedAt":"2021-10-28T18:46:00Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 28 Oct 2021 at 18:22, Jean-Noël Avila via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>  archives that it imports, it is also possible to specify Git branch names\n> -manually.  To do so, write a Git branch name after each <archive/branch>\n> +manually.  To do so, write a Git branch name after each <archive>/<branch>\n>  parameter, separated by a colon.  This way, you can shorten the Arch\n\n> -<archive/branch>::\n> -       Archive/branch identifier in a format that `tla log` understands.\n> +<archive>/<branch>::\n> +       <archive>/<branch> identifier in a format that `tla log` understands.\n\nThis patch looks good to me. Maybe these \"<archive>/<branch>\" should go\nin SQs, but that should be outside the scope of this patch (and this\nseries is big enough anyway). This last instance here adds a new\ninstance of this pattern, but it's an existing pattern and you're\nfollowing the local convention.\n\n\nMartin\n"},{"id":"439918","messageId":"CAN0heSpHfCNLL3X=eLQMe6RV8mtNq3pYEZYohc4HqzfnP1tdsw@mail.gmail.com","threadId":"56788","inReplyTo":"984b6d687a2e779c775de6ea80536afe6ecc0aaf.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-10-28T18:47:21Z","receivedAt":"2021-10-28T18:47:38Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 28 Oct 2021 at 18:22, Jean-Noël Avila via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> -       It is `<unix timestamp> <time zone offset>`, where `<unix\n> +       It is `<unix-timestamp> <time-zone-offset>`, where `<unix-\n>         timestamp>` is the number of seconds since the UNIX epoch.\n\nThis still effectively has a space -- it renders as \"<unix- timestamp>\".\nYou'll probably need to rewrap the lines a little to get rid of that.\n\n> -** 'separator=<SEP>': specify a separator inserted between trailer\n> +** 'separator=<sep>': specify a separator inserted between trailer\n>     lines. When this option is not given each trailer line is\n>     terminated with a line feed character. The string SEP may contain\n\ns/SEP/<sep>/ ?\n\nThanks for taking on this large task.\n\n\nMartin\n"},{"id":"439919","messageId":"CAN0heSpQpW8HN9FW9ZyuyU33Mn6WoMhL49knWsdKijH-n6erhg@mail.gmail.com","threadId":"56788","inReplyTo":"819ab0ed-8a99-2987-79c9-88cd1118b51b@free.fr","subject":"Re: [PATCH] doc: fix grammar rules in commands'syntax","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-10-28T18:47:37Z","receivedAt":"2021-10-28T18:47:52Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 28 Oct 2021 at 11:32, Jean-Noël Avila <jn.avila@free.fr> wrote:\n>\n> Le 27/10/2021 à 20:56, Martin Ågren a écrit :\n> > On Tue, 26 Oct 2021 at 21:35, Jean-Noël Avila via GitGitGadget\n> > <gitgitgadget@gmail.com> wrote:\n\n> >> -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n> >> +'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <cvsroot>]\n> >\n> >> -<CVS_module>::\n> >> +<CVS-module>::\n> >>         The CVS module you want to import. Relative to <CVSROOT>.\n> >\n> > Here's another \"<CVSROOT>\".\n>\n> Is this an environment variable or a placeholder?\n\nI don't know. I see that you've dropped this from v2. Makes sense.\n\n\nMartin\n"},{"id":"439926","messageId":"xmqqv91hq7il.fsf@gitster.g","threadId":"56788","inReplyTo":"pull.1066.v2.git.1635438124.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/9] doc: fix grammar rules in commands' syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T19:22:26Z","receivedAt":"2021-10-28T19:22:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\"  <gitgitgadget@gmail.com> writes:\n\n> There are command expressions which do not follow the grammar syntax rules.\n>\n> According to the coding guidelines, the placeholders must:\n>\n>  * be in small letters\n>  * enclosed in angle brackets\n>  * use hyphens as spaces\n>\n> They also must represent tokens' meaning as atomic entities.\n>\n> Some fixups for git-credential, git-ls-files, git-init and git-http-push.\n>\n> changes since v1:\n>\n>  * split changes across simpler commits\n>\n> Signed-off-by: Jean-Noël Avila jn.avila@free.fr\n>\n> Jean-Noël Avila (9):\n>   doc: fix git credential synopsis\n>   doc: split placeholders as individual tokens\n>   doc: express grammar placeholders between angle brackets\n>   doc: use only hyphens as word separators in placeholders\n>   doc: git-ls-files: express options as optional alternatives\n>   doc: use three dots for indicating repetition instead of star\n>   doc: uniformize <URL> placeholders' case\n>   doc: git-http-push: describe the refs as pattern pairs\n>   doc: git-init: clarify file modes in octal.\n\nThanks.  All looked good to me.\n"},{"id":"439929","messageId":"xmqqee85q6wd.fsf@gitster.g","threadId":"56788","inReplyTo":"CAN0heSpHfCNLL3X=eLQMe6RV8mtNq3pYEZYohc4HqzfnP1tdsw@mail.gmail.com","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T19:35:46Z","receivedAt":"2021-10-28T19:35:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren <martin.agren@gmail.com> writes:\n\n> On Thu, 28 Oct 2021 at 18:22, Jean-Noël Avila via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>>\n>> -       It is `<unix timestamp> <time zone offset>`, where `<unix\n>> +       It is `<unix-timestamp> <time-zone-offset>`, where `<unix-\n>>         timestamp>` is the number of seconds since the UNIX epoch.\n>\n> This still effectively has a space -- it renders as \"<unix- timestamp>\".\n> You'll probably need to rewrap the lines a little to get rid of that.\n\nThanks for sharp eyes.  grep -e '<[^ ]*-$' Documentation/ spots only this\ninstance, so I'll fix it locally.\n\n\n>> -** 'separator=<SEP>': specify a separator inserted between trailer\n>> +** 'separator=<sep>': specify a separator inserted between trailer\n>>     lines. When this option is not given each trailer line is\n>>     terminated with a line feed character. The string SEP may contain\n>\n> s/SEP/<sep>/ ?\n\nAlso, this one.\n\n"},{"id":"439930","messageId":"xmqqa6itq6v4.fsf@gitster.g","threadId":"56788","inReplyTo":"CAPig+cR4j_jPLJs-sQAAuNQ5cEqbO0ibck-czOBy=difgi50VQ@mail.gmail.com","subject":"Re: [PATCH v2 3/9] doc: express grammar placeholders between angle brackets","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-28T19:36:31Z","receivedAt":"2021-10-28T19:36:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine <sunshine@sunshineco.com> writes:\n\n> On Thu, Oct 28, 2021 at 12:22 PM Jean-Noël Avila via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>> doc: express grammar placeholders between angle brackets\n>>\n>> This rules discerns user inputs from verbatim options in the\n>> synopsis.\n>\n> Maybe: s/rules//\n>\n>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>> ---\n>> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\n>> @@ -145,7 +145,7 @@ See also <<FILES>>.\n>> --f config-file::\n>> +-f <config-file>::\n>>  --file config-file::\n>\n> You need to fix the `--file` item as well (mentioned in my v1 review):\n>\n>     --file <config-file>::\n\nWill amend locally.\nThanks.\n"},{"id":"440205","messageId":"ee376004-a4dd-539d-28b3-3fc5baa6fe00@archlinux.org","threadId":"56788","inReplyTo":"984b6d687a2e779c775de6ea80536afe6ecc0aaf.1635438124.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Eli Schwartz","fromEmail":"eschwartz@archlinux.org","sentAt":"2021-10-31T18:58:56Z","receivedAt":"2021-10-31T18:59:18Z","isPatch":true,"sender":{"key":"eschwartz@archlinux.org","avatar":"https://avatars.githubusercontent.com/u/6551424?v=4"},"body":"On 10/28/21 12:21 PM, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> \n> According to CodingGuidelines, spaces and underscores are not\n> allowed in placeholders.\n\n\nI have a patch under review that touches the same files you are\nmodifying here. As I've been pointed to these changes, I'd like to make\na quick observation.\n\n\n> @@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is shown e.g. with\n>  `git log --raw`. To get full object names in a raw diff format,\n>  use `--no-abbrev`.\n>  \n> -* 'format:<string>'\n> +* 'format:<format-string>'\n>  +\n> -The 'format:<string>' format allows you to specify which information\n> +The 'format:<format-string>' format allows you to specify which information\n>  you want to show. It works a little bit like printf format,\n>  with the notable exception that you get a newline with '%n'\n>  instead of '\\n'.\n> @@ -273,12 +273,12 @@ endif::git-rev-list[]\n>  \t\t\t  If any option is provided multiple times the\n>  \t\t\t  last occurrence wins.\n>  +\n> -The boolean options accept an optional value `[=<BOOL>]`. The values\n> +The boolean options accept an optional value `[=<value>]`. The values\n\n\nHere you change \"BOOL\" to \"value\", below you change it to \"bool-value\".\n\n\n>  `true`, `false`, `on`, `off` etc. are all accepted. See the \"boolean\"\n>  sub-section in \"EXAMPLES\" in linkgit:git-config[1]. If a boolean\n>  option is given with no value, it's enabled.\n>  +\n> -** 'key=<K>': only show trailers with specified key. Matching is done\n> +** 'key=<key>': only show trailers with specified <key>. Matching is done\n>     case-insensitively and trailing colon is optional. If option is\n>     given multiple times trailer lines matching any of the keys are\n>     shown. This option automatically enables the `only` option so that\n> @@ -286,9 +286,9 @@ option is given with no value, it's enabled.\n>     desired it can be disabled with `only=false`.  E.g.,\n>     `%(trailers:key=Reviewed-by)` shows trailer lines with key\n>     `Reviewed-by`.\n> -** 'only[=<BOOL>]': select whether non-trailer lines from the trailer\n> +** 'only[=<bool-value>]': select whether non-trailer lines from the trailer\n>     block should be included.\n> -** 'separator=<SEP>': specify a separator inserted between trailer\n> +** 'separator=<sep>': specify a separator inserted between trailer\n>     lines. When this option is not given each trailer line is\n>     terminated with a line feed character. The string SEP may contain\n>     the literal formatting codes described above. To use comma as\n> @@ -296,15 +296,15 @@ option is given with no value, it's enabled.\n>     next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`\n>     shows all trailer lines whose key is \"Ticket\" separated by a comma\n>     and a space.\n> -** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`\n> +** 'unfold[=<bool-value>]': make it behave as if interpret-trailer's `--unfold`\n>     option was given. E.g.,\n>     `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.\n> -** 'keyonly[=<BOOL>]': only show the key part of the trailer.\n> -** 'valueonly[=<BOOL>]': only show the value part of the trailer.\n> -** 'key_value_separator=<SEP>': specify a separator inserted between\n> +** 'keyonly[=<bool-value>]': only show the key part of the trailer.\n> +** 'valueonly[=<bool-value>]': only show the value part of the trailer.\n> +** 'key_value_separator=<sep>': specify a separator inserted between\n>     trailer lines. When this option is not given each trailer key-value\n>     pair is separated by \": \". Otherwise it shares the same semantics\n> -   as 'separator=<SEP>' above.\n> +   as 'separator=<sep>' above.\n>  \n>  NOTE: Some placeholders may depend on other options given to the\n>  revision traversal engine. For example, the `%g*` reflog options will\n\n\nThese changes over here are contrary to the statement in the commit\nmessage. In addition to switching to hyphens, they:\n\n- switch casing (okay, makes sense, you point this out in the cover\n  letter but maybe it's worth mentioning it in the commit message too?\n  idk)\n\n- change the terms used -- and this I don't understand. I'm not really\n  bothered by switching <n> to <number> or <k> to <key>, as these\n  changes seem reasonable (though again, they are not mentioned in the\n  commit message). However, \"bool-value\" seems odd. Why that and not\n  \"number-value\"? IMHO the \"value\" is redundant here, let it be \"bool\"\n  and \"number\".\n\n  Similarly \"the 'format:<format-string>' format\" feels highly\n  redundant, I expect the reader knows that <string> contains a format\n  inside it as it's mentioned immediately before *and* after.\n\n-- \nEli Schwartz\nArch Linux Bug Wrangler and Trusted User\n"},{"id":"440206","messageId":"2803948.JoDkH9avOM@cayenne","threadId":"56788","inReplyTo":"ee376004-a4dd-539d-28b3-3fc5baa6fe00@archlinux.org","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2021-10-31T20:23:11Z","receivedAt":"2021-10-31T20:23:21Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le dimanche 31 octobre 2021, 19:58:56 CET Eli Schwartz a écrit :\n> On 10/28/21 12:21 PM, Jean-Noël Avila via GitGitGadget wrote:\n> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> > \n> > According to CodingGuidelines, spaces and underscores are not\n> > allowed in placeholders.\n> \n> \n> I have a patch under review that touches the same files you are\n> modifying here. As I've been pointed to these changes, I'd like to make\n> a quick observation.\n> \n> \n> > @@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is \nshown e.g. with\n> >  `git log --raw`. To get full object names in a raw diff format,\n> >  use `--no-abbrev`.\n> >  \n> > -* 'format:<string>'\n> > +* 'format:<format-string>'\n> >  +\n> > -The 'format:<string>' format allows you to specify which information\n> > +The 'format:<format-string>' format allows you to specify which \ninformation\n> >  you want to show. It works a little bit like printf format,\n> >  with the notable exception that you get a newline with '%n'\n> >  instead of '\\n'.\n> > @@ -273,12 +273,12 @@ endif::git-rev-list[]\n> >  \t\t\t  If any option is provided multiple times the\n> >  \t\t\t  last occurrence wins.\n> >  +\n> > -The boolean options accept an optional value `[=<BOOL>]`. The values\n> > +The boolean options accept an optional value `[=<value>]`. The values\n> \n> \n> Here you change \"BOOL\" to \"value\", below you change it to \"bool-value\".\n\nIndeed. Should be fixed.\n\n> \n> \n> >  `true`, `false`, `on`, `off` etc. are all accepted. See the \"boolean\"\n> >  sub-section in \"EXAMPLES\" in linkgit:git-config[1]. If a boolean\n> >  option is given with no value, it's enabled.\n> >  +\n> > -** 'key=<K>': only show trailers with specified key. Matching is done\n> > +** 'key=<key>': only show trailers with specified <key>. Matching is done\n> >     case-insensitively and trailing colon is optional. If option is\n> >     given multiple times trailer lines matching any of the keys are\n> >     shown. This option automatically enables the `only` option so that\n> > @@ -286,9 +286,9 @@ option is given with no value, it's enabled.\n> >     desired it can be disabled with `only=false`.  E.g.,\n> >     `%(trailers:key=Reviewed-by)` shows trailer lines with key\n> >     `Reviewed-by`.\n> > -** 'only[=<BOOL>]': select whether non-trailer lines from the trailer\n> > +** 'only[=<bool-value>]': select whether non-trailer lines from the \ntrailer\n> >     block should be included.\n> > -** 'separator=<SEP>': specify a separator inserted between trailer\n> > +** 'separator=<sep>': specify a separator inserted between trailer\n> >     lines. When this option is not given each trailer line is\n> >     terminated with a line feed character. The string SEP may contain\n> >     the literal formatting codes described above. To use comma as\n> > @@ -296,15 +296,15 @@ option is given with no value, it's enabled.\n> >     next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`\n> >     shows all trailer lines whose key is \"Ticket\" separated by a comma\n> >     and a space.\n> > -** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`\n> > +** 'unfold[=<bool-value>]': make it behave as if interpret-trailer's `--\nunfold`\n> >     option was given. E.g.,\n> >     `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.\n> > -** 'keyonly[=<BOOL>]': only show the key part of the trailer.\n> > -** 'valueonly[=<BOOL>]': only show the value part of the trailer.\n> > -** 'key_value_separator=<SEP>': specify a separator inserted between\n> > +** 'keyonly[=<bool-value>]': only show the key part of the trailer.\n> > +** 'valueonly[=<bool-value>]': only show the value part of the trailer.\n> > +** 'key_value_separator=<sep>': specify a separator inserted between\n> >     trailer lines. When this option is not given each trailer key-value\n> >     pair is separated by \": \". Otherwise it shares the same semantics\n> > -   as 'separator=<SEP>' above.\n> > +   as 'separator=<sep>' above.\n> >  \n> >  NOTE: Some placeholders may depend on other options given to the\n> >  revision traversal engine. For example, the `%g*` reflog options will\n> \n> \n> These changes over here are contrary to the statement in the commit\n> message. In addition to switching to hyphens, they:\n> \n> - switch casing (okay, makes sense, you point this out in the cover\n>   letter but maybe it's worth mentioning it in the commit message too?\n>   idk)\n> \n> - change the terms used -- and this I don't understand. I'm not really\n>   bothered by switching <n> to <number> or <k> to <key>, as these\n>   changes seem reasonable (though again, they are not mentioned in the\n>   commit message). However, \"bool-value\" seems odd. Why that and not\n>   \"number-value\"? IMHO the \"value\" is redundant here, let it be \"bool\"\n>   and \"number\".\n\nMy initial aim was to be more descriptive. The placeholders act as variables \nand you don't name variables with their types.\t\nFair enough, \"bool-value\" isn't the best example, but there are some facts \nthat drove these choices:\n * You can't expect manpage readers to be seasoned C programmers that \nunderstand what the word \"bool\" means. Using boolean-value, makes the \nreference to the description in the previous paragraph.\n * I'm facing a similar issue with translators. Some of them have some culture \nof computer science, but most of them are not programmers. Having more \nmeaningful placeholders helps them find a correct translation: this is a bool \nvalue, not the bool type.\n\nI did not push far to change all the placeholders that were not descriptive. \nMaybe another set of patches, if it is acceptable.\n\nThe choices here may be awkward; no problem to propose even more descriptive \nnames.\n\n> \n>   Similarly \"the 'format:<format-string>' format\" feels highly\n>   redundant, I expect the reader knows that <string> contains a format\n>   inside it as it's mentioned immediately before *and* after.\n> \n\nThe fact that it is a string doesn't tell you much about what you can do with \nit. For me, this isn't a problem that the explanation is redundant.\n\n\n\n\n"},{"id":"440214","messageId":"xmqqmtmocqz4.fsf@gitster.g","threadId":"56788","inReplyTo":"2803948.JoDkH9avOM@cayenne","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-01T06:47:11Z","receivedAt":"2021-11-01T06:47:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA <jn.avila@free.fr> writes:\n\n> The choices here may be awkward; no problem to propose even more descriptive \n> names.\n>\n>> \n>>   Similarly \"the 'format:<format-string>' format\" feels highly\n>>   redundant, I expect the reader knows that <string> contains a format\n>>   inside it as it's mentioned immediately before *and* after.\n>> \n>\n> The fact that it is a string doesn't tell you much about what you can do with \n> it. For me, this isn't a problem that the explanation is redundant.\n\nI agree that --format:<string> is quite poor, as type alone does not\ngive readers any information on what it means and how it is supposed\nto look like.  Calling it <format-string> does make quite a lot of\nsense.\n\nIt is a bit less obvious how much value we get out of <bool-value>,\nthough.  In --opt=<arg> scheme of things, what comes after '=' are\nall <value>s, so <bool-value> does not clarify over <bool> like the\nway <format-string> clarifies over <string>.\n\n"},{"id":"440374","messageId":"0b404448-cd4b-8614-2c49-c4683b56879f@gmail.com","threadId":"56788","inReplyTo":"xmqqmtmocqz4.fsf@gitster.g","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Jean-Noël Avila","fromEmail":"avila.jn@gmail.com","sentAt":"2021-11-03T12:46:39Z","receivedAt":"2021-11-03T12:46:45Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Junio C Hamano wrote:\n> Jean-Noël AVILA <jn.avila@free.fr> writes:\n>\n>> The choices here may be awkward; no problem to propose even more descriptive \n>> names.\n>>\n>>>   Similarly \"the 'format:<format-string>' format\" feels highly\n>>>   redundant, I expect the reader knows that <string> contains a format\n>>>   inside it as it's mentioned immediately before *and* after.\n>>>\n>> The fact that it is a string doesn't tell you much about what you can do with \n>> it. For me, this isn't a problem that the explanation is redundant.\n> I agree that --format:<string> is quite poor, as type alone does not\n> give readers any information on what it means and how it is supposed\n> to look like.  Calling it <format-string> does make quite a lot of\n> sense.\n>\n> It is a bit less obvious how much value we get out of <bool-value>,\n> though.  In --opt=<arg> scheme of things, what comes after '=' are\n> all <value>s, so <bool-value> does not clarify over <bool> like the\n> way <format-string> clarifies over <string>.\n>\nAgreed. Should reroll the patch series?\n\n"},{"id":"440380","messageId":"xmqqlf258aq3.fsf@gitster.g","threadId":"56788","inReplyTo":"0b404448-cd4b-8614-2c49-c4683b56879f@gmail.com","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-03T16:28:36Z","receivedAt":"2021-11-03T16:28:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila <avila.jn@gmail.com> writes:\n\n> Junio C Hamano wrote:\n>> Jean-Noël AVILA <jn.avila@free.fr> writes:\n>>\n>>> The choices here may be awkward; no problem to propose even more descriptive \n>>> names.\n>>>\n>>>>   Similarly \"the 'format:<format-string>' format\" feels highly\n>>>>   redundant, I expect the reader knows that <string> contains a format\n>>>>   inside it as it's mentioned immediately before *and* after.\n>>>>\n>>> The fact that it is a string doesn't tell you much about what you can do with \n>>> it. For me, this isn't a problem that the explanation is redundant.\n>> I agree that --format:<string> is quite poor, as type alone does not\n>> give readers any information on what it means and how it is supposed\n>> to look like.  Calling it <format-string> does make quite a lot of\n>> sense.\n>>\n>> It is a bit less obvious how much value we get out of <bool-value>,\n>> though.  In --opt=<arg> scheme of things, what comes after '=' are\n>> all <value>s, so <bool-value> does not clarify over <bool> like the\n>> way <format-string> clarifies over <string>.\n>>\n> Agreed. Should reroll the patch series?\n\nI guess another (hopefully the final) reroll would not hurt (but we\nare not in hurry---this may be among the topics that graduate early\nin the next cycle, but not during this cycle).\n\nThanks.\n"},{"id":"440418","messageId":"nycvar.QRO.7.76.6.2111040134110.56@tvgsbejvaqbjf.bet","threadId":"56788","inReplyTo":"xmqqlf258aq3.fsf@gitster.g","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2021-11-04T00:38:03Z","receivedAt":"2021-11-04T00:38:20Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Wed, 3 Nov 2021, Junio C Hamano wrote:\n\n> Jean-Noël Avila <avila.jn@gmail.com> writes:\n>\n> > Junio C Hamano wrote:\n> >> Jean-Noël AVILA <jn.avila@free.fr> writes:\n> >>\n> >>> The choices here may be awkward; no problem to propose even more descriptive\n> >>> names.\n> >>>\n> >>>>   Similarly \"the 'format:<format-string>' format\" feels highly\n> >>>>   redundant, I expect the reader knows that <string> contains a format\n> >>>>   inside it as it's mentioned immediately before *and* after.\n> >>>>\n> >>> The fact that it is a string doesn't tell you much about what you can do with\n> >>> it. For me, this isn't a problem that the explanation is redundant.\n> >> I agree that --format:<string> is quite poor, as type alone does not\n> >> give readers any information on what it means and how it is supposed\n> >> to look like.  Calling it <format-string> does make quite a lot of\n> >> sense.\n> >>\n> >> It is a bit less obvious how much value we get out of <bool-value>,\n> >> though.  In --opt=<arg> scheme of things, what comes after '=' are\n> >> all <value>s, so <bool-value> does not clarify over <bool> like the\n> >> way <format-string> clarifies over <string>.\n> >>\n> > Agreed. Should reroll the patch series?\n>\n> I guess another (hopefully the final) reroll would not hurt (but we\n> are not in hurry---this may be among the topics that graduate early\n> in the next cycle, but not during this cycle).\n\nI fear that it won't be as easy to send the next iteration as one might\nthink: GitGitGadget works off of open Pull Requests on GitHub. And the\nbranch for the Pull Request corresponding to this series has been deleted,\nthereby permanently closing the Pull Request (it cannot be reopened\nanymore): https://github.com/gitgitgadget/git/pull/1066#event-5541689437\n\nThat means that none of GitGitGadget's convenience can be used to send v3\nwith a range-diff. All that can be done at this point is to open a new\nPull Request, generate a range-diff manually (which could very easily\ndiffer from the actual range-diff, whether by design or mistake) and put\nit into the cover letter, then send a \"v3\" (which is actually a v1).\n\nCiao,\nJohannes\n"},{"id":"440473","messageId":"xmqqh7cr3jrp.fsf@gitster.g","threadId":"56788","inReplyTo":"nycvar.QRO.7.76.6.2111040134110.56@tvgsbejvaqbjf.bet","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-04T17:36:42Z","receivedAt":"2021-11-04T17:36:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n>> Jean-Noël Avila <avila.jn@gmail.com> writes:\n>> ...\n>> > Agreed. Should reroll the patch series?\n>>\n>> I guess another (hopefully the final) reroll would not hurt (but we\n>> are not in hurry---this may be among the topics that graduate early\n>> in the next cycle, but not during this cycle).\n>\n> I fear that it won't be as easy to send the next iteration as one might\n> think: GitGitGadget works off of open Pull Requests on GitHub. And ...\n> ...it into the cover letter, then send a \"v3\" (which is actually a v1).\n\nI see Jean-Noël is a long-time community member whose contribution\ndates back to 2012, which presumably predates GGG, so I suspect that\n\"contributors who use GGG cannot send a series without it\" would not\napply here.\n"},{"id":"440577","messageId":"20211106184858.11500-1-jn.avila@free.fr","threadId":"56788","inReplyTo":"pull.1066.git.1635261072531.gitgitgadget@gmail.com","subject":"[PATCH v3 00/10] doc: fix grammar rules in commands' syntax","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:48Z","receivedAt":"2021-11-06T18:49:28Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"There are command expressions which do not follow the grammar syntax rules.\n\nAccording to the coding guidelines, the placeholders must:\n\n * be in small letters\n * enclosed in angle brackets\n * use hyphens as spaces\n\nThey also must represent tokens' meaning as atomic entities.\n\nSome fixups for git-credential, git-ls-files, git-init and git-http-push.\n\nchanges since v1:\n\n * split changes across simpler commits\n\nchanges since v2:\n\n * remove back-quote formatting of placeholders from patches\n * revert renaming <bool> placeholder\n\nJean-Noël Avila (9):\n  doc: fix git credential synopsis\n  doc: split placeholders as individual tokens\n  doc: express grammar placeholders between angle brackets\n  doc: use only hyphens as word separators in placeholders\n  doc: git-ls-files: express options as optional alternatives\n  doc: use three dots for indicating repetition instead of star\n  doc: uniformize <URL> placeholders' case\n  doc: git-http-push: describe the refs as pattern pairs\n  doc: git-init: clarify file modes in octal.\n\nJunio C Hamano (1):\n  init doc: --shared=0xxx does not give umask but perm bits\n\n Documentation/date-formats.txt        |  6 +--\n Documentation/git-archimport.txt      | 14 +++----\n Documentation/git-checkout.txt        | 36 +++++++++---------\n Documentation/git-cherry-pick.txt     |  6 +--\n Documentation/git-clone.txt           |  8 ++--\n Documentation/git-config.txt          | 46 +++++++++++------------\n Documentation/git-credential.txt      |  2 +-\n Documentation/git-cvsexportcommit.txt |  4 +-\n Documentation/git-cvsimport.txt       |  8 ++--\n Documentation/git-diff-files.txt      |  2 +-\n Documentation/git-diff-index.txt      |  2 +-\n Documentation/git-diff-tree.txt       |  2 +-\n Documentation/git-fsck.txt            |  2 +-\n Documentation/git-gui.txt             |  2 +-\n Documentation/git-help.txt            |  6 +--\n Documentation/git-http-fetch.txt      |  2 +-\n Documentation/git-http-push.txt       | 15 ++++----\n Documentation/git-init-db.txt         |  2 +-\n Documentation/git-init.txt            | 27 ++++++++------\n Documentation/git-log.txt             |  8 ++--\n Documentation/git-ls-files.txt        |  6 +--\n Documentation/git-merge-index.txt     |  2 +-\n Documentation/git-p4.txt              |  8 ++--\n Documentation/git-pack-objects.txt    |  4 +-\n Documentation/git-pack-redundant.txt  |  2 +-\n Documentation/git-reflog.txt          |  4 +-\n Documentation/git-remote.txt          |  8 ++--\n Documentation/git-request-pull.txt    |  8 ++--\n Documentation/git-shortlog.txt        |  8 ++--\n Documentation/git-sparse-checkout.txt |  2 +-\n Documentation/git-stage.txt           |  2 +-\n Documentation/git-svn.txt             |  2 +-\n Documentation/git-web--browse.txt     |  2 +-\n Documentation/gitcredentials.txt      |  4 +-\n Documentation/gitsubmodules.txt       |  2 +-\n Documentation/gitworkflows.txt        |  6 +--\n Documentation/pretty-formats.txt      | 54 +++++++++++++--------------\n Documentation/urls-remotes.txt        |  8 ++--\n builtin/credential.c                  |  2 +-\n 39 files changed, 168 insertions(+), 166 deletions(-)\n\n-- \n2.33.1\n\n"},{"id":"440578","messageId":"20211106184858.11500-2-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 01/10] doc: fix git credential synopsis","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:49Z","receivedAt":"2021-11-06T18:49:34Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"The subcommand of git credential is not optional.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-credential.txt | 2 +-\n builtin/credential.c             | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 206e3c5f40..f18673017f 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials\n SYNOPSIS\n --------\n ------------------\n-git credential <fill|approve|reject>\n+'git credential' (fill|approve|reject)\n ------------------\n \n DESCRIPTION\ndiff --git a/builtin/credential.c b/builtin/credential.c\nindex d75dcdc64a..d7b304fa08 100644\n--- a/builtin/credential.c\n+++ b/builtin/credential.c\n@@ -4,7 +4,7 @@\n #include \"config.h\"\n \n static const char usage_msg[] =\n-\t\"git credential [fill|approve|reject]\";\n+\t\"git credential (fill|approve|reject)\";\n \n int cmd_credential(int argc, const char **argv, const char *prefix)\n {\n-- \n2.33.1\n\n"},{"id":"440579","messageId":"20211106184858.11500-3-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 02/10] doc: split placeholders as individual tokens","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:50Z","receivedAt":"2021-11-06T18:49:36Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"The placeholders represent atoms of tokens and must not be\naggregates.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-archimport.txt  | 14 +++++++-------\n Documentation/git-p4.txt          |  2 +-\n Documentation/git-web--browse.txt |  2 +-\n 3 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt\nindex a595a0ffee..847777fd17 100644\n--- a/Documentation/git-archimport.txt\n+++ b/Documentation/git-archimport.txt\n@@ -9,14 +9,14 @@ git-archimport - Import a GNU Arch repository into Git\n SYNOPSIS\n --------\n [verse]\n-'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]\n-               <archive/branch>[:<git-branch>] ...\n+'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]\n+\t       <archive>/<branch>[:<git-branch>]...\n \n DESCRIPTION\n -----------\n Imports a project from one or more GNU Arch repositories.\n It will follow branches\n-and repositories within the namespaces defined by the <archive/branch>\n+and repositories within the namespaces defined by the <archive>/<branch>\n parameters supplied. If it cannot find the remote branch a merge comes from\n it will just import it as a regular commit. If it can find it, it will mark it\n as a merge whenever possible (see discussion below).\n@@ -27,7 +27,7 @@ import new branches within the provided roots.\n \n It expects to be dealing with one project only. If it sees\n branches that have different roots, it will refuse to run. In that case,\n-edit your <archive/branch> parameters to define clearly the scope of the\n+edit your <archive>/<branch> parameters to define clearly the scope of the\n import.\n \n 'git archimport' uses `tla` extensively in the background to access the\n@@ -42,7 +42,7 @@ incremental imports.\n \n While 'git archimport' will try to create sensible branch names for the\n archives that it imports, it is also possible to specify Git branch names\n-manually.  To do so, write a Git branch name after each <archive/branch>\n+manually.  To do so, write a Git branch name after each <archive>/<branch>\n parameter, separated by a colon.  This way, you can shorten the Arch\n branch names and convert Arch jargon to Git jargon, for example mapping a\n \"PROJECT{litdd}devo{litdd}VERSION\" branch to \"master\".\n@@ -104,8 +104,8 @@ OPTIONS\n \tOverride the default tempdir.\n \n \n-<archive/branch>::\n-\tArchive/branch identifier in a format that `tla log` understands.\n+<archive>/<branch>::\n+\t<archive>/<branch> identifier in a format that `tla log` understands.\n \n \n GIT\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex 38e5257b2a..8a6addcf72 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -361,7 +361,7 @@ These options can be used to modify 'git p4 submit' behavior.\n \tp4/master.  See the \"Sync options\" section above for more\n \tinformation.\n \n---commit <sha1>|<sha1..sha1>::\n+--commit (<sha1>|<sha1>..<sha1>)::\n     Submit only the specified commit or range of commits, instead of the full\n     list of changes that are in the current Git branch.\n \ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex 8d162b56c5..f2f996cbe1 100644\n--- a/Documentation/git-web--browse.txt\n+++ b/Documentation/git-web--browse.txt\n@@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser\n SYNOPSIS\n --------\n [verse]\n-'git web{litdd}browse' [<options>] <url|file>...\n+'git web{litdd}browse' [<options>] (<URL>|<file>)...\n \n DESCRIPTION\n -----------\n-- \n2.33.1\n\n"},{"id":"440580","messageId":"20211106184858.11500-4-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 03/10] doc: express grammar placeholders between angle brackets","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:51Z","receivedAt":"2021-11-06T18:49:40Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This discerns user inputs from verbatim options in the synopsis.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-cherry-pick.txt     |  6 ++--\n Documentation/git-config.txt          | 46 +++++++++++++--------------\n Documentation/git-cvsexportcommit.txt |  4 +--\n Documentation/git-gui.txt             |  2 +-\n Documentation/git-help.txt            |  6 ++--\n Documentation/git-http-fetch.txt      |  2 +-\n Documentation/git-init.txt            |  2 +-\n Documentation/git-pack-objects.txt    |  4 +--\n Documentation/git-pack-redundant.txt  |  2 +-\n Documentation/git-reflog.txt          |  4 +--\n Documentation/git-sparse-checkout.txt |  2 +-\n Documentation/git-stage.txt           |  2 +-\n 12 files changed, 41 insertions(+), 41 deletions(-)\n\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 5d750314b2..78dcc9171f 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits\n SYNOPSIS\n --------\n [verse]\n-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]\n+'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]\n \t\t  [-S[<keyid>]] <commit>...\n 'git cherry-pick' (--continue | --skip | --abort | --quit)\n \n@@ -81,8 +81,8 @@ OPTIONS\n \tdescribed above, and `-r` was to disable it.  Now the\n \tdefault is not to do `-x` so this option is a no-op.\n \n--m parent-number::\n---mainline parent-number::\n+-m <parent-number>::\n+--mainline <parent-number>::\n \tUsually you cannot cherry-pick a merge because you do not know which\n \tside of the merge should be considered the mainline.  This\n \toption specifies the parent number (starting from 1) of\ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 992225f612..2285effb36 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -9,20 +9,20 @@ git-config - Get and set repository or global options\n SYNOPSIS\n --------\n [verse]\n-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]\n-'git config' [<file-option>] [--type=<type>] --add name value\n-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]\n-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL\n-'git config' [<file-option>] [--fixed-value] --unset name [value-pattern]\n-'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern]\n-'git config' [<file-option>] --rename-section old_name new_name\n-'git config' [<file-option>] --remove-section name\n+'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]\n+'git config' [<file-option>] [--type=<type>] --add <name> <value>\n+'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]\n+'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>\n+'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]\n+'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]\n+'git config' [<file-option>] --rename-section <old-name> <new-name>\n+'git config' [<file-option>] --remove-section <name>\n 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list\n-'git config' [<file-option>] --get-color name [default]\n-'git config' [<file-option>] --get-colorbool name [stdout-is-tty]\n+'git config' [<file-option>] --get-color <name> [<default>]\n+'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]\n 'git config' [<file-option>] -e | --edit\n \n DESCRIPTION\n@@ -102,9 +102,9 @@ OPTIONS\n \tin which section and variable names are lowercased, but subsection\n \tnames are not.\n \n---get-urlmatch name URL::\n+--get-urlmatch <name> <URL>::\n \tWhen given a two-part name section.key, the value for\n-\tsection.<url>.key whose <url> part matches the best to the\n+\tsection.<URL>.key whose <URL> part matches the best to the\n \tgiven URL is returned (if no such key exists, the value for\n \tsection.key is used as a fallback).  When given just the\n \tsection as name, do so for all the keys in the section and\n@@ -145,8 +145,8 @@ See also <<FILES>>.\n \tread from or written to if `extensions.worktreeConfig` is\n \tpresent. If not it's the same as `--local`.\n \n--f config-file::\n---file config-file::\n+-f <config-file>::\n+--file <config-file>::\n \tFor writing options: write to the specified file rather than the\n \trepository `.git/config`.\n +\n@@ -155,7 +155,7 @@ available files.\n +\n See also <<FILES>>.\n \n---blob blob::\n+--blob <blob>::\n \tSimilar to `--file` but use the given blob instead of a file. E.g.\n \tyou can use 'master:.gitmodules' to read values from the file\n \t'.gitmodules' in the master branch. See \"SPECIFYING REVISIONS\"\n@@ -246,18 +246,18 @@ Valid `<type>`'s include:\n \tall queried config options with the scope of that value\n \t(local, global, system, command).\n \n---get-colorbool name [stdout-is-tty]::\n+--get-colorbool <name> [<stdout-is-tty>]::\n \n-\tFind the color setting for `name` (e.g. `color.diff`) and output\n-\t\"true\" or \"false\".  `stdout-is-tty` should be either \"true\" or\n+\tFind the color setting for `<name>` (e.g. `color.diff`) and output\n+\t\"true\" or \"false\".  `<stdout-is-tty>` should be either \"true\" or\n \t\"false\", and is taken into account when configuration says\n-\t\"auto\".  If `stdout-is-tty` is missing, then checks the standard\n+\t\"auto\".  If `<stdout-is-tty>` is missing, then checks the standard\n \toutput of the command itself, and exits with status 0 if color\n \tis to be used, or exits with status 1 otherwise.\n \tWhen the color setting for `name` is undefined, the command uses\n \t`color.ui` as fallback.\n \n---get-color name [default]::\n+--get-color <name> [<default>]::\n \n \tFind the color configured for `name` (e.g. `color.diff.new`) and\n \toutput it as the ANSI color escape sequence to the standard\ndiff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt\nindex 00154b6c85..41c8a8a05c 100644\n--- a/Documentation/git-cvsexportcommit.txt\n+++ b/Documentation/git-cvsexportcommit.txt\n@@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout\n SYNOPSIS\n --------\n [verse]\n-'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]\n-\t[-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID\n+'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]\n+\t[-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt\nindex c9d7e96214..e8f3ccb433 100644\n--- a/Documentation/git-gui.txt\n+++ b/Documentation/git-gui.txt\n@@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git\n SYNOPSIS\n --------\n [verse]\n-'git gui' [<command>] [arguments]\n+'git gui' [<command>] [<arguments>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 96d5f598b4..44ea63cc6d 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -9,14 +9,14 @@ SYNOPSIS\n --------\n [verse]\n 'git help' [-a|--all [--[no-]verbose]]\n-\t   [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]\n+\t   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]\n 'git help' [-g|--guides]\n 'git help' [-c|--config]\n \n DESCRIPTION\n -----------\n \n-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'\n+With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'\n command and a list of the most commonly used Git commands are printed\n on the standard output.\n \n@@ -33,7 +33,7 @@ variables.\n \n If an alias is given, git shows the definition of the alias on\n standard output. To get the manual page for the aliased command, use\n-`git COMMAND --help`.\n+`git <command> --help`.\n \n Note that `git --help ...` is identical to `git help ...` because the\n former is internally converted into the latter.\ndiff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt\nindex 9fa17b60e4..fa4bb6cbc3 100644\n--- a/Documentation/git-http-fetch.txt\n+++ b/Documentation/git-http-fetch.txt\n@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP\n SYNOPSIS\n --------\n [verse]\n-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex b611d80697..7781d0b354 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n \t  [--separate-git-dir <git dir>] [--object-format=<format>]\n \t  [-b <branch-name> | --initial-branch=<branch-name>]\n-\t  [--shared[=<permissions>]] [directory]\n+\t  [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex dbfd1f9017..f8344e1e5b 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -13,8 +13,8 @@ SYNOPSIS\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n \t[--local] [--incremental] [--window=<n>] [--depth=<n>]\n \t[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]\n-\t[--stdout [--filter=<filter-spec>] | base-name]\n-\t[--shallow] [--keep-true-parents] [--[no-]sparse] < object-list\n+\t[--stdout [--filter=<filter-spec>] | <base-name>]\n+\t[--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt\nindex f2869da572..ee7034b5e5 100644\n--- a/Documentation/git-pack-redundant.txt\n+++ b/Documentation/git-pack-redundant.txt\n@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files\n SYNOPSIS\n --------\n [verse]\n-'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >\n+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex ff487ff77d..5ced7ad4f8 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -17,12 +17,12 @@ The command takes various subcommands, and different options\n depending on the subcommand:\n \n [verse]\n-'git reflog' ['show'] [log-options] [<ref>]\n+'git reflog' ['show'] [<log-options>] [<ref>]\n 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]\n 'git reflog delete' [--rewrite] [--updateref]\n-\t[--dry-run | -n] [--verbose] ref@\\{specifier\\}...\n+\t[--dry-run | -n] [--verbose] <ref>@\\{<specifier>\\}...\n 'git reflog exists' <ref>\n \n Reference logs, or \"reflogs\", record when the tips of branches and\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 42056ee9ff..9a78dd721e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -11,7 +11,7 @@ given by a list of patterns.\n SYNOPSIS\n --------\n [verse]\n-'git sparse-checkout <subcommand> [options]'\n+'git sparse-checkout <subcommand> [<options>]'\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt\nindex 25bcda936d..2f6aaa75b9 100644\n--- a/Documentation/git-stage.txt\n+++ b/Documentation/git-stage.txt\n@@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area\n SYNOPSIS\n --------\n [verse]\n-'git stage' args...\n+'git stage' <arg>...\n \n \n DESCRIPTION\n-- \n2.33.1\n\n"},{"id":"440581","messageId":"20211106184858.11500-5-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 04/10] doc: use only hyphens as word separators in placeholders","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:52Z","receivedAt":"2021-11-06T18:49:46Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"According to CodingGuidelines, multi-word placeholders should use\nhyphens as word separators.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\nReviewed-by: Eli Schwartz <eschwartz@archlinux.org>\n---\n Documentation/date-formats.txt   |  6 ++--\n Documentation/git-checkout.txt   | 36 ++++++++++-----------\n Documentation/git-clone.txt      |  8 ++---\n Documentation/git-cvsimport.txt  |  8 ++---\n Documentation/git-diff-files.txt |  2 +-\n Documentation/git-diff-index.txt |  2 +-\n Documentation/git-diff-tree.txt  |  2 +-\n Documentation/git-init-db.txt    |  2 +-\n Documentation/git-init.txt       |  8 ++---\n Documentation/git-log.txt        |  8 ++---\n Documentation/git-p4.txt         |  6 ++--\n Documentation/git-shortlog.txt   |  8 ++---\n Documentation/git-svn.txt        |  2 +-\n Documentation/pretty-formats.txt | 54 ++++++++++++++++----------------\n 14 files changed, 76 insertions(+), 76 deletions(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex 99c455f51c..67645cae64 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -5,9 +5,9 @@ The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables\n support the following date formats:\n \n Git internal format::\n-\tIt is `<unix timestamp> <time zone offset>`, where `<unix\n-\ttimestamp>` is the number of seconds since the UNIX epoch.\n-\t`<time zone offset>` is a positive or negative offset from UTC.\n+\tIt is `<unix-timestamp> <time-zone-offset>`, where\n+\t`<unix-timestamp>` is the number of seconds since the UNIX epoch.\n+\t`<time-zone-offset>` is a positive or negative offset from UTC.\n \tFor example CET (which is 1 hour ahead of UTC) is `+0100`.\n \n RFC 2822::\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d473c9bf38..a52dc49a3d 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n 'git checkout' [-q] [-f] [-m] [<branch>]\n 'git checkout' [-q] [-f] [-m] --detach [<branch>]\n 'git checkout' [-q] [-f] [-m] [--detach] <commit>\n-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]\n+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...\n 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]\n 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]\n@@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to\n rather expensive side-effects to show only the tracking information,\n if exists, for the current branch.\n \n-'git checkout' -b|-B <new_branch> [<start point>]::\n+'git checkout' -b|-B <new-branch> [<start-point>]::\n \n \tSpecifying `-b` causes a new branch to be created as if\n \tlinkgit:git-branch[1] were called and then checked out.  In\n@@ -52,11 +52,11 @@ if exists, for the current branch.\n \t`--track` without `-b` implies branch creation; see the\n \tdescription of `--track` below.\n +\n-If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it\n+If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it\n is reset. This is the transactional equivalent of\n +\n ------------\n-$ git branch -f <branch> [<start point>]\n+$ git branch -f <branch> [<start-point>]\n $ git checkout <branch>\n ------------\n +\n@@ -145,13 +145,13 @@ as `ours` (i.e. \"our shared canonical history\"), while what you did\n on your side branch as `theirs` (i.e. \"one contributor's work on top\n of it\").\n \n--b <new_branch>::\n-\tCreate a new branch named `<new_branch>` and start it at\n-\t`<start_point>`; see linkgit:git-branch[1] for details.\n+-b <new-branch>::\n+\tCreate a new branch named `<new-branch>` and start it at\n+\t`<start-point>`; see linkgit:git-branch[1] for details.\n \n--B <new_branch>::\n-\tCreates the branch `<new_branch>` and start it at `<start_point>`;\n-\tif it already exists, then reset it to `<start_point>`. This is\n+-B <new-branch>::\n+\tCreates the branch `<new-branch>` and start it at `<start-point>`;\n+\tif it already exists, then reset it to `<start-point>`. This is\n \tequivalent to running \"git branch\" with \"-f\"; see\n \tlinkgit:git-branch[1] for details.\n \n@@ -210,16 +210,16 @@ variable.\n \t`<commit>` is not a branch name.  See the \"DETACHED HEAD\" section\n \tbelow for details.\n \n---orphan <new_branch>::\n-\tCreate a new 'orphan' branch, named `<new_branch>`, started from\n-\t`<start_point>` and switch to it.  The first commit made on this\n+--orphan <new-branch>::\n+\tCreate a new 'orphan' branch, named `<new-branch>`, started from\n+\t`<start-point>` and switch to it.  The first commit made on this\n \tnew branch will have no parents and it will be the root of a new\n \thistory totally disconnected from all the other branches and\n \tcommits.\n +\n The index and the working tree are adjusted as if you had previously run\n-`git checkout <start_point>`.  This allows you to start a new history\n-that records a set of paths similar to `<start_point>` by easily running\n+`git checkout <start-point>`.  This allows you to start a new history\n+that records a set of paths similar to `<start-point>` by easily running\n `git commit -a` to make the root commit.\n +\n This can be useful when you want to publish the tree from a commit\n@@ -229,7 +229,7 @@ whose full history contains proprietary or otherwise encumbered bits of\n code.\n +\n If you want to start a disconnected history that records a set of paths\n-that is totally different from the one of `<start_point>`, then you should\n+that is totally different from the one of `<start-point>`, then you should\n clear the index and the working tree right after creating the orphan\n branch by running `git rm -rf .` from the top level of the working tree.\n Afterwards you will be ready to prepare your new files, repopulating the\n@@ -341,10 +341,10 @@ As a special case, you may use `A...B` as a shortcut for the\n merge base of `A` and `B` if there is exactly one merge base. You can\n leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.\n \n-<new_branch>::\n+<new-branch>::\n \tName for the new branch.\n \n-<start_point>::\n+<start-point>::\n \tThe name of a commit at which to start the new branch; see\n \tlinkgit:git-branch[1] for details. Defaults to `HEAD`.\n +\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 3fe3810f1c..9685ea0691 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -9,10 +9,10 @@ git-clone - Clone a repository into a new directory\n SYNOPSIS\n --------\n [verse]\n-'git clone' [--template=<template_directory>]\n+'git clone' [--template=<template-directory>]\n \t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n \t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n-\t  [--dissociate] [--separate-git-dir <git dir>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n \t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n \t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n \t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n@@ -211,7 +211,7 @@ objects from the source repository into a pack in the cloned repository.\n \tvia ssh, this specifies a non-default path for the command\n \trun on the other end.\n \n---template=<template_directory>::\n+--template=<template-directory>::\n \tSpecify the directory from which templates will be used;\n \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n \n@@ -294,7 +294,7 @@ or `--mirror` is given)\n \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n \t`git submodule update`.\n \n---separate-git-dir=<git dir>::\n+--separate-git-dir=<git-dir>::\n \tInstead of placing the cloned repository where it is supposed\n \tto be, place the cloned repository at the specified directory,\n \tthen make a filesystem-agnostic Git symbolic link to there.\ndiff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\nindex de1ebed67d..b3f27671a0 100644\n--- a/Documentation/git-cvsimport.txt\n+++ b/Documentation/git-cvsimport.txt\n@@ -11,9 +11,9 @@ SYNOPSIS\n [verse]\n 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]\n \t      [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]\n-\t      [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n-\t      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]\n-\t      [-r <remote>] [-R] [<CVS_module>]\n+\t      [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]\n+\t      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>]\n+\t      [-r <remote>] [-R] [<CVS-module>]\n \n \n DESCRIPTION\n@@ -59,7 +59,7 @@ OPTIONS\n \tfrom `CVS/Root`. If no such file exists, it checks for the\n \t`CVSROOT` environment variable.\n \n-<CVS_module>::\n+<CVS-module>::\n \tThe CVS module you want to import. Relative to <CVSROOT>.\n \tIf not given, 'git cvsimport' tries to read it from\n \t`CVS/Repository`.\ndiff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt\nindex 906774f0f7..bf1febb9ae 100644\n--- a/Documentation/git-diff-files.txt\n+++ b/Documentation/git-diff-files.txt\n@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index\n SYNOPSIS\n --------\n [verse]\n-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...]\n+'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt\nindex 27acb31cbf..679cae27d9 100644\n--- a/Documentation/git-diff-index.txt\n+++ b/Documentation/git-diff-index.txt\n@@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index\n SYNOPSIS\n --------\n [verse]\n-'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...]\n+'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 2fc24c542f..274d5eaba9 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]\n \t      [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]\n-\t      [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]\n+\t      [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt\nindex 648a6cd78a..18bf1a3c8c 100644\n--- a/Documentation/git-init-db.txt\n+++ b/Documentation/git-init-db.txt\n@@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository\n SYNOPSIS\n --------\n [verse]\n-'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]\n+'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 7781d0b354..fdb7b3f367 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -9,8 +9,8 @@ git-init - Create an empty Git repository or reinitialize an existing one\n SYNOPSIS\n --------\n [verse]\n-'git init' [-q | --quiet] [--bare] [--template=<template_directory>]\n-\t  [--separate-git-dir <git dir>] [--object-format=<format>]\n+'git init' [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t  [--separate-git-dir <git-dir>] [--object-format=<format>]\n \t  [-b <branch-name> | --initial-branch=<branch-name>]\n \t  [--shared[=<permissions>]] [<directory>]\n \n@@ -57,12 +57,12 @@ values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.\n +\n include::object-format-disclaimer.txt[]\n \n---template=<template_directory>::\n+--template=<template-directory>::\n \n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n---separate-git-dir=<git dir>::\n+--separate-git-dir=<git-dir>::\n \n Instead of initializing the repository as a directory to either `$GIT_DIR` or\n `./.git/`, create a text file there containing the path to the actual\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 0498e7bacb..20e87cecf4 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -9,7 +9,7 @@ git-log - Show commit logs\n SYNOPSIS\n --------\n [verse]\n-'git log' [<options>] [<revision range>] [[--] <path>...]\n+'git log' [<options>] [<revision-range>] [[--] <path>...]\n \n DESCRIPTION\n -----------\n@@ -81,13 +81,13 @@ produced by `--stat`, etc.\n \n include::line-range-options.txt[]\n \n-<revision range>::\n+<revision-range>::\n \tShow only commits in the specified revision range.  When no\n-\t<revision range> is specified, it defaults to `HEAD` (i.e. the\n+\t<revision-range> is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n \t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell <revision range>, see the 'Specifying Ranges'\n+\tways to spell <revision-range>, see the 'Specifying Ranges'\n \tsection of linkgit:gitrevisions[7].\n \n [--] <path>...::\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex 8a6addcf72..e21fcd8f71 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories\n SYNOPSIS\n --------\n [verse]\n-'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...\n-'git p4 sync' [<sync options>] [<p4 depot path>...]\n+'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>...\n+'git p4 sync' [<sync-options>] [<p4-depot-path>...]\n 'git p4 rebase'\n-'git p4 submit' [<submit options>] [<master branch name>]\n+'git p4 submit' [<submit-options>] [<master-branch-name>]\n \n \n DESCRIPTION\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex c9c7f3065c..f64e77047b 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output\n SYNOPSIS\n --------\n [verse]\n-'git shortlog' [<options>] [<revision range>] [[--] <path>...]\n+'git shortlog' [<options>] [<revision-range>] [[--] <path>...]\n git log --pretty=short | 'git shortlog' [<options>]\n \n DESCRIPTION\n@@ -89,13 +89,13 @@ counts both authors and co-authors.\n If width is `0` (zero) then indent the lines of the output without wrapping\n them.\n \n-<revision range>::\n+<revision-range>::\n \tShow only commits in the specified revision range.  When no\n-\t<revision range> is specified, it defaults to `HEAD` (i.e. the\n+\t<revision-range> is specified, it defaults to `HEAD` (i.e. the\n \twhole history leading to the current commit).  `origin..HEAD`\n \tspecifies all the commits reachable from the current commit\n \t(i.e. `HEAD`), but not from `origin`. For a complete list of\n-\tways to spell <revision range>, see the \"Specifying Ranges\"\n+\tways to spell <revision-range>, see the \"Specifying Ranges\"\n \tsection of linkgit:gitrevisions[7].\n \n [--] <path>...::\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 222b556d7a..4e92308e85 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -575,7 +575,7 @@ OPTIONS\n -------\n \n --shared[=(false|true|umask|group|all|world|everybody)]::\n---template=<template_directory>::\n+--template=<template-directory>::\n \tOnly used with the 'init' command.\n \tThese are passed directly to 'git init'.\n \ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex ef6bd420ae..23f6335887 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -20,7 +20,7 @@ built-in formats:\n \n * 'oneline'\n \n-\t  <hash> <title line>\n+\t  <hash> <title-line>\n +\n This is designed to be as compact as possible.\n \n@@ -29,17 +29,17 @@ This is designed to be as compact as possible.\n \t  commit <hash>\n \t  Author: <author>\n \n-\t      <title line>\n+\t      <title-line>\n \n * 'medium'\n \n \t  commit <hash>\n \t  Author: <author>\n-\t  Date:   <author date>\n+\t  Date:   <author-date>\n \n-\t      <title line>\n+\t      <title-line>\n \n-\t      <full commit message>\n+\t      <full-commit-message>\n \n * 'full'\n \n@@ -47,25 +47,25 @@ This is designed to be as compact as possible.\n \t  Author: <author>\n \t  Commit: <committer>\n \n-\t      <title line>\n+\t      <title-line>\n \n-\t      <full commit message>\n+\t      <full-commit-message>\n \n * 'fuller'\n \n \t  commit <hash>\n \t  Author:     <author>\n-\t  AuthorDate: <author date>\n+\t  AuthorDate: <author-date>\n \t  Commit:     <committer>\n-\t  CommitDate: <committer date>\n+\t  CommitDate: <committer-date>\n \n-\t       <title line>\n+\t       <title-line>\n \n-\t       <full commit message>\n+\t       <full-commit-message>\n \n * 'reference'\n \n-\t  <abbrev hash> (<title line>, <short author date>)\n+\t  <abbrev-hash> (<title-line>, <short-author-date>)\n +\n This format is used to refer to another commit in a commit message and\n is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,\n@@ -78,10 +78,10 @@ placeholders, its output is not affected by other options like\n \n \t  From <hash> <date>\n \t  From: <author>\n-\t  Date: <author date>\n-\t  Subject: [PATCH] <title line>\n+\t  Date: <author-date>\n+\t  Subject: [PATCH] <title-line>\n \n-\t  <full commit message>\n+\t  <full-commit-message>\n \n * 'mboxrd'\n +\n@@ -101,9 +101,9 @@ commits are displayed, but not the way the diff is shown e.g. with\n `git log --raw`. To get full object names in a raw diff format,\n use `--no-abbrev`.\n \n-* 'format:<string>'\n+* 'format:<format-string>'\n +\n-The 'format:<string>' format allows you to specify which information\n+The 'format:<format-string>' format allows you to specify which information\n you want to show. It works a little bit like printf format,\n with the notable exception that you get a newline with '%n'\n instead of '\\n'.\n@@ -273,12 +273,12 @@ endif::git-rev-list[]\n \t\t\t  If any option is provided multiple times the\n \t\t\t  last occurrence wins.\n +\n-The boolean options accept an optional value `[=<BOOL>]`. The values\n+The boolean options accept an optional value `[=<value>]`. The values\n `true`, `false`, `on`, `off` etc. are all accepted. See the \"boolean\"\n sub-section in \"EXAMPLES\" in linkgit:git-config[1]. If a boolean\n option is given with no value, it's enabled.\n +\n-** 'key=<K>': only show trailers with specified key. Matching is done\n+** 'key=<key>': only show trailers with specified <key>. Matching is done\n    case-insensitively and trailing colon is optional. If option is\n    given multiple times trailer lines matching any of the keys are\n    shown. This option automatically enables the `only` option so that\n@@ -286,25 +286,25 @@ option is given with no value, it's enabled.\n    desired it can be disabled with `only=false`.  E.g.,\n    `%(trailers:key=Reviewed-by)` shows trailer lines with key\n    `Reviewed-by`.\n-** 'only[=<BOOL>]': select whether non-trailer lines from the trailer\n+** 'only[=<bool>]': select whether non-trailer lines from the trailer\n    block should be included.\n-** 'separator=<SEP>': specify a separator inserted between trailer\n+** 'separator=<sep>': specify a separator inserted between trailer\n    lines. When this option is not given each trailer line is\n-   terminated with a line feed character. The string SEP may contain\n+   terminated with a line feed character. The string <sep> may contain\n    the literal formatting codes described above. To use comma as\n    separator one must use `%x2C` as it would otherwise be parsed as\n    next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`\n    shows all trailer lines whose key is \"Ticket\" separated by a comma\n    and a space.\n-** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold`\n+** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold`\n    option was given. E.g.,\n    `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.\n-** 'keyonly[=<BOOL>]': only show the key part of the trailer.\n-** 'valueonly[=<BOOL>]': only show the value part of the trailer.\n-** 'key_value_separator=<SEP>': specify a separator inserted between\n+** 'keyonly[=<bool>]': only show the key part of the trailer.\n+** 'valueonly[=<bool>]': only show the value part of the trailer.\n+** 'key_value_separator=<sep>': specify a separator inserted between\n    trailer lines. When this option is not given each trailer key-value\n    pair is separated by \": \". Otherwise it shares the same semantics\n-   as 'separator=<SEP>' above.\n+   as 'separator=<sep>' above.\n \n NOTE: Some placeholders may depend on other options given to the\n revision traversal engine. For example, the `%g*` reflog options will\n-- \n2.33.1\n\n"},{"id":"440582","messageId":"20211106184858.11500-6-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 05/10] doc: git-ls-files: express options as optional alternatives","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:53Z","receivedAt":"2021-11-06T18:49:49Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"That's how alternative options are expressed in general.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-ls-files.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 6d11ab506b..2e3d695fa2 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -10,9 +10,9 @@ SYNOPSIS\n --------\n [verse]\n 'git ls-files' [-z] [-t] [-v] [-f]\n-\t\t(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\n-\t\t(-[c|d|o|i|s|u|k|m])*\n-\t\t[--eol]\n+\t\t[-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored]\n+\t\t[-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified]\n+\t\t[--directory [--no-empty-directory]] [--eol]\n \t\t[--deduplicate]\n \t\t[-x <pattern>|--exclude=<pattern>]\n \t\t[-X <file>|--exclude-from=<file>]\n-- \n2.33.1\n\n"},{"id":"440583","messageId":"20211106184858.11500-7-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 06/10] doc: use three dots for indicating repetition instead of star","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:54Z","receivedAt":"2021-11-06T18:49:51Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This is how it is specified in CodingGuidelines.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-fsck.txt        | 2 +-\n Documentation/git-merge-index.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex bd596619c0..5088783dcc 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]\n \t [--[no-]full] [--strict] [--verbose] [--lost-found]\n \t [--[no-]dangling] [--[no-]progress] [--connectivity-only]\n-\t [--[no-]name-objects] [<object>*]\n+\t [--[no-]name-objects] [<object>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 2ab84a91e5..eea56b3154 100644\n--- a/Documentation/git-merge-index.txt\n+++ b/Documentation/git-merge-index.txt\n@@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging\n SYNOPSIS\n --------\n [verse]\n-'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)\n+'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) )\n \n DESCRIPTION\n -----------\n-- \n2.33.1\n\n"},{"id":"440584","messageId":"20211106184858.11500-8-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 07/10] doc: uniformize <URL> placeholders' case","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:55Z","receivedAt":"2021-11-06T18:49:57Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"URL being an acronym, it deserves to be kept uppercase.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-http-fetch.txt   | 2 +-\n Documentation/git-http-push.txt    | 2 +-\n Documentation/git-remote.txt       | 8 ++++----\n Documentation/git-request-pull.txt | 8 ++++----\n Documentation/gitcredentials.txt   | 4 ++--\n Documentation/gitsubmodules.txt    | 2 +-\n Documentation/gitworkflows.txt     | 6 +++---\n Documentation/urls-remotes.txt     | 8 ++++----\n 8 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt\nindex fa4bb6cbc3..319062c021 100644\n--- a/Documentation/git-http-fetch.txt\n+++ b/Documentation/git-http-fetch.txt\n@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP\n SYNOPSIS\n --------\n [verse]\n-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>\n+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt\nindex ea03a4eeb0..78f2bb7552 100644\n--- a/Documentation/git-http-push.txt\n+++ b/Documentation/git-http-push.txt\n@@ -9,7 +9,7 @@ git-http-push - Push objects over HTTP/DAV to another repository\n SYNOPSIS\n --------\n [verse]\n-'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...]\n+'git http-push' [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex 31c29c9b31..2bebc32566 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -10,7 +10,7 @@ SYNOPSIS\n --------\n [verse]\n 'git remote' [-v | --verbose]\n-'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url>\n+'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>\n 'git remote rename' <old> <new>\n 'git remote remove' <name>\n 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>)\n@@ -18,7 +18,7 @@ SYNOPSIS\n 'git remote get-url' [--push] [--all] <name>\n 'git remote set-url' [--push] <name> <newurl> [<oldurl>]\n 'git remote set-url --add' [--push] <name> <newurl>\n-'git remote set-url --delete' [--push] <name> <url>\n+'git remote set-url --delete' [--push] <name> <URL>\n 'git remote' [-v | --verbose] 'show' [-n] <name>...\n 'git remote prune' [-n | --dry-run] <name>...\n 'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]\n@@ -47,7 +47,7 @@ subcommands are available to perform operations on the remotes.\n 'add'::\n \n Add a remote named <name> for the repository at\n-<url>.  The command `git fetch <name>` can then be used to create and\n+<URL>.  The command `git fetch <name>` can then be used to create and\n update remote-tracking branches <name>/<branch>.\n +\n With `-f` option, `git fetch <name>` is run immediately after\n@@ -152,7 +152,7 @@ With `--push`, push URLs are manipulated instead of fetch URLs.\n With `--add`, instead of changing existing URLs, new URL is added.\n +\n With `--delete`, instead of changing existing URLs, all URLs matching\n-regex <url> are deleted for remote <name>.  Trying to delete all\n+regex <URL> are deleted for remote <name>.  Trying to delete all\n non-push URLs is an error.\n +\n Note that the push URL and the fetch URL, even though they can\ndiff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt\nindex 4d4392d0f8..fa5a426709 100644\n--- a/Documentation/git-request-pull.txt\n+++ b/Documentation/git-request-pull.txt\n@@ -8,7 +8,7 @@ git-request-pull - Generates a summary of pending changes\n SYNOPSIS\n --------\n [verse]\n-'git request-pull' [-p] <start> <url> [<end>]\n+'git request-pull' [-p] <start> <URL> [<end>]\n \n DESCRIPTION\n -----------\n@@ -21,7 +21,7 @@ the changes and indicates from where they can be pulled.\n The upstream project is expected to have the commit named by\n `<start>` and the output asks it to integrate the changes you made\n since that commit, up to the commit named by `<end>`, by visiting\n-the repository named by `<url>`.\n+the repository named by `<URL>`.\n \n \n OPTIONS\n@@ -33,14 +33,14 @@ OPTIONS\n \tCommit to start at.  This names a commit that is already in\n \tthe upstream history.\n \n-<url>::\n+<URL>::\n \tThe repository URL to be pulled from.\n \n <end>::\n \tCommit to end at (defaults to HEAD).  This names the commit\n \tat the tip of the history you are asking to be pulled.\n +\n-When the repository named by `<url>` has the commit at a tip of a\n+When the repository named by `<URL>` has the commit at a tip of a\n ref that is different from the ref you have locally, you can use the\n `<local>:<remote>` syntax, to have its local name, a colon `:`, and\n its remote name.\ndiff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt\nindex 758bf39ba3..80517b4eb2 100644\n--- a/Documentation/gitcredentials.txt\n+++ b/Documentation/gitcredentials.txt\n@@ -132,7 +132,7 @@ because the hostnames differ. Nor would it match `foo.example.com`; Git\n compares hostnames exactly, without considering whether two hosts are part of\n the same domain. Likewise, a config entry for `http://example.com` would not\n match: Git compares the protocols exactly.  However, you may use wildcards in\n-the domain name and other pattern matching techniques as with the `http.<url>.*`\n+the domain name and other pattern matching techniques as with the `http.<URL>.*`\n options.\n \n If the \"pattern\" URL does include a path component, then this too must match\n@@ -147,7 +147,7 @@ CONFIGURATION OPTIONS\n \n Options for a credential context can be configured either in\n `credential.*` (which applies to all credentials), or\n-`credential.<url>.*`, where <url> matches the context as described\n+`credential.<URL>.*`, where <URL> matches the context as described\n above.\n \n The following options are available in either location:\ndiff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt\nindex 891c8da4fd..941858a6ec 100644\n--- a/Documentation/gitsubmodules.txt\n+++ b/Documentation/gitsubmodules.txt\n@@ -226,7 +226,7 @@ Workflow for a third party library\n ----------------------------------\n \n   # Add a submodule\n-  git submodule add <url> <path>\n+  git submodule add <URL> <path>\n \n   # Occasionally update the submodule to a new version:\n   git -C <path> checkout <new version>\ndiff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt\nindex 47cf97f9be..59305265c5 100644\n--- a/Documentation/gitworkflows.txt\n+++ b/Documentation/gitworkflows.txt\n@@ -394,7 +394,7 @@ request to do so by mail.  Such a request looks like\n \n -------------------------------------\n Please pull from\n-    <url> <branch>\n+    <URL> <branch>\n -------------------------------------\n \n In that case, 'git pull' can do the fetch and merge in one go, as\n@@ -403,7 +403,7 @@ follows.\n .Push/pull: Merging remote topics\n [caption=\"Recipe: \"]\n =====================================\n-`git pull <url> <branch>`\n+`git pull <URL> <branch>`\n =====================================\n \n Occasionally, the maintainer may get merge conflicts when they try to\n@@ -440,7 +440,7 @@ merge because you cannot format-patch merges):\n .format-patch/am: Keeping topics up to date\n [caption=\"Recipe: \"]\n =====================================\n-`git pull --rebase <url> <branch>`\n+`git pull --rebase <URL> <branch>`\n =====================================\n \n You can then fix the conflicts during the rebase.  Presumably you have\ndiff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt\nindex bd184cd653..86d0008f94 100644\n--- a/Documentation/urls-remotes.txt\n+++ b/Documentation/urls-remotes.txt\n@@ -26,14 +26,14 @@ config file would appear like this:\n \n ------------\n \t[remote \"<name>\"]\n-\t\turl = <url>\n+\t\turl = <URL>\n \t\tpushurl = <pushurl>\n \t\tpush = <refspec>\n \t\tfetch = <refspec>\n ------------\n \n The `<pushurl>` is used for pushes only. It is optional and defaults\n-to `<url>`.\n+to `<URL>`.\n \n Named file in `$GIT_DIR/remotes`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n@@ -67,10 +67,10 @@ This file should have the following format:\n \n \n ------------\n-\t<url>#<head>\n+\t<URL>#<head>\n ------------\n \n-`<url>` is required; `#<head>` is optional.\n+`<URL>` is required; `#<head>` is optional.\n \n Depending on the operation, git will use one of the following\n refspecs, if you don't provide one on the command line.\n-- \n2.33.1\n\n"},{"id":"440585","messageId":"20211106184858.11500-9-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 08/10] doc: git-http-push: describe the refs as pattern pairs","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:56Z","receivedAt":"2021-11-06T18:49:58Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Each member of the pair is explained but they are not defined\nbeforehand.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-http-push.txt | 13 ++++++-------\n 1 file changed, 6 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt\nindex 78f2bb7552..7c6a6dd7f6 100644\n--- a/Documentation/git-http-push.txt\n+++ b/Documentation/git-http-push.txt\n@@ -63,16 +63,15 @@ of such patterns separated by a colon \":\" (this means that a ref name\n cannot have a colon in it).  A single pattern '<name>' is just a\n shorthand for '<name>:<name>'.\n \n-Each pattern pair consists of the source side (before the colon)\n-and the destination side (after the colon).  The ref to be\n-pushed is determined by finding a match that matches the source\n-side, and where it is pushed is determined by using the\n-destination side.\n+Each pattern pair '<src>:<dst>' consists of the source side (before\n+the colon) and the destination side (after the colon).  The ref to be\n+pushed is determined by finding a match that matches the source side,\n+and where it is pushed is determined by using the destination side.\n \n- - It is an error if <src> does not match exactly one of the\n+ - It is an error if '<src>' does not match exactly one of the\n    local refs.\n \n- - If <dst> does not match any remote ref, either\n+ - If '<dst>' does not match any remote ref, either\n \n    * it has to start with \"refs/\"; <dst> is used as the\n      destination literally in this case.\n-- \n2.33.1\n\n"},{"id":"440586","messageId":"20211106184858.11500-10-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 09/10] doc: git-init: clarify file modes in octal.","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:57Z","receivedAt":"2021-11-06T18:50:03Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"The previous explanation was mixing the format with the identity of\nthe field.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-init.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex fdb7b3f367..af0d2ee182 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n---shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n+--shared[=(false|true|umask|group|all|world|everybody|<umask>)]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\n@@ -110,13 +110,15 @@ the repository permissions.\n \n Same as 'group', but make the repository readable by all users.\n \n-'0xxx'::\n+'<umask>'::\n \n-'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n-override users' umask(2) value (and not only loosen permissions as 'group' and\n-'all' does). '0640' will create a repository which is group-readable, but not\n-group-writable or accessible to others. '0660' will create a repo that is\n-readable and writable to the current user and group, but inaccessible to others.\n+'<umask>' is an 3-digit octal number prefixed with `0` and each file\n+will have mode '<umask>'. '<umask>' will override users' umask(2)\n+value (and not only loosen permissions as 'group' and 'all'\n+does). '0640' will create a repository which is group-readable, but\n+not group-writable or accessible to others. '0660' will create a repo\n+that is readable and writable to the current user and group, but\n+inaccessible to others.\n --\n \n By default, the configuration flag `receive.denyNonFastForwards` is enabled\n-- \n2.33.1\n\n"},{"id":"440587","messageId":"20211106184858.11500-11-jn.avila@free.fr","threadId":"56788","inReplyTo":"20211106184858.11500-1-jn.avila@free.fr","subject":"[PATCH v3 10/10] init doc: --shared=0xxx does not give umask but perm bits","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2021-11-06T18:48:58Z","receivedAt":"2021-11-06T18:50:07Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: Junio C Hamano <gitster@pobox.com>\n\nThe description that 0640 makes sure that the group members can read\nthe repository is correct, but calling that octal number a <umask>\nis wrong.  Let's call it <perm>, as the value is used to set the\npermission bits.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/git-init.txt | 11 ++++++-----\n 1 file changed, 6 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex af0d2ee182..42268ada22 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n---shared[=(false|true|umask|group|all|world|everybody|<umask>)]::\n+--shared[=(false|true|umask|group|all|world|everybody|<perm>)]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\n@@ -110,15 +110,16 @@ the repository permissions.\n \n Same as 'group', but make the repository readable by all users.\n \n-'<umask>'::\n+'<perm>'::\n \n-'<umask>' is an 3-digit octal number prefixed with `0` and each file\n-will have mode '<umask>'. '<umask>' will override users' umask(2)\n+'<perm>' is an 3-digit octal number prefixed with `0` and each file\n+will have mode '<perm>'. '<perm>' will override users' umask(2)\n value (and not only loosen permissions as 'group' and 'all'\n does). '0640' will create a repository which is group-readable, but\n not group-writable or accessible to others. '0660' will create a repo\n that is readable and writable to the current user and group, but\n-inaccessible to others.\n+inaccessible to others (directories and executable files get their\n+`x` bit from the `r` bit for corresponding classes of uses).\n --\n \n By default, the configuration flag `receive.denyNonFastForwards` is enabled\n-- \n2.33.1\n\n"},{"id":"440637","messageId":"20211107132023.c5x6j6o3gmoroiyb@gmail.com","threadId":"56788","inReplyTo":"20211106184858.11500-10-jn.avila@free.fr","subject":"Re: [PATCH v3 09/10] doc: git-init: clarify file modes in octal.","fromName":"Johannes Altmanninger","fromEmail":"aclopte@gmail.com","sentAt":"2021-11-07T13:20:23Z","receivedAt":"2021-11-07T13:20:31Z","isPatch":true,"sender":{"key":"aclopte@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6853872?v=4"},"body":"On Sat, Nov 06, 2021 at 07:48:57PM +0100, Jean-Noël Avila wrote:\n> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\n> -'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will\n> +'<umask>' is an 3-digit octal number prefixed with `0` and each file\n\n\"an 3-digit\" should be \"a 3-digit\"\n"},{"id":"440638","messageId":"20211107132259.jntrqxu5jn5v3vcw@gmail.com","threadId":"56788","inReplyTo":"20211106184858.11500-11-jn.avila@free.fr","subject":"Re: [PATCH v3 10/10] init doc: --shared=0xxx does not give umask but perm bits","fromName":"Johannes Altmanninger","fromEmail":"aclopte@gmail.com","sentAt":"2021-11-07T13:22:59Z","receivedAt":"2021-11-07T13:23:05Z","isPatch":true,"sender":{"key":"aclopte@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6853872?v=4"},"body":"On Sat, Nov 06, 2021 at 07:48:58PM +0100, Jean-Noël Avila wrote:\n> From: Junio C Hamano <gitster@pobox.com>\n> \n> The description that 0640 makes sure that the group members can read\n> the repository is correct, but calling that octal number a <umask>\n> is wrong.  Let's call it <perm>, as the value is used to set the\n> permission bits.\n> \n> Signed-off-by: Junio C Hamano <gitster@pobox.com>\n> ---\n>  Documentation/git-init.txt | 11 ++++++-----\n>  1 file changed, 6 insertions(+), 5 deletions(-)\n> \n> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\n> index af0d2ee182..42268ada22 100644\n> --- a/Documentation/git-init.txt\n> +++ b/Documentation/git-init.txt\n> @@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently\n>  `master`, but this is subject to change in the future; the name can be\n>  customized via the `init.defaultBranch` configuration variable).\n>  \n> ---shared[=(false|true|umask|group|all|world|everybody|<umask>)]::\n> +--shared[=(false|true|umask|group|all|world|everybody|<perm>)]::\n>  \n>  Specify that the Git repository is to be shared amongst several users.  This\n>  allows users belonging to the same group to push into that\n> @@ -110,15 +110,16 @@ the repository permissions.\n>  \n>  Same as 'group', but make the repository readable by all users.\n>  \n> -'<umask>'::\n> +'<perm>'::\n>  \n> -'<umask>' is an 3-digit octal number prefixed with `0` and each file\n> -will have mode '<umask>'. '<umask>' will override users' umask(2)\n> +'<perm>' is an 3-digit octal number prefixed with `0` and each file\n> +will have mode '<perm>'. '<perm>' will override users' umask(2)\n>  value (and not only loosen permissions as 'group' and 'all'\n>  does). '0640' will create a repository which is group-readable, but\n>  not group-writable or accessible to others. '0660' will create a repo\n>  that is readable and writable to the current user and group, but\n> -inaccessible to others.\n> +inaccessible to others (directories and executable files get their\n> +`x` bit from the `r` bit for corresponding classes of uses).\n\nThis confused me until I realized that \"classes of uses\" should be \"classes of users\".\n\nOther than that the whole series looks great.\n"},{"id":"440639","messageId":"74eec375-e7e1-dd2a-870c-cd46d870a4e6@archlinux.org","threadId":"56788","inReplyTo":"nycvar.QRO.7.76.6.2111040134110.56@tvgsbejvaqbjf.bet","subject":"Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders","fromName":"Eli Schwartz","fromEmail":"eschwartz@archlinux.org","sentAt":"2021-11-07T12:40:08Z","receivedAt":"2021-11-07T14:41:49Z","isPatch":true,"sender":{"key":"eschwartz@archlinux.org","avatar":"https://avatars.githubusercontent.com/u/6551424?v=4"},"body":"On 11/3/21 8:38 PM, Johannes Schindelin wrote:\n> I fear that it won't be as easy to send the next iteration as one might\n> think: GitGitGadget works off of open Pull Requests on GitHub. And the\n> branch for the Pull Request corresponding to this series has been deleted,\n> thereby permanently closing the Pull Request (it cannot be reopened\n> anymore): https://github.com/gitgitgadget/git/pull/1066#event-5541689437\n\n\nIn fact, I know you *can* re-open such a PR. The author of the PR would\nneed to restore the branch in the fork, and ensure that the latest\ncommit on the branch is the same commit that it was when the branch got\ndeleted.\n\nI know this is possible because I've accidentally deleted branches that\nI thought were already merged, when they got reused for another PR that\nwas still open --I restored the PR by restoring the branch immediately,\nI *think* github may offer a button to do that on the PR webpage but I'm\nnot sure.\n\n\n-- \nEli Schwartz\nArch Linux Bug Wrangler and Trusted User\n"},{"id":"440754","messageId":"xmqqwnlh2q1y.fsf@gitster.g","threadId":"56788","inReplyTo":"20211107132259.jntrqxu5jn5v3vcw@gmail.com","subject":"Re: [PATCH v3 10/10] init doc: --shared=0xxx does not give umask but perm bits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-09T17:32:09Z","receivedAt":"2021-11-09T17:32:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Altmanninger <aclopte@gmail.com> writes:\n\n>> -inaccessible to others.\n>> +inaccessible to others (directories and executable files get their\n>> +`x` bit from the `r` bit for corresponding classes of uses).\n>\n> This confused me until I realized that \"classes of uses\" should be \"classes of users\".\n>\n> Other than that the whole series looks great.\n\nYou spotted two typos, if I count correctly?  I didn't see anything\nquestionable in the rest, so let me queue the patches with your\ntypofixes.\n\nThanks, both.\n\n"}]}