Re: [PATCH 1/2] documentation fix: git log -p does not imply -c.

[Jeff King <peff@peff.net>]

On Mon, Mar 07, 2011 at 10:37:21AM -0800, Junio C Hamano wrote:

> > Hmm. "git show" seems to show --cc, but "git log -p" does not show
> > anything.
> 
> The intention has always been to default to --cc since 0fe7c1d (built-in
> diff: assorted updates., 2006-04-29) for "diff" if I am not misremembering
> things, but you are right---"log" is a tad different.
> 
> The code does not want to use --cc by default for "log", and I don't think
> that should change.  See 1aec791 (git log: don't do merge diffs by
> default, 2006-04-19).

Thanks for the history. I think the doc problem was an inaccuracy that
snuck in during 272bd3c (Include diff options in the git-log manpage,
2007-11-01). Nearly identical text (without the inaccuracy) is in the
"Diff Format For Merges" section in diff-format.txt.

Furthermore, the copied text talks about diff-index and diff-tree, but
gets included inline in git-log(1) (although the part in diff-format.txt
does not get included in git-log's manpage)[1]. So probably it's
reasonable to clean it up to something like:

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 3ac2bea..3d02da9 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -74,10 +74,12 @@ separate lines indicate the old and the new mode.
 combined diff format
 --------------------
 
-"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or
-'--cc' option to produce 'combined diff'.  For showing a merge commit
-with "git log -p", this is the default format; you can force showing
-full diff with the '-m' option.
+Any diff-generating command can take the `-c` or `--cc` option to
+produced a 'combined diff' when showing a merge. This is the default
+format when showing merge conflicts with linkgit:git-diff[1] or a merge
+commit with linkgit:git-show[1]. Note also that you can vie the full
+diff with the `-m` option.
+
 A 'combined diff' format looks like this:
 
 ------------

-- >8 --

Is there any way to get "git diff" to show combined-form besides an
index with conflicts? I couldn't convince it to show me a merge commit
beside its parents, since it doesn't have an equivalent to diff-tree's
--stdin option.

-Peff

[1] Reading over this, the whole section could use some editing. I think
this is another example that needs to be broken out into its own
user-visible manpage. That is, we have too much "if you use the -p
option to command X, or command Y by default, or command Z without
--raw, then you see this format". That's pretty dense. Instead command X
should have:

  -p::
  --stat::
  --summary::
  [etc]
    Generate diffs in this format. See "git help diff-formats" for
    details. The default format is "-p".

and then diff-format.txt should _just_ be a description of the diff
formats, without worrying about commands at all. And probably the text
above should be factored out as part of diff-options.txt. But that's all
part of a much bigger documentation architecture change that I am hoping
to get to eventually. For now, I think it's worth just tweaking this
text to stop being inaccurate.