Thread (4 messages) flat view 4 messages, 2 authors, 2016-06-15
DORMANTno replies

[PATCH v6] diff format documentation: clarify --cc and -c

From: Adam Monsen <hidden>
Date: 2016-06-15 22:50:44
Subsystem: documentation, the rest · Maintainers: Jonathan Corbet, Linus Torvalds

The description was unclear if -c or --cc was the default (--cc is for
some commands), and incorrectly implied that the default applies to
all diff generating commands.

Most importantly, "log" does not default to "--cc" (it defaults to
"--no-merges") and "log -p" obeys the user's wish to see non-combined
format.  Only "diff" (during merge and three-blob comparison) and
"show" use --cc as the default.

The genesis of this patch was me getting frustrated trying to find
changes hidden in conflict resolutions of a merge commit. Jeff King
proposed a documentation fix. I made it into a patch, and worked on it
with Junio. See the thread "frustrated forensics: hard to find diff
that undid a fix" on the git mailing list:

  http://thread.gmane.org/gmane.comp.version-control.git/168481

For more historical information about viewing merge conflict
resolutions, see this post by Linus from 2008:

  http://article.gmane.org/gmane.comp.version-control.git/89415

Signed-off-by: Adam Monsen <redacted>
---

Please ignore v5. I forgot to include links to mailing list archives
in that version.

 Documentation/diff-generate-patch.txt |   11 +++++++----
 1 files changed, 7 insertions(+), 4 deletions(-)
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 3ac2bea..c57460c 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -74,10 +74,13 @@ 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
+produce a 'combined diff' when showing a merge. This is the default
+format when showing merges with linkgit:git-diff[1] or
+linkgit:git-show[1]. Note also that you can give the `-m' option to any
+of these commands to force generation of diffs with individual parents
+of a merge.
+
 A 'combined diff' format looks like this:
 
 ------------
-- 
1.7.2.3
Keyboard shortcuts
hback out one level
jnext message in thread
kprevious message in thread
ldrill in
Escclose help / fold thread tree
?toggle this help