{"thread":{"id":"48567","subject":"[PATCH v2] Use proper syntax for replaceables in command docs","startedAt":"2018-05-24T20:13:27Z","lastAt":"2018-05-25T08:16:10Z","messageCount":3,"participants":["Robert P. J. Day","Simon Ruderich","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"348485","messageId":"alpine.LFD.2.21.1805241610030.7254@localhost.localdomain","threadId":"48567","inReplyTo":null,"subject":"[PATCH v2] Use proper syntax for replaceables in command docs","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2018-05-24T20:11:39Z","receivedAt":"2018-05-24T20:13:27Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"The standard for command documentation synopses appears to be:\n\n  [...] means optional\n  <...> means replaceable\n  [<...>] means both optional and replaceable\n\nSo fix a number of doc pages that use incorrect variations of the\nabove.\n\nSigned-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n\n---\n\ndiff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\nindex 05fd482b7..e44a83133 100644\n--- a/Documentation/git-annotate.txt\n+++ b/Documentation/git-annotate.txt\n@@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n SYNOPSIS\n --------\n [verse]\n-'git annotate' [options] file [revision]\n+'git annotate' [<options>] <file> [<revision>]\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt\nindex aa3b2bf2f..3c0578217 100644\n--- a/Documentation/git-check-attr.txt\n+++ b/Documentation/git-check-attr.txt\n@@ -9,8 +9,8 @@ git-check-attr - Display gitattributes information\n SYNOPSIS\n --------\n [verse]\n-'git check-attr' [-a | --all | attr...] [--] pathname...\n-'git check-attr' --stdin [-z] [-a | --all | attr...]\n+'git check-attr' [-a | --all | <attr>...] [--] <pathname>...\n+'git check-attr' --stdin [-z] [-a | --all | <attr>...]\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\nindex 611754f10..8b42cb3fb 100644\n--- a/Documentation/git-check-ignore.txt\n+++ b/Documentation/git-check-ignore.txt\n@@ -9,8 +9,8 @@ git-check-ignore - Debug gitignore / exclude files\n SYNOPSIS\n --------\n [verse]\n-'git check-ignore' [options] pathname...\n-'git check-ignore' [options] --stdin\n+'git check-ignore' [<options>] <pathname>...\n+'git check-ignore' [<options>] --stdin\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt\nindex 39028ee1a..aa2055dbe 100644\n--- a/Documentation/git-check-mailmap.txt\n+++ b/Documentation/git-check-mailmap.txt\n@@ -9,7 +9,7 @@ git-check-mailmap - Show canonical names and email addresses of contacts\n SYNOPSIS\n --------\n [verse]\n-'git check-mailmap' [options] <contact>...\n+'git check-mailmap' [<options>] <contact>...\n\n\n DESCRIPTION\ndiff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt\nindex 2b8582639..0216c18ef 100644\n--- a/Documentation/git-credential-cache.txt\n+++ b/Documentation/git-credential-cache.txt\n@@ -8,7 +8,7 @@ git-credential-cache - Helper to temporarily store passwords in memory\n SYNOPSIS\n --------\n -----------------------------\n-git config credential.helper 'cache [options]'\n+git config credential.helper 'cache [<options>]'\n -----------------------------\n\n DESCRIPTION\ndiff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt\nindex 25fb963f4..693dd9d9d 100644\n--- a/Documentation/git-credential-store.txt\n+++ b/Documentation/git-credential-store.txt\n@@ -8,7 +8,7 @@ git-credential-store - Helper to store credentials on disk\n SYNOPSIS\n --------\n -------------------\n-git config credential.helper 'store [options]'\n+git config credential.helper 'store [<options>]'\n -------------------\n\n DESCRIPTION\ndiff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt\nindex 37b96c545..f98b7c6ed 100644\n--- a/Documentation/git-cvsserver.txt\n+++ b/Documentation/git-cvsserver.txt\n@@ -22,7 +22,7 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver\n Usage:\n\n [verse]\n-'git-cvsserver' [options] [pserver|server] [<directory> ...]\n+'git-cvsserver' [<options>] [pserver|server] [<directory> ...]\n\n OPTIONS\n -------\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 7c2c44270..b180f1fa5 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -9,11 +9,11 @@ git-diff - Show changes between commits, commit and working tree, etc\n SYNOPSIS\n --------\n [verse]\n-'git diff' [options] [<commit>] [--] [<path>...]\n-'git diff' [options] --cached [<commit>] [--] [<path>...]\n-'git diff' [options] <commit> <commit> [--] [<path>...]\n-'git diff' [options] <blob> <blob>\n-'git diff' [options] --no-index [--] <path> <path>\n+'git diff' [<options>] [<commit>] [--] [<path>...]\n+'git diff' [<options>] --cached [<commit>] [--] [<path>...]\n+'git diff' [<options>] <commit> <commit> [--] [<path>...]\n+'git diff' [<options>] <blob> <blob>\n+'git diff' [<options>] --no-index [--] <path> <path>\n\n DESCRIPTION\n -----------\n@@ -21,7 +21,7 @@ Show changes between the working tree and the index or a tree, changes\n between the index and a tree, changes between two trees, changes between\n two blob objects, or changes between two files on disk.\n\n-'git diff' [options] [--] [<path>...]::\n+'git diff' [<options>] [--] [<path>...]::\n\n \tThis form is to view the changes you made relative to\n \tthe index (staging area for the next commit).  In other\n@@ -29,7 +29,7 @@ two blob objects, or changes between two files on disk.\n \tfurther add to the index but you still haven't.  You can\n \tstage these changes by using linkgit:git-add[1].\n\n-'git diff' [options] --no-index [--] <path> <path>::\n+'git diff' [<options>] --no-index [--] <path> <path>::\n\n \tThis form is to compare the given two paths on the\n \tfilesystem.  You can omit the `--no-index` option when\n@@ -38,7 +38,7 @@ two blob objects, or changes between two files on disk.\n \tor when running the command outside a working tree\n \tcontrolled by Git.\n\n-'git diff' [options] --cached [<commit>] [--] [<path>...]::\n+'git diff' [<options>] --cached [<commit>] [--] [<path>...]::\n\n \tThis form is to view the changes you staged for the next\n \tcommit relative to the named <commit>.  Typically you\n@@ -48,7 +48,7 @@ two blob objects, or changes between two files on disk.\n \t<commit> is not given, it shows all staged changes.\n \t--staged is a synonym of --cached.\n\n-'git diff' [options] <commit> [--] [<path>...]::\n+'git diff' [<options>] <commit> [--] [<path>...]::\n\n \tThis form is to view the changes you have in your\n \tworking tree relative to the named <commit>.  You can\n@@ -56,18 +56,18 @@ two blob objects, or changes between two files on disk.\n \tbranch name to compare with the tip of a different\n \tbranch.\n\n-'git diff' [options] <commit> <commit> [--] [<path>...]::\n+'git diff' [<options>] <commit> <commit> [--] [<path>...]::\n\n \tThis is to view the changes between two arbitrary\n \t<commit>.\n\n-'git diff' [options] <commit>..<commit> [--] [<path>...]::\n+'git diff' [<options>] <commit>..<commit> [--] [<path>...]::\n\n \tThis is synonymous to the previous form.  If <commit> on\n \tone side is omitted, it will have the same effect as\n \tusing HEAD instead.\n\n-'git diff' [options] <commit>\\...<commit> [--] [<path>...]::\n+'git diff' [<options>] <commit>\\...<commit> [--] [<path>...]::\n\n \tThis form is to view the changes on the branch containing\n \tand up to the second <commit>, starting at a common ancestor\n@@ -87,7 +87,7 @@ and the range notations (\"<commit>..<commit>\" and\n \"<commit>\\...<commit>\") do not mean a range as defined in the\n \"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n\n-'git diff' [options] <blob> <blob>::\n+'git diff' [<options>] <blob> <blob>::\n\n \tThis form is to view the differences between the raw\n \tcontents of two blob objects.\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 44098595d..ce954be53 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -9,7 +9,7 @@ git-fast-export - Git data exporter\n SYNOPSIS\n --------\n [verse]\n-'git fast-export [options]' | 'git fast-import'\n+'git fast-export [<options>]' | 'git fast-import'\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex cdf696ff7..e81117d27 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -9,7 +9,7 @@ git-fast-import - Backend for fast Git data importers\n SYNOPSIS\n --------\n [verse]\n-frontend | 'git fast-import' [options]\n+frontend | 'git fast-import' [<options>]\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt\nindex ff446f15f..9111c47a1 100644\n--- a/Documentation/git-interpret-trailers.txt\n+++ b/Documentation/git-interpret-trailers.txt\n@@ -8,8 +8,8 @@ git-interpret-trailers - add or parse structured information in commit messages\n SYNOPSIS\n --------\n [verse]\n-'git interpret-trailers' [options] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n-'git interpret-trailers' [options] [--parse] [<file>...]\n+'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]\n+'git interpret-trailers' [<options>] [--parse] [<file>...]\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt\nindex 4e0ad6fd8..118d9d86f 100644\n--- a/Documentation/git-pull.txt\n+++ b/Documentation/git-pull.txt\n@@ -9,7 +9,7 @@ git-pull - Fetch from and integrate with another repository or a local branch\n SYNOPSIS\n --------\n [verse]\n-'git pull' [options] [<repository> [<refspec>...]]\n+'git pull' [<options>] [<repository> [<refspec>...]]\n\n\n DESCRIPTION\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex bd5ecff98..0e20a66e7 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -8,9 +8,9 @@ git-rebase - Reapply commits on top of another base tip\n SYNOPSIS\n --------\n [verse]\n-'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]\n+'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]\n \t[<upstream> [<branch>]]\n-'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]\n+'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]\n \t--root [<branch>]\n 'git rebase' --continue | --skip | --abort | --quit | --edit-todo | --show-current-patch\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 95326b85f..e72d332b8 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -9,7 +9,7 @@ git-rev-parse - Pick out and massage parameters\n SYNOPSIS\n --------\n [verse]\n-'git rev-parse' [ --option ] <args>...\n+'git rev-parse' [<options>] <args>...\n\n DESCRIPTION\n -----------\n@@ -360,7 +360,7 @@ Example\n\n ------------\n OPTS_SPEC=\"\\\n-some-command [options] <args>...\n+some-command [<options>] <args>...\n\n some-command does foo and bar!\n --\n@@ -385,7 +385,7 @@ When `\"$@\"` is `-h` or `--help` in the above example, the following\n usage text would be shown:\n\n ------------\n-usage: some-command [options] <args>...\n+usage: some-command [<options>] <args>...\n\n     some-command does foo and bar!\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 464c15b94..4f3efde80 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -9,7 +9,7 @@ git-send-email - Send a collection of patches as emails\n SYNOPSIS\n --------\n [verse]\n-'git send-email' [options] <file|directory|rev-list options>...\n+'git send-email' [<options>] <file|directory|rev-list options>...\n 'git send-email' --dump-aliases\n\n\ndiff --git a/Documentation/git-show.txt b/Documentation/git-show.txt\nindex 0e1695df3..fcf528c1b 100644\n--- a/Documentation/git-show.txt\n+++ b/Documentation/git-show.txt\n@@ -9,7 +9,7 @@ git-show - Show various types of objects\n SYNOPSIS\n --------\n [verse]\n-'git show' [options] [<object>...]\n+'git show' [<options>] [<object>...]\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex e9615951d..7ea24fc94 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -8,7 +8,7 @@ git-svn - Bidirectional operation between a Subversion repository and Git\n SYNOPSIS\n --------\n [verse]\n-'git svn' <command> [options] [arguments]\n+'git svn' <command> [<options>] [<arguments>]\n\n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex a4ec25b45..fd952a5ff 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 -----------\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 9f13266a6..592e06d83 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -110,8 +110,8 @@ couple of magic command-line options:\n +\n ---------------------------------------------\n $ git describe -h\n-usage: git describe [options] <commit-ish>*\n-   or: git describe [options] --dirty\n+usage: git describe [<options>] <commit-ish>*\n+   or: git describe [<options>] --dirty\n\n     --contains            find the tag that comes after the commit\n     --debug               debug search strategy on stderr\n"},{"id":"348521","messageId":"20180525074137.GA10300@ruderich.org","threadId":"48567","inReplyTo":"alpine.LFD.2.21.1805241610030.7254@localhost.localdomain","subject":"Re: [PATCH v2] Use proper syntax for replaceables in command docs","fromName":"Simon Ruderich","fromEmail":"simon@ruderich.org","sentAt":"2018-05-25T07:41:37Z","receivedAt":"2018-05-25T07:41:42Z","isPatch":true,"sender":{"key":"simon@ruderich.org","avatar":"https://avatars.githubusercontent.com/u/390994?v=4"},"body":"On Thu, May 24, 2018 at 04:11:39PM -0400, Robert P. J. Day wrote:\n> diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt\n> index 37b96c545..f98b7c6ed 100644\n> --- a/Documentation/git-cvsserver.txt\n> +++ b/Documentation/git-cvsserver.txt\n> @@ -22,7 +22,7 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver\n>  Usage:\n>\n>  [verse]\n> -'git-cvsserver' [options] [pserver|server] [<directory> ...]\n> +'git-cvsserver' [<options>] [pserver|server] [<directory> ...]\n\nNo space in front of \"...\" for consistency?\n\nRegards\nSimon\n-- \n+ privacy is necessary\n+ using gnupg http://gnupg.org\n+ public key id: 0x92FEFDB7E44C32F9\n"},{"id":"348524","messageId":"xmqqlgc8noaj.fsf@gitster-ct.c.googlers.com","threadId":"48567","inReplyTo":"alpine.LFD.2.21.1805241610030.7254@localhost.localdomain","subject":"Re: [PATCH v2] Use proper syntax for replaceables in command docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-05-25T08:16:04Z","receivedAt":"2018-05-25T08:16:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n\n> The standard for command documentation synopses appears to be:\n>\n>   [...] means optional\n>   <...> means replaceable\n>   [<...>] means both optional and replaceable\n>\n> So fix a number of doc pages that use incorrect variations of the\n> above.\n>\n> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n>\n> ---\n>\n> diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt\n> index 05fd482b7..e44a83133 100644\n> --- a/Documentation/git-annotate.txt\n> +++ b/Documentation/git-annotate.txt\n> @@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git annotate' [options] file [revision]\n> +'git annotate' [<options>] <file> [<revision>]\n> ...\n> -'git check-mailmap' [options] <contact>...\n> +'git check-mailmap' [<options>] <contact>...\n\nA pedant in me screams s/<options>/<option>.../ after seeing this\nline, but <options> appears _very_ _very_ often and extremely handy,\ncompared to having to spell \"<option>...\".  So let's standardise\nthe way this patch does.\n\nThanks.\n"}]}