Jeff King <peff@xxxxxxxx> writes:
> I would argue the opposite; if it is about a specific point, then put it
> with the point. Otherwise, you are asking the reader to remember back to
> an earlier point (that they may not even have read; in reference
> documentation, the point of a list is often to let readers skip from
> bullet to bullet easily).
You need to follow all the rules when composing your command line.
You cannot simply ignore ones that are inconvenient for you and pick
only the one you like.
The second and the third one are related in the "sides of the same
coin" sense; you either have "--" in which case no disambiguation
checks are done, or don't in which case your command line may get an
ambiguity error, so in that sense, you could say "I am writing '--',
so point C does not apply to me and I skip". But whether you do or
do not say '--', you have to have your revs before pathspecs, so you
cannot skip point A.
So I do not think a bullet list is designed to let the readers skip
and forget (or "may not even have read"). If that is the case,
perhaps we would need to use something else to give the set of rules
that apply to the command line here.
> I don't think that makes it any better. You went from:
>
> * A
> * B
> * C
> * D
>
> By the way, B and C imply BC.
>
> to:
> ...
> I think it would make more sense to do:
>
> * A
> * B
> * C
>
> By the way, B and C imply BC.
>
> Also, D.
I think the following is probably the best.
* A (revs and then paths)
* B (with "--", no dwim is done).
* C (without "--", disambiguation kicks in. By the way, this
means your script had better avoid this form; make sure you
use "--").
* D (pathspecs are patterns).
without the trailing paragraph, which is meant only for people who
write their script without using "--" by mistake, i.e. it only
belongs to point C.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html