Re: cherry-pick applies some other changes than the specified one?

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

>> Thanks, didn't know about that (and it's not documented in diff man page).
>
> These "compare a particular stage against working tree file" modes
> only make sense when you are comparing the index and the working tree, so
> the description is in "git diff-files" manpage but hasn't been ported to
> the documentation of generic "git diff" frontend.
>
> Perhaps we should.

And here is a quick attempt to do so.

This just leaves the details of what -c/--cc are about to the combined
diff format section in diff-generate-patch.txt, which I updated in the
separate patch.

 Documentation/diff-options.txt   |   31 +++++++++++++++++++++++++++++++
 Documentation/git-diff-files.txt |   19 -------------------
 Documentation/git-diff-tree.txt  |   20 --------------------
 3 files changed, 31 insertions(+), 39 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index c93124b..19ce302 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -24,6 +24,37 @@ ifndef::git-format-patch[]
 --patch::
 	Generate patch (see section on generating patches).
 	{git-diff? This is the default.}
+
+-1 --base::
+-2 --ours::
+-3 --theirs::
+-0::
+	These make sense only when comparing the index and the working
+	tree (i.e. `git diff-files` or `git diff <path>...`) and compares
+	against the "base" version, "our branch" or "their
+	branch" respectively.  With these options, diffs for
+	merged entries are not shown.
++
+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::
+	Produce "combined diff" (and "dense combined diff" showing how the
+	result is different compared to more than one original.
++
+When used in showing a merge commit (i.e. `git show <merge>`, 
+`git diff-tree <merge>` or when feeding a merge commit
+to `git diff-tree --stdin`), compare the parent commits of the
+merge with the merge commit.
++
+When used in comparison between the index and the working tree
+(i.e. `git diff` during a conflicted merge or rebase),
+compare stage 2 (our branch), stage 3 (their
+branch) and the working tree file and outputs a combined
+diff.
+
 endif::git-format-patch[]
 
 -U<n>::
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt
index 8d48194..82d2e2e 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.txt
@@ -21,25 +21,6 @@ OPTIONS
 -------
 include::diff-options.txt[]
 
--1 --base::
--2 --ours::
--3 --theirs::
--0::
-	Diff against the "base" version, "our branch" or "their
-	branch" respectively.  With these options, diffs for
-	merged entries are not shown.
-+
-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 nonexistent files
 
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 4e5f127..ebcfcfb 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -88,26 +88,6 @@ include::pretty-options.txt[]
 	'git diff-tree' outputs a line with the commit ID when
 	applicable.  This flag suppressed the commit ID output.
 
--c::
-	This flag changes 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 is what the '-m' option does).
-	Furthermore, it lists only files which were modified
-	from all parents.
-
---cc::
-	This flag changes the way a merge commit patch is displayed,
-	in a similar way to the '-c' option. It implies the '-c'
-	and '-p' options and further compresses the patch output
-	by omitting uninteresting hunks whose the contents in the parents
-	have only two variants and the merge result picks one of them
-	without modification.  When all hunks are uninteresting, the commit
-	itself and the commit log message is not shown, just like in any other
-	"empty diff" case.
-
 --always::
 	Show the commit itself and the commit log message even
 	if the diff itself is empty.