Re: [PATCH 2/3] revision: add "--ignore-merges" option to counteract "-m"

[Chris Torek <chris.torek@gmail.com>]

First, not that anyone should particularly care: I heartily
approve. :-)

On Tue, Jul 28, 2020 at 9:40 AM Jeff King <peff@peff.net> wrote:
> I pulled the option name from the rev_info field name. It might be too
> broad (we are not ignoring merges during the traversal, only for the
> diff). It could be "--no-diff-merges" or something, but that would
> involve flipping the sense of the boolean (but that would just be in the
> code, not user-visible, so not that big a deal).

Perhaps a bit bikesheddy, but I would suggest some clarifying
notes in the documentation.  The fact that `git log` *follows*
merges by default is pretty obvious, but the fact that it doesn't
*diff them at all* by default appears to be surprising to most Git
newcomers.  (It was to me, so many years ago, and I see this all
the time on stackoverflow.)

  Note that --ignore-merges / --no-ignore-merges affect
  only diff generation, not commit traversal.  Note
  also that by default, "git log -p" does not generate
  diffs for merges except when using --first-parent.
  See also the -c and --cc options and note that the
  default for "git show" is "--cc".

(The "except when using --first-parent" is of course new here.)

This probably needs a bit of tweaking, but the big idea is
to communicate and emphasize three things:

 1. "git log -p" and "git show" behave differently by default.
    It's a surprise, so we should call it out separately.

 2. The default for "git log -p" is no diff at all for merge
    commits, so see -c / --cc when you're looking at -m.

 3. The default for "git show" is "--cc".  (This note doesn't
    really belong here; perhaps it should be separately
    listed under the -c and --cc options?)

Chris