From: Junio C Hamano Date: Wed, 22 Nov 2017 02:24:12 GMT Subject: Re: [PATCH] doc: remove explanation of "--" from man pages Message-ID: In-Reply-To: <20171121212305.GA16418@alpha.vpn.ikke.info> Kevin Daudt writes: > 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.