Re: checkout extra files

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 10, 2012, 00:24 UTC
Message-ID: <7vwr02pvwh.fsf@alter.siamese.dyndns.org>
In-Reply-To: <7va9x0uyz9.fsf@alter.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> writes:

Show 21 quoted lines

> Angelo Borsotti <angelo.borsotti@gmail.com> writes:
>
>> It makes quite clear that the command accepts wildcards
>> (not expanded by the shell), which was is not clear in the current
>> man page (although one could imagine that <path> could also be a
>> wildcard).
>>
>> P.S. In the man page there is also a <pathspec>
>>
>>     "*git checkout* [-p|--patch] [<tree-ish>] [--] <pathspec>...
>>
>> that should perhaps be a <path>
>
> That's backwards.  Saying <path> as if it means a plain vanilla
> pathname is a cause of confusion.  The command takes pathspec, which
> is a pattern (see "git help glossary"). The places in the text that
> say <path> may need to be fixed.
>
> It just happens that you do not realize that you are using pathspec
> when you say "git checkout hello.c", as the pattern "hello.c" only
> matches the one pathname "hello.c".

I've read Documentation/git-checkout.txt and looked at the use of "paths".

the most of the "paths" (if not all) in the description are used as short-hand to mean "paths that the end user specified by giving a pathspec without repeating that expression over and over again. And it should be clear from the context, especially in places where we say things like "It updates the named paths", "update the index for the given paths", "checking out paths from the index", "when paths are given" etc.

As long as readers notice that the command takes <pathspec> on the command line, and understand <pathspec> has a specific meaning (i.e. it is a way to specify set of paths to be manipulated) and semantics, the existing text should be OK. The <paths> in synopsis section should be updated to <pathspec>, though.