[RFC/PATCH 5/4] Documentation: flesh out diff --no-index description
Explain what diff --no-index is used for in more detail.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Documentation/git-diff.txt | 21 +++++++++++++++++----
1 files changed, 17 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index dd1fb32..6700e8c 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -25,7 +25,7 @@ tree and the index file, or the index file and the working tree.
+
If exactly two paths are given and at least one points outside
the current repository, 'git diff' will compare the two files /
-directories. This behavior can be forced by --no-index.
+directories (see --no-index below).
'git diff' [--options] --cached [<commit>] [--] [<path>...]::
@@ -62,11 +62,24 @@ directories. This behavior can be forced by --no-index.
"git diff $(git-merge-base A B) B". You can omit any one
of <commit>, which has the same effect as using HEAD instead.
+'git diff' [--options] --no-index [--] <path> <path>::
+
+ In this form, 'git diff' will compare a pair of files or
+ directories that are not necessarily being managed by git.
+ The tracked content of files in the index and the object
+ database are ignored.
++
+In other words, this form allows 'git diff' to be used as a
+traditional 'diff' command (plus the familiar extras like --check,
+color, pagination, automatic use of -r, --stat/--name-status,
+--pickaxe, --binary, copy/rename detection, -Oorderfile, and
+--patience).
+
Just in case if you are doing something exotic, it should be
noted that all of the <commit> in the above description, except
-in the last two forms that use ".." notations, can be any
-<tree>. The third form ('git diff <commit> <commit>') can also
-be used to compare two <blob> objects.
+in the two forms that use ".." notations, can be any <tree>.
+The third form ('git diff <commit> <commit>') can also be used
+to compare two <blob> objects.
For a more complete list of ways to spell <commit>, see
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
--
1.7.2.3
Jonathan Nieder <jrnieder@gmail.com>