Re: checkout extra files

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 10, 2012, 17:09 UTC
Message-ID: <7vpq5told4.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20120910161904.GC9435@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 9 quoted lines

>>  When writing a script that is expected to handle random user-input, it is
>>  a good practice to make it explicit which arguments are which by placing
>>  disambiguating `--` at appropriate places.
>
> Look at the paragraph below your addition. It is typographically outside
> of the bulleted list you are adding to, but it really makes sense
> directly after the prior two bullet points, which are explicitly about
> disambiguation between revisions and paths. Your addition splits them
> apart.

Yes, I noticed it and thought about different possibilities, including making the description of glob the first bullet point.

> Does it make sense to join that final paragraph into what is now the
> third bullet, and then add your new text (the fourth bullet) after?

I am not sure. After re-reading it, I do not think the fileglob discussion belongs to the existing "Here are the rules" list in the first place. It should probably be the extended description for the first point (revisions then paths) to explain what kind of "paths" we accept there.

I generally consider follow-up paragraphs after bulleted list to be enhancements on any of the points in the list, not necessarily applying to all of them. The existing structure is:

    * point A (revisions and paths)
    * point B (-- can be used to disambiguate)
    * point C (ambiguation leads to an error)

    Note that point B and point C taken together imply corollary BC.

So something like this would be the right thing to do:

    * point A
    * point B
    * point C

    Note that point B and point C taken together imply corollary BC.
    Also note that point A implies corollary AA.

or even

    * point A
    * point B
    * point C

    Note that point A implies corollary AA.  Also note that point B
    and point C taken together imply corollary BC.

So perhaps something like this squashed in on top of the patch in question?

 Documentation/gitcli.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
index c70cd81..4413489 100644
--- c/Documentation/gitcli.txt
+++ w/Documentation/gitcli.txt
@@ -38,9 +38,9 @@ arguments.  Here are the rules:
    you have to say either `git diff HEAD --` or `git diff -- HEAD` to
    disambiguate.
 
- * Many commands allow wildcards in paths, but you need to protect
-   them from getting globbed by the shell.  These two mean different
-   things:
+Many commands allow wildcards in paths (see pathspec in
+linkgit:gitglossary[7]), but you need to protect them
+from getting globbed by the shell.  These two mean different things:
 +
 --------------------------------
 $ git checkout -- *.c