Re: checkout extra files

Hi all,

consider this example:

$ mkdir gittest
$ cd gittest
$ git init
Initialized empty Git repository in d:/gittest/.git/
$ touch f1
$ git add f1
$ git commit commit -m "first commit"
[master (root-commit) e6f935e] first commit
 0 files changed
 create mode 100644 f1
$ touch f2
$ git checkout e6f9 -- *
error: pathspec 'f2' did not match any file(s) known to git.

Note the error. 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). I am not questioning this behavior, but the documentation, which does not describe it:

   "It updates the named paths in the working tree from the index file or
   from a named <tree-ish> ..."

There are two ways to read this sentence:

    1.  "named paths" referred to working tree, i.e. the files whose
names match the
          paths among all the ones present in the working tree
    2.  "named paths" referred to the index or tree-ish, i.e. the
files whose names match
          paths among oll the ones present in the index or tree-ish

In both cases, nothing tells the user that the matching of the paths is done over the union of the set of file names of the working tree + ndex or tree-ish. Indeed, the first time I have seen the error above I got quite confused because I thought that the checkout would restore the working directory as it was at the time I made the commit, without bothering about extra files that the directory contained at the moment (and note that f2 is not even a tracked one). This behavior is a bit strange, but if it is a hundred percent clearly documented I can live with it.

I think that knowing precisely what files are involved in this command is essential for the user.

-Angelo