[PATCH 2/2] gitcli: contrast wildcard given to shell and to git

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 10, 2012, 19:54 UTC
Message-ID: <1347306840-14007-2-git-send-email-gitster@pobox.com>
In-Reply-To: <1347306840-14007-1-git-send-email-gitster@pobox.com>

People who are not used to working with shell may intellectually understand how the command line argument is massaged by the shell but still have a hard time visualizing the difference between letting the shell expand fileglobs and having Git see the fileglob to use as a pathspec.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/gitcli.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index c4edf04..00b8403 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -42,6 +42,23 @@ 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:

-- 
1.7.12.322.g2c7d289