Re: checkout extra files

Nguyen Thai Ngoc Duy [off-list ref] writes:

quoted

For this particular scenario, I do not see anything offhand that is
unclear about the behaviour of Git in the documentation, even though
as you pointed out, if the user is unaware that the shell passes
globs unmodified when they do not match, it may lead to a confusion
like this.  I certainly do not want to do a full "introduction to
shell" in our documentation, but if adding a short sentence or two
helps to avoid confusion like this, I do not strongly object to it.

Perhaps like this?

 Documentation/git-checkout.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git i/Documentation/git-checkout.txt w/Documentation/git-checkout.txt
index 63a2516..e7272b6 100644
--- i/Documentation/git-checkout.txt
+++ w/Documentation/git-checkout.txt

@@ -360,20 +360,32 @@ mistake, and gets it back from the index.
 $ git checkout master             <1>
 $ git checkout master~2 Makefile  <2>
 $ rm -f hello.c
 $ git checkout hello.c            <3>
 ------------
 +
 <1> switch branch
 <2> take a file out of another commit
 <3> restore hello.c from the index
 +
+If you want to check out _all_ C source files out of the index,
+you can say
++
+------------
+$ git checkout -- '*.c'
+------------
++
+Note the quotes around '*.c'.  'hello.c' will also be checked
+out, even though it is no longer in the working tree, because
+the pathspec is used to match entries in the index (not in the
+working tree by your shell).
++
 If you have an unfortunate branch that is named `hello.c`, this
 step would be confused as an instruction to switch to that branch.
 You should instead write:
 +
 ------------
 $ git checkout -- hello.c
 ------------
 
 . After working in the wrong branch, switching to the correct
 branch would be done using:

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

On Tue, Sep 4, 2012 at 9:55 AM, Junio C Hamano [off-list ref] wrote:

Perhaps like this?

Looks good. I was going to complain that this patch applied to
git-checkout.txt only but I just saw git-add.txt also mentions about
quoting wildcards. So I'm good.

-- 
Duy