{"thread":{"id":"47185","subject":"[PATCH] doc: Remove explanation of \"--\" from several man pages","startedAt":"2017-11-12T21:03:26Z","lastAt":"2017-11-13T09:56:53Z","messageCount":5,"participants":["Robert P. J. Day","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"332365","messageId":"alpine.LFD.2.21.1711121600170.7904@localhost.localdomain","threadId":"47185","inReplyTo":null,"subject":"[PATCH] doc: Remove explanation of \"--\" from several man pages","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-12T21:02:56Z","receivedAt":"2017-11-12T21:03:26Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"There is no value in individual man pages explaining the purpose of\nthe \"--\" separator.\n\nSigned-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n\n---\n\n  unless every man page explains that option, it's pointless to have\njust *some* man pages explaining it, so might as well remove it from\nall of them.\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 d153c17e0..93ebb020c 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -171,9 +171,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 75c7dd9de..3ff5b3460 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -201,9 +201,6 @@ will remove the intended effect of the option.\n \t`--untracked-cache` used to imply `--test-untracked-cache` but\n \tthis option would enable the extension unconditionally.\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":"332392","messageId":"xmqq8tfaak6s.fsf@gitster.mtv.corp.google.com","threadId":"47185","inReplyTo":"alpine.LFD.2.21.1711121600170.7904@localhost.localdomain","subject":"Re: [PATCH] doc: Remove explanation of \"--\" from several man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-13T04:15:07Z","receivedAt":"2017-11-13T04:15:14Z","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> There is no value in individual man pages explaining the purpose of\n> the \"--\" separator.\n>\n> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n>\n> ---\n>\n>   unless every man page explains that option, it's pointless to have\n> just *some* man pages explaining it, so might as well remove it from\n> all of them.\n\nPlease do not remove diffstat that format-patch gave you at this\npoint.  While commenting on the hunk on \"git add\", I wanted to see\nif you touched \"git rm\", and the diffstat at front _is_ the go-to\nplace to do so for reviewers.\n\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index 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\nI do not think if this removal alone is a good idea.  \n\nBefore this can happen, the description for \"--\" in other pages,\n(like gitcli(7), may need to be extended.  Right now, gitcli's\nmention of \"--\" is only about turning off disambiguation between\nrevs and pathspecs, and it does not cover this case\n\n\t$ >./--foo-bar\n\t$ git add -- --foo-bar\n\neven though the description you are removing would have helped the\nreader to understand why \"--\" is there.  The hunk on \"git rm\" shares\nthe same issue.\n\n>  Configuration\n>  -------------\n> diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt\n> index 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\nThis also has a similar issue.  \"--\" here is not between revs and\npathspecs but is between attributes and pathspecs.\n\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index d153c17e0..93ebb020c 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -171,9 +171,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\nThese removals would become a good idea, once we say that we would\nuse \"--\" to mean \"you will not see any --flags after this point\" (as\ncommonly seen in programs that are not Git) somewhere central like\ngitcli(7).\n"},{"id":"332399","messageId":"alpine.LFD.2.21.1711130357190.10471@localhost.localdomain","threadId":"47185","inReplyTo":"xmqq8tfaak6s.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: Remove explanation of \"--\" from several man pages","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-13T09:22:22Z","receivedAt":"2017-11-13T09:22:55Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Mon, 13 Nov 2017, Junio C Hamano wrote:\n\n> \"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n>\n> > There is no value in individual man pages explaining the purpose\n> > of the \"--\" separator.\n> >\n> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>\n> >\n> > ---\n> >\n> >   unless every man page explains that option, it's pointless to\n> > have just *some* man pages explaining it, so might as well remove\n> > it from all of them.\n>\n> Please do not remove diffstat that format-patch gave you at this\n> point.  While commenting on the hunk on \"git add\", I wanted to see\n> if you touched \"git rm\", and the diffstat at front _is_ the go-to\n> place to do so for reviewers.\n\n  apologies, won't happen again.\n\n> > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> > index 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> I do not think if this removal alone is a good idea.\n>\n> Before this can happen, the description for \"--\" in other pages,\n> (like gitcli(7), may need to be extended.  Right now, gitcli's\n> mention of \"--\" is only about turning off disambiguation between\n> revs and pathspecs, and it does not cover this case\n>\n> \t$ >./--foo-bar\n> \t$ git add -- --foo-bar\n>\n> even though the description you are removing would have helped the\n> reader to understand why \"--\" is there.  The hunk on \"git rm\" shares\n> the same issue.\n\n  i don't see the problem here ... in the above, \"--foobar\" is clearly\na pathspec. and if you think that's a special case that needs special\nexplanation, then that argument surely applies to several other\ncommands and their man pages.\n\n  the main point here is that it's inconsistent to have *some* man\npages explicitly explain \"--\" and not have *all* of them explain it.\neither they all should, or none of them should, and there's little\nvalue in suggesting that the occasional man page somehow deserves\nspecial treatment.\n\n> >  Configuration\n> >  -------------\n> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt\n> > index 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>\n> This also has a similar issue.  \"--\" here is not between revs and\n> pathspecs but is between attributes and pathspecs.\n\n  that can already be seen in the SYNOPSIS for that command, it does\nnot require further explanation:\n\n  SYNOPSIS\n       git check-attr [-a | --all | attr...] [--] pathname...\n\n> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> > index d153c17e0..93ebb020c 100644\n> > --- a/Documentation/git-ls-files.txt\n> > +++ b/Documentation/git-ls-files.txt\n> > @@ -171,9 +171,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> These removals would become a good idea, once we say that we would\n> use \"--\" to mean \"you will not see any --flags after this point\" (as\n> commonly seen in programs that are not Git) somewhere central like\n> gitcli(7).\n\n  if you want to suggest some wording to make that happen, that would\nbe great, but i'm standing by my opinion that there is no rationale\nfor *any* man page explaining what \"--\" means when, as far as i can\ntell, it always means the same thing.\n\nrday\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":"332400","messageId":"xmqqlgja8q74.fsf@gitster.mtv.corp.google.com","threadId":"47185","inReplyTo":"alpine.LFD.2.21.1711130357190.10471@localhost.localdomain","subject":"Re: [PATCH] doc: Remove explanation of \"--\" from several man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-11-13T09:48:15Z","receivedAt":"2017-11-13T09:48:28Z","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>> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt\n>> > index 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>>\n>> This also has a similar issue.  \"--\" here is not between revs and\n>> pathspecs but is between attributes and pathspecs.\n>\n>   that can already be seen in the SYNOPSIS for that command, it does\n> not require further explanation:\n>\n>   SYNOPSIS\n>        git check-attr [-a | --all | attr...] [--] pathname...\n\nNah.  With the same logic you could say --all is already on synopsis\nand no need for explanation.\n\nIf you are shooting for pedantic consistency, adding to pages that\nare missing would be less problematic than removing from the ones\nthat have them, especially given that people thought the use of\ndouble-dash in commands described on these pages are common or\nspecial enough to deserve extra attention.\n"},{"id":"332402","messageId":"alpine.LFD.2.21.1711130450570.11083@localhost.localdomain","threadId":"47185","inReplyTo":"xmqqlgja8q74.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: Remove explanation of \"--\" from several man pages","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-13T09:56:22Z","receivedAt":"2017-11-13T09:56:53Z","isPatch":true,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Mon, 13 Nov 2017, Junio C Hamano wrote:\n\n> \"Robert P. J. Day\" <rpjday@crashcourse.ca> writes:\n>\n> >> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt\n> >> > index 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> >>\n> >> This also has a similar issue.  \"--\" here is not between revs and\n> >> pathspecs but is between attributes and pathspecs.\n> >\n> >   that can already be seen in the SYNOPSIS for that command, it does\n> > not require further explanation:\n> >\n> >   SYNOPSIS\n> >        git check-attr [-a | --all | attr...] [--] pathname...\n>\n> Nah.  With the same logic you could say --all is already on synopsis\n> and no need for explanation.\n\n  uh, that's not what i meant. what i *meant* was that the purpose of\n\"--\" was already in the SYNOPSIS (as it appears to be in *all* man\npages) to visually show that it is a separator between the first part\nof the command and possible pathnames. i was *not* suggesting that, if\nsomething is in the SYNOPSIS, there is no further need to explain it.\n\n  anyway, i can see this is a losing battle so i'll let it go.\n\nrday\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"}]}