DESCRIPTION
-----------
-This manual describes best practice in how to use git CLI. Here are
-the rules that you should follow when you are scripting git:
+This manual describes the convention 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
+arguments. Here are the rules:
+
+ * Revisions come first and then paths.
+ E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
+ `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`
+ 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
+ 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.
+
+ * 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
+ 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.
+
+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.
-ENHANCED CLI
-------------
+ENHANCED OPTION PARSER
+----------------------
From the git 1.5.4 series and further, many git commands (not all of them at the
time of the writing though) come with an enhanced option parser.
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
----------------------------
+NOTES ON FREQUENTLY CONFUSED OPTIONS
+------------------------------------
+
+Many commands that can work on files in the working tree
+and/or in the index can take `--cached` and/or `--index`
+options. Sometimes people incorrectly think that, because
+the index was originally called cache, these two are
+synonyms. They are *not* -- these two options mean very
+different things.
+
+ * The `--cached` option is used to ask a command that
+ usually works on files in the working tree to *only* work
+ with the index. For example, `git grep`, when used
+ without a commit to specify from which commit to look for
+ strings in, usually works on files in the working tree,
+ but with the `--cached` option, it looks for strings in
+ the index.
+
+ * The `--index` option is used to ask a command that
+ usually works on files in the working tree to *also*
+ affect the index. For example, `git stash apply` usually
+ merges changes recorded in a stash to the working tree,
+ but with the `--index` option, it also merges changes to
+ the index as well.
+
+`git apply` command can be used with `--cached` and
+`--index` (but not at the same time). Usually the command
+only affects the files in the working tree, but with
+`--index`, it patches both the files and their index
+entries, and with `--cached`, it modifies only the index
+entries.
+
+See also http://marc.info/?l=git&m=116563135620359 and
+http://marc.info/?l=git&m=119150393620273 for further
+information.
+
Documentation
-------------
-Documentation by Pierre Habouzit.
+Documentation by Pierre Habouzit and the git-list <git@vger.kernel.org>.
GIT
---