[PATCH] doc: Remove explanation of "--" from several man pages

[PATCH] doc: Remove explanation of "--" from several man pages

[Robert P. J. Day]

There is no value in individual man pages explaining the purpose of
the "--" separator.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

  unless every man page explains that option, it's pointless to have
just *some* man pages explaining it, so might as well remove it from
all of them.

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index b700beaff..69d625285 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -180,11 +180,6 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
 	bit is only changed in the index, the files on disk are left
 	unchanged.

-\--::
-	This option can be used to separate command-line options from
-	the list of files, (useful when filenames might be mistaken
-	for command-line options).
-

 Configuration
 -------------
diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
index aa3b2bf2f..0ae2523e0 100644
--- a/Documentation/git-check-attr.txt
+++ b/Documentation/git-check-attr.txt
@@ -36,10 +36,6 @@ OPTIONS
 	If `--stdin` is also given, input paths are separated
 	with a NUL character instead of a linefeed character.

-\--::
-	Interpret all preceding arguments as attributes and all following
-	arguments as path names.
-
 If none of `--stdin`, `--all`, or `--` is used, the first argument
 will be treated as an attribute and the rest of the arguments as
 pathnames.
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index 4d33e7be0..11ee76e7d 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -68,9 +68,6 @@ OPTIONS
 	Only meaningful with `--stdin`; paths are separated with
 	NUL character instead of LF.

-\--::
-	Do not interpret any more arguments as options.
-
 The order of the flags used to matter, but not anymore.

 Just doing `git checkout-index` does nothing. You probably meant
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 8c74a2ca0..cd9f362d1 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -334,9 +334,6 @@ changes to tracked files.
 	Countermand `commit.gpgSign` configuration variable that is
 	set to force each and every commit to be signed.

-\--::
-	Do not interpret any more arguments as options.
-
 <file>...::
 	When files are given on the command line, the command
 	commits the contents of the named files, without
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 18b494731..bac0b789c 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -282,10 +282,6 @@ providing this option will cause it to die.
 	Instead of searching tracked files in the working tree, search
 	blobs in the given trees.

-\--::
-	Signals the end of options; the rest of the parameters
-	are <pathspec> limiters.
-
 <pathspec>...::
 	If given, limit the search to paths matching at least one pattern.
 	Both leading paths match and glob(7) patterns are supported.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index d153c17e0..93ebb020c 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -171,9 +171,6 @@ Both the <eolinfo> in the index ("i/<eolinfo>")
 and in the working tree ("w/<eolinfo>") are shown for regular files,
 followed by the  ("attr/<eolattr>").

-\--::
-	Do not interpret any more arguments as options.
-
 <file>::
 	Files to show. If no files are given all files which match the other
 	specified criteria are shown.
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt
index 02676fb39..51f884c7e 100644
--- a/Documentation/git-merge-index.txt
+++ b/Documentation/git-merge-index.txt
@@ -20,9 +20,6 @@ files are passed as arguments 5, 6 and 7.

 OPTIONS
 -------
-\--::
-	Do not interpret any more arguments as options.
-
 -a::
 	Run merge against all files in the index that need merging.

diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt
index 7a493c80f..39caa247a 100644
--- a/Documentation/git-prune.txt
+++ b/Documentation/git-prune.txt
@@ -42,9 +42,6 @@ OPTIONS
 --verbose::
 	Report all removed objects.

-\--::
-	Do not interpret any more arguments as options.
-
 --expire <time>::
 	Only expire loose objects older than <time>.

diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt
index b5c46223c..67ea38e46 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.txt
@@ -50,11 +50,6 @@ OPTIONS
         Allow recursive removal when a leading directory name is
         given.

-\--::
-	This option can be used to separate command-line options from
-	the list of files, (useful when filenames might be mistaken
-	for command-line options).
-
 --cached::
 	Use this option to unstage and remove paths only from the index.
 	Working tree files, whether modified or not, will be
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 75c7dd9de..3ff5b3460 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -201,9 +201,6 @@ will remove the intended effect of the option.
 	`--untracked-cache` used to imply `--test-untracked-cache` but
 	this option would enable the extension unconditionally.

-\--::
-	Do not interpret any more arguments as options.
-
 <file>::
 	Files to act on.
 	Note that files beginning with '.' are discarded. This includes
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index 61ca6d04c..b546c2192 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -33,9 +33,6 @@ OPTIONS
 	Do not verify the pack contents; only show the histogram of delta
 	chain length.  With `--verbose`, list of objects is also shown.

-\--::
-	Do not interpret any more arguments as options.
-
 OUTPUT FORMAT
 -------------
 When specifying the -v option the format used is:

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH] doc: Remove explanation of "--" from several man pages

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

> There is no value in individual man pages explaining the purpose of
> the "--" separator.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
>   unless every man page explains that option, it's pointless to have
> just *some* man pages explaining it, so might as well remove it from
> all of them.

Please do not remove diffstat that format-patch gave you at this
point.  While commenting on the hunk on "git add", I wanted to see
if you touched "git rm", and the diffstat at front _is_ the go-to
place to do so for reviewers.

> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index b700beaff..69d625285 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -180,11 +180,6 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
>  	bit is only changed in the index, the files on disk are left
>  	unchanged.
>
> -\--::
> -	This option can be used to separate command-line options from
> -	the list of files, (useful when filenames might be mistaken
> -	for command-line options).
> -

I do not think if this removal alone is a good idea.  

Before this can happen, the description for "--" in other pages,
(like gitcli(7), may need to be extended.  Right now, gitcli's
mention of "--" is only about turning off disambiguation between
revs and pathspecs, and it does not cover this case

	$ >./--foo-bar
	$ git add -- --foo-bar

even though the description you are removing would have helped the
reader to understand why "--" is there.  The hunk on "git rm" shares
the same issue.

>  Configuration
>  -------------
> diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
> index aa3b2bf2f..0ae2523e0 100644
> --- a/Documentation/git-check-attr.txt
> +++ b/Documentation/git-check-attr.txt
> @@ -36,10 +36,6 @@ OPTIONS
>  	If `--stdin` is also given, input paths are separated
>  	with a NUL character instead of a linefeed character.
>
> -\--::
> -	Interpret all preceding arguments as attributes and all following
> -	arguments as path names.
> -

This also has a similar issue.  "--" here is not between revs and
pathspecs but is between attributes and pathspecs.

> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index d153c17e0..93ebb020c 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -171,9 +171,6 @@ Both the <eolinfo> in the index ("i/<eolinfo>")
>  and in the working tree ("w/<eolinfo>") are shown for regular files,
>  followed by the  ("attr/<eolattr>").
>
> -\--::
> -	Do not interpret any more arguments as options.

These removals would become a good idea, once we say that we would
use "--" to mean "you will not see any --flags after this point" (as
commonly seen in programs that are not Git) somewhere central like
gitcli(7).

Re: [PATCH] doc: Remove explanation of "--" from several man pages

[Robert P. J. Day]

On Mon, 13 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> > There is no value in individual man pages explaining the purpose
> > of the "--" separator.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
> >
> >   unless every man page explains that option, it's pointless to
> > have just *some* man pages explaining it, so might as well remove
> > it from all of them.
>
> Please do not remove diffstat that format-patch gave you at this
> point.  While commenting on the hunk on "git add", I wanted to see
> if you touched "git rm", and the diffstat at front _is_ the go-to
> place to do so for reviewers.

  apologies, won't happen again.

> > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> > index b700beaff..69d625285 100644
> > --- a/Documentation/git-add.txt
> > +++ b/Documentation/git-add.txt
> > @@ -180,11 +180,6 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
> >  	bit is only changed in the index, the files on disk are left
> >  	unchanged.
> >
> > -\--::
> > -	This option can be used to separate command-line options from
> > -	the list of files, (useful when filenames might be mistaken
> > -	for command-line options).
> > -
>
> I do not think if this removal alone is a good idea.
>
> Before this can happen, the description for "--" in other pages,
> (like gitcli(7), may need to be extended.  Right now, gitcli's
> mention of "--" is only about turning off disambiguation between
> revs and pathspecs, and it does not cover this case
>
> 	$ >./--foo-bar
> 	$ git add -- --foo-bar
>
> even though the description you are removing would have helped the
> reader to understand why "--" is there.  The hunk on "git rm" shares
> the same issue.

  i don't see the problem here ... in the above, "--foobar" is clearly
a pathspec. and if you think that's a special case that needs special
explanation, then that argument surely applies to several other
commands and their man pages.

  the main point here is that it's inconsistent to have *some* man
pages explicitly explain "--" and not have *all* of them explain it.
either they all should, or none of them should, and there's little
value in suggesting that the occasional man page somehow deserves
special treatment.

> >  Configuration
> >  -------------
> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
> > index aa3b2bf2f..0ae2523e0 100644
> > --- a/Documentation/git-check-attr.txt
> > +++ b/Documentation/git-check-attr.txt
> > @@ -36,10 +36,6 @@ OPTIONS
> >  	If `--stdin` is also given, input paths are separated
> >  	with a NUL character instead of a linefeed character.
> >
> > -\--::
> > -	Interpret all preceding arguments as attributes and all following
> > -	arguments as path names.
> > -
>
> This also has a similar issue.  "--" here is not between revs and
> pathspecs but is between attributes and pathspecs.

  that can already be seen in the SYNOPSIS for that command, it does
not require further explanation:

  SYNOPSIS
       git check-attr [-a | --all | attr...] [--] pathname...

> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> > index d153c17e0..93ebb020c 100644
> > --- a/Documentation/git-ls-files.txt
> > +++ b/Documentation/git-ls-files.txt
> > @@ -171,9 +171,6 @@ Both the <eolinfo> in the index ("i/<eolinfo>")
> >  and in the working tree ("w/<eolinfo>") are shown for regular files,
> >  followed by the  ("attr/<eolattr>").
> >
> > -\--::
> > -	Do not interpret any more arguments as options.
>
> These removals would become a good idea, once we say that we would
> use "--" to mean "you will not see any --flags after this point" (as
> commonly seen in programs that are not Git) somewhere central like
> gitcli(7).

  if you want to suggest some wording to make that happen, that would
be great, but i'm standing by my opinion that there is no rationale
for *any* man page explaining what "--" means when, as far as i can
tell, it always means the same thing.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH] doc: Remove explanation of "--" from several man pages

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
>> > index aa3b2bf2f..0ae2523e0 100644
>> > --- a/Documentation/git-check-attr.txt
>> > +++ b/Documentation/git-check-attr.txt
>> > @@ -36,10 +36,6 @@ OPTIONS
>> >  	If `--stdin` is also given, input paths are separated
>> >  	with a NUL character instead of a linefeed character.
>> >
>> > -\--::
>> > -	Interpret all preceding arguments as attributes and all following
>> > -	arguments as path names.
>> > -
>>
>> This also has a similar issue.  "--" here is not between revs and
>> pathspecs but is between attributes and pathspecs.
>
>   that can already be seen in the SYNOPSIS for that command, it does
> not require further explanation:
>
>   SYNOPSIS
>        git check-attr [-a | --all | attr...] [--] pathname...

Nah.  With the same logic you could say --all is already on synopsis
and no need for explanation.

If you are shooting for pedantic consistency, adding to pages that
are missing would be less problematic than removing from the ones
that have them, especially given that people thought the use of
double-dash in commands described on these pages are common or
special enough to deserve extra attention.

Re: [PATCH] doc: Remove explanation of "--" from several man pages

[Robert P. J. Day]

On Mon, 13 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> >> > diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
> >> > index aa3b2bf2f..0ae2523e0 100644
> >> > --- a/Documentation/git-check-attr.txt
> >> > +++ b/Documentation/git-check-attr.txt
> >> > @@ -36,10 +36,6 @@ OPTIONS
> >> >  	If `--stdin` is also given, input paths are separated
> >> >  	with a NUL character instead of a linefeed character.
> >> >
> >> > -\--::
> >> > -	Interpret all preceding arguments as attributes and all following
> >> > -	arguments as path names.
> >> > -
> >>
> >> This also has a similar issue.  "--" here is not between revs and
> >> pathspecs but is between attributes and pathspecs.
> >
> >   that can already be seen in the SYNOPSIS for that command, it does
> > not require further explanation:
> >
> >   SYNOPSIS
> >        git check-attr [-a | --all | attr...] [--] pathname...
>
> Nah.  With the same logic you could say --all is already on synopsis
> and no need for explanation.

  uh, that's not what i meant. what i *meant* was that the purpose of
"--" was already in the SYNOPSIS (as it appears to be in *all* man
pages) to visually show that it is a separator between the first part
of the command and possible pathnames. i was *not* suggesting that, if
something is in the SYNOPSIS, there is no further need to explain it.

  anyway, i can see this is a losing battle so i'll let it go.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================