[RFC/PATCH 5/4] Documentation: flesh out diff --no-index description

[Jonathan Nieder <jrnieder@gmail.com>]

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