From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 12 Sep 2012 21:22:08 +0000 (-0700)
Subject: Merge branch 'jc/maint-checkout-fileglob-doc'
X-Git-Tag: v1.8.0-rc0~66
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/9d0b9ed99f97a558f815a61fe6d35b4632a21cf5?ds=inline;hp=-c

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

Updated with help from Peff.

* jc/maint-checkout-fileglob-doc:
gitcli: contrast wildcard given to shell and to git
gitcli: formatting fix
Document file-glob for "git checkout -- '*.c'"
---

9d0b9ed99f97a558f815a61fe6d35b4632a21cf5
diff --combined Documentation/git-checkout.txt
index 11cc7f0588,5634efffa0..7958a47006
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@@ -84,11 -84,11 +84,11 @@@ entries; instead, unmerged entries are 
  	When checking out paths from the index, check out stage #2
  	('ours') or #3 ('theirs') for unmerged paths.
  
 --b::
 +-b <new_branch>::
  	Create a new branch named <new_branch> and start it at
  	<start_point>; see linkgit:git-branch[1] for details.
  
 --B::
 +-B <new_branch>::
  	Creates the branch <new_branch> and start it at <start_point>;
  	if it already exists, then reset it to <start_point>. This is
  	equivalent to running "git branch" with "-f"; see
@@@ -124,7 -124,7 +124,7 @@@ explicitly give a name with '-b' in suc
  	<commit> is not a branch name.  See the "DETACHED HEAD" section
  	below for details.
  
 ---orphan::
 +--orphan <new_branch>::
  	Create a new 'orphan' branch, named <new_branch>, started from
  	<start_point> and switch to it.  The first commit made on this
  	new branch will have no parents and it will be the root of a new
@@@ -367,6 -367,18 +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:
diff --combined Documentation/gitcli.txt
index 3e72a5d68e,00b8403225..f6ba90c2da
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@@ -37,11 -37,28 +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:
  
@@@ -62,14 -79,6 +79,14 @@@
     `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work
     if you happen to have a file called `HEAD` in the work tree.
  
 + * many commands allow a long option "--option" to be abbreviated
 +   only to their unique prefix (e.g. if there is no other option
 +   whose name begins with "opt", you may be able to spell "--opt" to
 +   invoke the "--option" flag), but you should fully spell them out
 +   when writing your scripts; later versions of Git may introduce a
 +   new option whose name shares the same prefix, e.g. "--optimize",
 +   to make a short prefix that used to be unique no longer unique.
 +
  
  ENHANCED OPTION PARSER
  ----------------------