Re: [PATCH v4] Documentation fix: git log -p does not imply -c.

Adam Monsen [off-list ref] writes:

Relates to the thread with subject "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

I don't wish for anyone to repeat my bungled forensics episode.
Hopefully this will help others git along happily.

See also:

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

Signed-off-by: Adam Monsen <redacted>

Please don't do this.

Re-read what you wrote above while pretending that you do not have any
knowledge of the "frustrated forensics" you did.  Does it convey _any_
useful information?  Log messages should be sufficiently understandable
offline without having the web access.

Instead, summarize why the change is necessary.  IOW, don't be lazy now
while writing the log, to save time for people who later need to read log.

Something like

    Subject: diff format documentation: clarify --cc and -c

    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 the 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.

should be sufficient.

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 the 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.

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

Here's another try at "my" first git patch, a one-paragraph
documentation change. Now featuring a much-improved commit message by
Junio.

 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

Junio C Hamano wrote:

Log messages should be sufficiently understandable offline without 
having the web access.

Ok! Makes sense.

I read some stuff before writing it (like
Documentation/SubmittingPatches), but what I should have done is just
thumb through the log. Many commit messages are as you say they should be.

Something like ...<snipped>... should be sufficient.

Thanks, I'll use that. It includes history and code details I didn't know.

This is good advice about how to fit in to the git community... would
you like a "commit message guide"? I did something like this for another
community (Mifos), and they found it helpful. Here's a rough draft:

-----------8<-----------

Commit message guide
====================

The suggested *format* of a commit message is covered in DISCUSSION in
git-commit(1). This guide covers philosophy of commit messages.

- Read previous commit messages. Emulate the best ones.
- Reveal your intentions.
- Answer questions you anticipate others will ask.
- Imagine you are reading this same commit message 10 years from now.
  What would be most helpful for you to quickly recall why these
  changes were made?
- Imagine someone else is reading this same commit message 10 years
  from now. What would be most helpful for them to quickly understand
  what this commit changes and why it was done?
- Commit messages should be sufficiently understandable without access
  to any online content.
- Be verbose!
- This is your chance to use time- and context-sensitive information
  relevant to code changed.
- Refer to related content.
  - other commits
  - mailing list discussions (but not in lieu of a proper description)

----------->8-----------

If you want a guide like this, some questions:
* do you want asciidoc, something else, or don't care?
* name it Documentation/CommitMessageGuide ? or something else?

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