Junio C Hamano <gitster@xxxxxxxxx> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html