Documentation: diff -c/--cc

Signed-off-by: Junio C Hamano <junkio@cox.net>

3 files changed, 73 insertions, 3 deletions

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 0398b408c0..617d8f526f 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -146,3 +146,52 @@ the file that rename/copy produces, respectively.
 
 3.  TAB, LF, and backslash characters in pathnames are
     represented as `\t`, `\n`, and `\\`, respectively.
+
+
+combined diff format
+--------------------
+
+git-diff-tree and git-diff-files can take '-c' or '--cc' option
+to produce 'combined diff', which looks like this:
+
+------------
+diff --combined describe.c
+@@@ +98,7 @@@
+   return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +     unsigned char sha1[20];
+ +     struct commit *cmit;
+------------
+
+Unlike the traditional 'unified' diff format, which shows two
+files A and B with a single column that has `-` (minus --
+appears in A but removed in B), `+` (plus -- missing in A but
+added to B), or ` ` (space -- unchanged) prefix, this format
+compares two or more files file1, file2,... with one file X, and
+shows how X differs from each of fileN.  One column for each of
+fileN is prepended to the output line to note how X's line is
+different from it.
+
+A `-` character in the column N means that the line appears in
+fileN but it does not appear in the last file.  A `+` character
+in the column N means that the line appears in the last file,
+and fileN does not have that line.
+
+In the above example output, the function signature was changed
+from both files (hence two `-` removals from both file1 and
+file2, plus `++` to mean one line that was added does not appear
+in either file1 nor file2).  Also two other lines are the same
+from file1 but do not appear in file2 (hence prefixed with ` +`).
+
+When shown by `git diff-tree -c`, it compares the parents of a
+merge commit with the merge result (i.e. file1..fileN are the
+parents).  When shown by `git diff-files -c`, it compares the
+two unresolved merge parents with the working tree file
+(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
+"their version").
+
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index 67f51265e6..481b8b3aa0 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -8,7 +8,7 @@ git-diff-files - Compares files in the working tree and the index
 
 SYNOPSIS
 --------
-'git-diff-files' [-q] [<common diff options>] [<path>...]
+'git-diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...]
 
 DESCRIPTION
 -----------
@@ -30,6 +30,12 @@ The default is to diff against our branch (-2) and the
 cleanly resolved paths.  The option -0 can be given to
 omit diff output for unmerged entries and just show "Unmerged".
 
+-c,--cc::
+	This compares stage 2 (our branch), stage 3 (their
+	branch) and the working tree file and outputs a combined
+	diff, similar to the way 'diff-tree' shows a merge
+	commit with these flags.
+
 -q::
 	Remain silent even on nonexisting files
 
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 91fb130497..dd46d4f05d 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -9,8 +9,9 @@ git-diff-tree - Compares the content and mode of blobs found via two tree object
 SYNOPSIS
 --------
 [verse]
-'git-diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r]
-	      [--root] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]
+'git-diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
+	      [-t] [-r] [-c | --cc] [--root] [<common diff options>]
+	      <tree-ish> [<tree-ish>] [<path>...]
 
 DESCRIPTION
 -----------
@@ -80,6 +81,20 @@ separated with a single space are given.
 	git-diff-tree outputs a line with the commit ID when
 	applicable.  This flag suppressed the commit ID output.
 
+-c,--cc::
+	These flags change the way a merge commit is displayed
+	(which means it is useful only when the command is given
+	one <tree-ish>, or '--stdin').  It shows the differences
+	from each of the parents to the merge result
+	simultaneously, instead of showing pairwise diff between
+	a parent and the result one at a time, which '-m' option
+	output does.  '--cc' further compresses the output by
+	omiting hunks that show differences from only one
+	parent, or show the same change from all but one parent
+	for an Octopus merge.  When this optimization makes all
+	hunks disappear, the commit itself and the commit log
+	message is not shown, unless '-m' is specified.
+
 
 Limiting Output
 ---------------