[PATCH] Update diff documentation.

This updates diff documentation to discuss --find-copies-harder,
and adds descriptions for options that were not described
earlier.

Signed-off-by: Junio C Hamano <junkio@cox.net>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

6 files changed, 129 insertions, 14 deletions

diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt
index 45620f8fb..7627453d9 100644
--- a/Documentation/diffcore.txt
+++ b/Documentation/diffcore.txt
@@ -150,15 +150,13 @@ similarity score different from the default 50% by giving a
 number after "-M" or "-C" option (e.g. "-M8" to tell it to use
 8/10 = 80%).
 
-Note.  When the "-C" option is used, git-diff-cache and
-git-diff-file commands feed not just modified filepairs but
-unmodified ones to diffcore mechanism as well.  This lets the
-copy detector consider unmodified files as copy source
-candidates at the expense of making it slower.  Currently
-git-diff-tree does not feed unmodified filepairs even when the
-"-C" option is used, so it can detect copies only if the file
-that was copied happened to have been modified in the same
-changeset.
+Note.  When the "-C" option is used with --find-copies-harder
+option, git-diff-* commands feed unmodified filepairs to
+diffcore mechanism as well as modified ones.  This lets the copy
+detector consider unmodified files as copy source candidates at
+the expense of making it slower.  Without --find-copies-harder,
+git-diff-* commands can detect copies only if the file that was
+copied happened to have been modified in the same changeset.
 
 
 diffcore-merge-broken
diff --git a/Documentation/git-diff-cache.txt b/Documentation/git-diff-cache.txt
index 14041f3df..f6dd7037d 100644
--- a/Documentation/git-diff-cache.txt
+++ b/Documentation/git-diff-cache.txt
@@ -9,7 +9,7 @@ git-diff-cache - Compares content and mode of blobs between the cache and reposi
 
 SYNOPSIS
 --------
-'git-diff-cache' [-p] [-r] [-z] [-m] [-B] [-M] [-R] [-C] [-O<orderfile>] [-S<string>] [--pickaxe-all] [--cached] <tree-ish> [<path>...]
+'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O<orderfile>] [-S<string>] [--pickaxe-all] <tree-ish> [<path>...]
 
 DESCRIPTION
 -----------
@@ -44,6 +44,14 @@ OPTIONS
 -C::
 	Detect copies as well as renames.
 
+--find-copies-harder::
+	By default, -C option finds copies only if the original
+	file of the copy was modified in the same changeset for
+	performance reasons.  This flag makes the command
+	inspect unmodified files as candidates for the source of
+	copy.  This is a very expensive operation for large
+	projects, so use it with caution.
+
 -S<string>::
 	Look for differences that contains the change in <string>.
 
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index 58137b3b9..32e9a1e76 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the cache
 
 SYNOPSIS
 --------
-'git-diff-files' [-p] [-q] [-r] [-z] [-B] [-M] [-C] [-R] [-O<orderfile>] [-S<string>] [--pickaxe-all] [<pattern>...]
+'git-diff-files' [-p] [-q] [-r] [-z] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O<orderfile>] [-S<string>] [--pickaxe-all] [<path>...]
 
 DESCRIPTION
 -----------
@@ -39,6 +39,14 @@ OPTIONS
 -C::
 	Detect copies as well as renames.
 
+--find-copies-harder::
+	By default, -C option finds copies only if the original
+	file of the copy was modified in the same changeset for
+	performance reasons.  This flag makes the command
+	inspect unmodified files as candidates for the source of
+	copy.  This is a very expensive operation for large
+	projects, so use it with caution.
+
 -S<string>::
 	Look for differences that contains the change in <string>.
 
diff --git a/Documentation/git-diff-helper.txt b/Documentation/git-diff-helper.txt
index 29c5967d1..d826deb42 100644
--- a/Documentation/git-diff-helper.txt
+++ b/Documentation/git-diff-helper.txt
@@ -24,6 +24,11 @@ OPTIONS
 -S<string>::
 	Look for differences that contains the change in <string>.
 
+--pickaxe-all::
+	When -S finds a change, show all the changes in that
+	changeset, not just the files that contains the change
+	in <string>.
+
 -O<orderfile>::
 	Output the patch in the order specified in the
 	<orderfile>, which has one shell glob pattern per line.
diff --git a/Documentation/git-diff-stages.txt b/Documentation/git-diff-stages.txt
new file mode 100644
index 000000000..e7e59c849
--- /dev/null
+++ b/Documentation/git-diff-stages.txt
@@ -0,0 +1,83 @@
+git-diff-stages(1)
+==================
+v0.1, June 2005
+
+NAME
+----
+git-diff-stages - Compares content and mode of blobs between stages in an unmerged index file.
+
+
+SYNOPSIS
+--------
+'git-diff-stages' [-p] [-r] [-z] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O<orderfile>] [-S<string>] [--pickaxe-all] <stage1> <stage2> [<path>...]
+
+DESCRIPTION
+-----------
+Compares the content and mode of the blobs in two stages in an
+unmerged index file.
+
+OPTIONS
+-------
+<stage1>,<stage2>::
+	The stage number to be compared.
+
+-p::
+	Generate patch (see section on generating patches)
+
+-r::
+	This flag does not mean anything.  It is there only to match
+	"git-diff-tree".  Unlike "git-diff-tree", "git-diff-stages"
+	always looks at all the subdirectories.
+
+-z::
+	\0 line termination on output
+
+-B::
+	Break complete rewrite changes into pairs of delete and create.
+
+-M::
+	Detect renames.
+
+-C::
+	Detect copies as well as renames.
+
+--find-copies-harder::
+	By default, -C option finds copies only if the original
+	file of the copy was modified in the same changeset for
+	performance reasons.  This flag makes the command
+	inspect unmodified files as candidates for the source of
+	copy.  This is a very expensive operation for large
+	projects, so use it with caution.
+
+-S<string>::
+	Look for differences that contains the change in <string>.
+
+--pickaxe-all::
+	When -S finds a change, show all the changes in that
+	changeset, not just the files that contains the change
+	in <string>.
+
+-O<orderfile>::
+	Output the patch in the order specified in the
+	<orderfile>, which has one shell glob pattern per line.
+
+-R::
+	Swap two inputs; that is, show differences from <stage2> to
+	<stage1>.
+
+Output format
+-------------
+include::diff-format.txt[]
+
+
+Author
+------
+Written by Junio C Hamano <junkio@cox.net>
+
+Documentation
+--------------
+Documentation by Junio C Hamano.
+
+GIT
+---
+Part of the link:git.html[git] suite
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 762546bfe..ab0ba4fb1 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -9,7 +9,7 @@ git-diff-tree - Compares the content and mode of blobs found via two tree object
 
 SYNOPSIS
 --------
-'git-diff-tree' [-p] [-r] [-z] [--stdin] [-B] [-M] [-R] [-C] [-O<orderfile>] [-S<string>] [--pickaxe-all] [-m] [-s] [-v] [-t] <tree-ish> <tree-ish> [<pattern>]\*
+'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] [-t] [-R] [-B] [-M] [-C] [--find-copies-harder] [-O<orderfile>] [-S<string>] [--pickaxe-all] <tree-ish> <tree-ish> [<path>...]
 
 DESCRIPTION
 -----------
@@ -22,11 +22,11 @@ OPTIONS
 <tree-ish>::
 	The id of a tree object.
 
-<pattern>::
+<path>...::
 	If provided, the results are limited to a subset of files
 	matching one of these prefix strings.
 	ie file matches `/^<pattern1>|<pattern2>|.../`
-	Note that pattern does not provide any wildcard or regexp
+	Note that this parameter does not provide any wildcard or regexp
 	features.
 
 -p::
@@ -42,6 +42,14 @@ OPTIONS
 -C::
 	Detect copies as well as renames.
 
+--find-copies-harder::
+	By default, -C option finds copies only if the original
+	file of the copy was modified in the same changeset for
+	performance reasons.  This flag makes the command
+	inspect unmodified files as candidates for the source of
+	copy.  This is a very expensive operation for large
+	projects, so use it with caution.
+
 -R::
 	Swap two input trees.
 
@@ -96,6 +104,11 @@ separated with a single space are given.
 	This flag causes "git-diff-tree --stdin" to also show
 	the commit message before the differences.
 
+--pretty[=(raw|medium|short)]::
+	This is used to control "pretty printing" format of the
+	commit message.  Without "=<style>", it defaults to
+	medium.
+
 
 Limiting Output
 ---------------