Re: [PATCH] doc/for-each-ref: explicitly specify option names
- Date: Sat, 02 Sep 2017 11:03:19 +0900
- From: Junio C Hamano <gitster@xxxxxxxxx>
- Subject: Re: [PATCH] doc/for-each-ref: explicitly specify option names
Kevin Daudt <me@xxxxxxxxx> writes:
> For count, sort and format, only the argument names were listed under
> OPTIONS, not the option names.
> Add the option names to make it clear the options exist
> Signed-off-by: Kevin Daudt <me@xxxxxxxxx>
> Documentation/git-for-each-ref.txt | 18 +++++++++---------
> 1 file changed, 9 insertions(+), 9 deletions(-)
Sounds sensible. First I thought this was done deliberately because
these placeholder can apply to more than one option and we wanted to
explain each thing only once (e.g. "<object>" appears in 5 places,
and having to repeat something like "you can spell <object> by the
unique prefix of the object name, or the name of a ref that points
at it, or ..." in each option would be awkward), but that is not the
While we are at it, I just noticed that the SYNOPSIS section makes
it look as if <pattern>... must come before points-at, merged, and
their friends, but I do not think that should be the case. I also
notice that unlike --sort/--format/... the last four/five options
are spelled with "--option <value>" syntax; we should consistently
use "--option=<value>" instead there.
But these two are separate issues that can be fixed in a patch
separate from this one I am responding to.
p.s. I am still mostly offline and won't be doing any reviews or
queuing that requires me to look at anything beyond the patch
context. Please do not get disappointed if you do not see your
patch in my tree until later next week.