{"thread":{"id":"47281","subject":"[PATCH] doc: remove explanation of \"--\" from man pages","startedAt":"2017-11-21T21:13:29Z","lastAt":"2017-11-22T02:24:19Z","messageCount":3,"participants":["Robert P. J. Day","Kevin Daudt","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"333147","messageId":"alpine.LFD.2.21.1711211607200.25585@localhost.localdomain","threadId":"47281","inReplyTo":null,"subject":"[PATCH] doc: remove explanation of \"--\" from man pages","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-21T21:12:02Z","receivedAt":"2017-11-21T21:13:29Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\"man gitcli\" already explains the purpose of the \"--\" syntax, so there\nis no value to a small subset of Git commands explaining that in their\nman pages.\n\nSigned-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n\n---\n\n  i tried this once before, and i'm going to try to push it through\nagain ... it's pointless and inconsistent for less than a dozen man\npages to explicitly explain the purpose of \"--\" unless all of the man\npages do. as long as the \"--\" appears in the command SYNOPSIS, that\nshould be more than adequate.\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex b700beaff..69d625285 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -180,11 +180,6 @@ for \"git add --no-all <pathspec>...\", i.e. ignored removed files.\n \tbit is only changed in the index, the files on disk are left\n \tunchanged.\n\n-\\--::\n-\tThis option can be used to separate command-line options from\n-\tthe list of files, (useful when filenames might be mistaken\n-\tfor command-line options).\n-\n\n Configuration\n -------------\ndiff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt\nindex aa3b2bf2f..0ae2523e0 100644\n--- a/Documentation/git-check-attr.txt\n+++ b/Documentation/git-check-attr.txt\n@@ -36,10 +36,6 @@ OPTIONS\n \tIf `--stdin` is also given, input paths are separated\n \twith a NUL character instead of a linefeed character.\n\n-\\--::\n-\tInterpret all preceding arguments as attributes and all following\n-\targuments as path names.\n-\n If none of `--stdin`, `--all`, or `--` is used, the first argument\n will be treated as an attribute and the rest of the arguments as\n pathnames.\ndiff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt\nindex 4d33e7be0..11ee76e7d 100644\n--- a/Documentation/git-checkout-index.txt\n+++ b/Documentation/git-checkout-index.txt\n@@ -68,9 +68,6 @@ OPTIONS\n \tOnly meaningful with `--stdin`; paths are separated with\n \tNUL character instead of LF.\n\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n The order of the flags used to matter, but not anymore.\n\n Just doing `git checkout-index` does nothing. You probably meant\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 8c74a2ca0..cd9f362d1 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -334,9 +334,6 @@ changes to tracked files.\n \tCountermand `commit.gpgSign` configuration variable that is\n \tset to force each and every commit to be signed.\n\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n <file>...::\n \tWhen files are given on the command line, the command\n \tcommits the contents of the named files, without\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 18b494731..bac0b789c 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -282,10 +282,6 @@ providing this option will cause it to die.\n \tInstead of searching tracked files in the working tree, search\n \tblobs in the given trees.\n\n-\\--::\n-\tSignals the end of options; the rest of the parameters\n-\tare <pathspec> limiters.\n-\n <pathspec>...::\n \tIf given, limit the search to paths matching at least one pattern.\n \tBoth leading paths match and glob(7) patterns are supported.\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3ac3e3a77..c5cf3a488 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -176,9 +176,6 @@ Both the <eolinfo> in the index (\"i/<eolinfo>\")\n and in the working tree (\"w/<eolinfo>\") are shown for regular files,\n followed by the  (\"attr/<eolattr>\").\n\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n <file>::\n \tFiles to show. If no files are given all files which match the other\n \tspecified criteria are shown.\ndiff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt\nindex 02676fb39..51f884c7e 100644\n--- a/Documentation/git-merge-index.txt\n+++ b/Documentation/git-merge-index.txt\n@@ -20,9 +20,6 @@ files are passed as arguments 5, 6 and 7.\n\n OPTIONS\n -------\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n -a::\n \tRun merge against all files in the index that need merging.\n\ndiff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt\nindex 7a493c80f..39caa247a 100644\n--- a/Documentation/git-prune.txt\n+++ b/Documentation/git-prune.txt\n@@ -42,9 +42,6 @@ OPTIONS\n --verbose::\n \tReport all removed objects.\n\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n --expire <time>::\n \tOnly expire loose objects older than <time>.\n\ndiff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt\nindex b5c46223c..67ea38e46 100644\n--- a/Documentation/git-rm.txt\n+++ b/Documentation/git-rm.txt\n@@ -50,11 +50,6 @@ OPTIONS\n         Allow recursive removal when a leading directory name is\n         given.\n\n-\\--::\n-\tThis option can be used to separate command-line options from\n-\tthe list of files, (useful when filenames might be mistaken\n-\tfor command-line options).\n-\n --cached::\n \tUse this option to unstage and remove paths only from the index.\n \tWorking tree files, whether modified or not, will be\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex bdb034259..7d67704a9 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -218,9 +218,6 @@ will remove the intended effect of the option.\n \tthe configured value will take effect next time the index is\n \tread and this will remove the intended effect of the option.\n\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n <file>::\n \tFiles to act on.\n \tNote that files beginning with '.' are discarded. This includes\ndiff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt\nindex 61ca6d04c..b546c2192 100644\n--- a/Documentation/git-verify-pack.txt\n+++ b/Documentation/git-verify-pack.txt\n@@ -33,9 +33,6 @@ OPTIONS\n \tDo not verify the pack contents; only show the histogram of delta\n \tchain length.  With `--verbose`, list of objects is also shown.\n\n-\\--::\n-\tDo not interpret any more arguments as options.\n-\n OUTPUT FORMAT\n -------------\n When specifying the -v option the format used is:\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"333164","messageId":"20171121212305.GA16418@alpha.vpn.ikke.info","threadId":"47281","inReplyTo":"alpine.LFD.2.21.1711211607200.25585@localhost.localdomain","subject":"Re: [PATCH] doc: remove explanation of \"--\" from man pages","fromName":"Kevin Daudt","fromEmail":"me@ikke.info","sentAt":"2017-11-21T21:23:05Z","receivedAt":"2017-11-21T21:23:11Z","isPatch":true,"sender":{"key":"me@ikke.info","avatar":"https://avatars.githubusercontent.com/u/135698?v=4"},"body":"On Tue, Nov 21, 2017 at 04:12:02PM -0500, Robert P. J. Day wrote:\n> \"man gitcli\" already explains the purpose of the \"--\" syntax, so there\n> is no value to a small subset of Git commands explaining that in their\n> man pages.\n> \n> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n> \n> ---\n> \n>   i tried this once before, and i'm going to try to push it through\n> again ... it's pointless and inconsistent for less than a dozen man\n> pages to explicitly explain the purpose of \"--\" unless all of the man\n> pages do. as long as the \"--\" appears in the command SYNOPSIS, that\n> should be more than adequate.\n\nAlthough I agree that common options don't need to be explained\neverytime again, this change might make '--' even more obscure. To be\nhonest, I didn't even know about gitcli(7), let alone most new users.\n\nIn the #git irc channel we often have to explain what '--' means and\nwhy it's sometimes necessary.\n\nI don't however know a better solution to it more clear.\n\nKevin\n"},{"id":"333223","messageId":"xmqq1skrxd83.fsf@gitster.mtv.corp.google.com","threadId":"47281","inReplyTo":"20171121212305.GA16418@alpha.vpn.ikke.info","subject":"Re: [PATCH] doc: remove explanation of \"--\" from man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-22T02:24:12Z","receivedAt":"2017-11-22T02:24:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kevin Daudt <me@ikke.info> writes:\n\n> Although I agree that common options don't need to be explained\n> everytime again, this change might make '--' even more obscure. To be\n> honest, I didn't even know about gitcli(7), let alone most new users.\n>\n> In the #git irc channel we often have to explain what '--' means and\n> why it's sometimes necessary.\n>\n> I don't however know a better solution to it more clear.\n\nI do not agree with the starting thought of this patch in the first\nplace.  With the same logic, \"git help\" showing the most commonly\nused subcommands, as \"git help -a\" has all the information, is\nredundant and unwanted.  So is the synopsis section and \"git $cmd\n-h\" that shows only commonly used options but not necessarily all of\nthem.\n\nThere may be some git-$foo manual page that do not describe how '--'\nwould be useful for the specific $foo subcommand that would become\nmore helpful to new readers if they did, and I think updating them\nwould be a better approach if we wanted to have consistency across\nmanual pages.\n\n"}]}