Subject: Re: checkout extra files

From: Junio C Hamano <[email-masked]>
Date: Tue, 04 Sep 2012 09:15:05 -0700

Junio C Hamano <[email-masked]> writes:

> Now we have f1 and f2 in the working tree.
>
>> $ git checkout e6f9 -- *
>
> That is the same as "git checkout e6f935e -- f1 f2", as the shell
> expanded "*" into "f1" and "f2".
>
>> error: pathspec 'f2' did not match any file(s) known to git.
>>
>> Note the error.
>
> Yes?
>
>> It is clear that the set of file names that git checkout is taking is
>> the union of the ones that
>> match the specified path ('*') in the work directory (gittest) with
>> the ones that match the
>> path in the specified commit (e6f9).
>
> The command tells git to check out "f1" and "f2" out of the tree of
> e6f935e, and git found "f1" but did not find "f2" and reported an
> error.  I do not see a room or need for "union" to come into the
> picture to explain what we see in the above transcript.

Actually, I "kind of sort of" can see where that "union" is coming
from, if I squint my eyes hard enough.

Yes, it makes it look like the path affected has some relationship
between two sets of paths:

 - set W, which consists of f1 and f2, that is the result of
   matching '*' against working tree files; and

 - set T, which consists of f1 (but not f2), that is the result of
   matching '*' against the tree contained in e6f935e

and the intersection of W and T (i.e. f1) is what is checked out.

But that is not what is happening at all.  What goes on is far
simpler than that.

 - the shell sees '*', matches it against working tree files, to
   obtain "f1" and "f2";

 - the shell tells "git" to "checkout e6f935e -- f1 f2";

 - "git" looks into the tree of e6f935e to find paths that match
   "f1" and "f2".

When "git" is run by the shell in the last step, it has _no_ clue
that the end user typed "*" from the shell.  It only sees "f1" and
"f2" on the command line.  There is no "set T" to be intersected
with "set W", so stop thinking in those terms, and you will be fine.

Now the question is, _you_ will be fine, but can the documentation 
be updated in such a way so that it will help _others_ to also stop
thinking about "intersection between set W and set T"?  I do not
have a good answer to that.