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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 22, 2017, 02:24 UTC
Message-ID: <xmqq1skrxd83.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20171121212305.GA16418@alpha.vpn.ikke.info>

Kevin Daudt <me@ikke.info> writes:

Show 8 quoted lines

> Although I agree that common options don't need to be explained
> everytime again, this change might make '--' even more obscure. To be
> honest, I didn't even know about gitcli(7), let alone most new users.
>
> In the #git irc channel we often have to explain what '--' means and
> why it's sometimes necessary.
>
> I don't however know a better solution to it more clear.

I do not agree with the starting thought of this patch in the first place. With the same logic, "git help" showing the most commonly used subcommands, as "git help -a" has all the information, is redundant and unwanted. So is the synopsis section and "git $cmd -h" that shows only commonly used options but not necessarily all of them.

There may be some git-$foo manual page that do not describe how '--' would be useful for the specific $foo subcommand that would become more helpful to new readers if they did, and I think updating them would be a better approach if we wanted to have consistency across manual pages.