No major changes, just some rewording and showing some variations of
general Git commands.
Signed-off-by: Robert P. J. Day <rpjday@xxxxxxxxxxxxxx>
---
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 9f13266a6..b7f40bf78 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -13,7 +13,7 @@ gitcli
DESCRIPTION
-----------
-This manual describes the convention used throughout Git CLI.
+This manual describes the conventions used throughout Git CLI.
Many commands take revisions (most often "commits", but sometimes
"tree-ish", depending on the context and command) and paths as their
@@ -32,32 +32,35 @@ arguments. Here are the rules:
between the HEAD commit and the work tree as a whole". You can say
`git diff HEAD --` to ask for the latter.
- * Without disambiguating `--`, Git makes a reasonable guess, but errors
- out and asking you to disambiguate when ambiguous. E.g. if you have a
- file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
+ * In cases where a Git command is truly ambiguous, Git will error out
+ and ask you to disambiguate the command. E.g. if you have a 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.
+a 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:
+ them from getting globbed by the shell. The following commands have
+ two different meanings:
+
--------------------------------
$ git checkout -- *.c
+
$ git checkout -- \*.c
+$ 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.
+The first command 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 three variations pass 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 first command, but with
+the latter three variations, you will.
* Just as the filesystem '.' (period) refers to the current directory,
using a '.' as a repository name in Git (a dot-repository) is a relative
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
