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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 13, 2017, 04:15 UTC
Message-ID: <xmqq8tfaak6s.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <alpine.LFD.2.21.1711121600170.7904@localhost.localdomain>

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

Show 10 quoted lines

> 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.

Show 13 quoted lines

> 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.

Show 14 quoted lines

>  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.

Show 10 quoted lines

> 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).