are paths.
* When an argument can be misunderstood as either a revision or a path,
- they can be disambiguated by placing `\--` between them.
- E.g. `git diff \-- HEAD` is, "I have a file called HEAD in my work
+ they can be disambiguated by placing `--` between them.
+ E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work
tree. Please show changes between the version I staged in the index
and what I have in the work tree for that file". not "show difference
between the HEAD commit and the work tree as a whole". You can say
- `git diff HEAD \--` to ask for the latter.
+ `git diff HEAD --` to ask for the latter.
- * Without disambiguating `\--`, git makes a reasonable guess, but errors
+ * 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
- you have to say either `git diff HEAD \--` or `git diff \-- HEAD` to
+ 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.
+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:
* it's preferred to use the non dashed form of git commands, which means that
- you should prefer `"git foo"` to `"git-foo"`.
+ you should prefer `git foo` to `git-foo`.
- * splitting short options to separate words (prefer `"git foo -a -b"`
- to `"git foo -ab"`, the latter may not even work).
+ * splitting short options to separate words (prefer `git foo -a -b`
+ to `git foo -ab`, the latter may not even work).
* when a command line option takes an argument, use the 'sticked' form. In
- other words, write `"git foo -oArg"` instead of `"git foo -o Arg"` for short
- options, and `"git foo --long-opt=Arg"` instead of `"git foo --long-opt Arg"`
+ other words, write `git foo -oArg` instead of `git foo -o Arg` for short
+ options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg`
for long options. An option that takes optional option-argument must be
written in the 'sticked' form.
* when you give a revision parameter to a command, make sure the parameter is
not ambiguous with a name of a file in the work tree. E.g. do not write
- `"git log -1 HEAD"` but write `"git log -1 HEAD --"`; the former will not work
+ `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
----------------------
+
---------------------------------------------
$ git describe -h
-usage: git-describe [options] <committish>*
+usage: git describe [options] <committish>*
--contains find the tag that comes after the commit
--debug debug search strategy on stderr
Negating options
~~~~~~~~~~~~~~~~
-Options with long option names can be negated by prefixing `"--no-"`. For
-example, `"git branch"` has the option `"--track"` which is 'on' by default. You
-can use `"--no-track"` to override that behaviour. The same goes for `"--color"`
-and `"--no-color"`.
+Options with long option names can be negated by prefixing `--no-`. For
+example, `git branch` has the option `--track` which is 'on' by default. You
+can use `--no-track` to override that behaviour. The same goes for `--color`
+and `--no-color`.
Aggregating short options
~~~~~~~~~~~~~~~~~~~~~~~~~
Commands that support the enhanced option parser allow you to aggregate short
-options. This means that you can for example use `"git rm -rf"` or
-`"git clean -fdx"`.
+options. This means that you can for example use `git rm -rf` or
+`git clean -fdx`.
Separating argument from the option
http://marc.info/?l=git&m=119150393620273 for further
information.
-Documentation
--------------
-Documentation by Pierre Habouzit and the git-list <git@vger.kernel.org>.
-
GIT
---
Part of the linkgit:git[1] suite