Re: checkout extra files

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 10, 2012, 19:35 UTC
Message-ID: <7vhar5oemu.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20120910171954.GA15583@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 5 quoted lines

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

Show 20 quoted lines

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