[PATCH] Cleanup git-diff documentation

There were a couple inconsistencies in the formatting of the command
descriptions and a more descriptive initial description is better.

Signed-off-by: Brian Gernhardt <redacted>
---

I agree with Johannes about the original being clearer.  Plus two of
the command examples were missing brackets around -- and one had a
* at the beginning the others didn't.  This patch is against Junio's
changes made on master (1d770), even though his patch didn't apply
cleanly.

Documentation/git-diff.txt |   11 +++++++----
1 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 534f824..2ba9145 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt

@@ -12,7 +12,10 @@ SYNOPSIS

DESCRIPTION
-----------
-This command shows changes between four combinations of states.
+Show changes between two trees, a tree and the working tree, a
+tree and the index file, or the index file and the working tree.
+The combination of what is compared with what is determined by
+the number of trees given to the command.
'git-diff' [--options] [--] [<path>...]::

@@ -25,11 +28,11 @@ This command shows changes between four  

combinations of states.
'git-diff' [--options] --cached [<commit>] [--] [<path>...]::
	This form is to view the changes you staged for the next
-	commit relative to the named <tree-ish>.  Typically you
+	commit relative to the named <commit>.  Typically you
	would want comparison with the latest commit, so if you
	do not give <commit>, it defaults to HEAD.
-'git-diff' [--options] <commit> -- [<path>...]::
+'git-diff' [--options] <commit> [--] [<path>...]::
	This form is to view the changes you have in your
	working tree relative to the named <commit>.  You can

@@ -37,7 +40,7 @@ This command shows changes between four  

combinations of states.
	branch name to compare with the tip of a different
	branch.
-* 'git-diff' [--options] <commit> <commit> -- [<path>...]
+'git-diff' [--options] <commit> <commit> [--] [<path>...]
	This form is to view the changes between two <commit>,
	for example, tips of two branches.
--