Merge branch 'jc/maint-checkout-fileglob-doc' into maint-1.7.11

* jc/maint-checkout-fileglob-doc:
  gitcli: contrast wildcard given to shell and to git
  gitcli: formatting fix
  Document file-glob for "git checkout -- '*.c'"
This commit is contained in:
Junio C Hamano 2012-09-14 20:45:03 -07:00
commit 6711759617
2 changed files with 30 additions and 1 deletions

View File

@ -367,6 +367,18 @@ $ git checkout hello.c <3>
<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`. The file `hello.c` will also be
checked out, even though it is no longer in the working tree,
because the file globbing is used to match entries in the index
(not in the working tree by the 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:

View File

@ -37,11 +37,28 @@ arguments. Here are the rules:
file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
you have to say either `git diff HEAD --` or `git diff -- HEAD` to
disambiguate.
+
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.
* Many commands allow wildcards in paths, but you need to protect
them from getting globbed by the shell. These two mean different
things:
+
--------------------------------
$ git checkout -- *.c
$ git checkout -- \*.c
--------------------------------
+
The former lets your shell expand the fileglob, and you are asking
the dot-C files in your working tree to be overwritten with the version
in the index. The latter passes the `*.c` to Git, and you are asking
the paths in the index that match the pattern to be checked out to your
working tree. After running `git add hello.c; rm hello.c`, you will _not_
see `hello.c` in your working tree with the former, but with the latter
you will.
Here are the rules regarding the "flags" that you should follow when you are
scripting git: