Re: [PATCH v1 24/27] doc/git-log: describe new --diff-merges options

[Elijah Newren <newren@gmail.com>]

On Thu, Dec 3, 2020 at 11:34 AM Sergey Organov <sorganov@gmail.com> wrote:
>
> Elijah Newren <newren@gmail.com> writes:
>
> > On Sun, Nov 8, 2020 at 1:46 PM Sergey Organov <sorganov@gmail.com> wrote:
> >>
> >> Describe all the new --diff-merges options in the git-log.txt
> >>
> >> Signed-off-by: Sergey Organov <sorganov@gmail.com>
> >> ---
> >>  Documentation/git-log.txt | 79 +++++++++++++++++++++++----------------
> >>  1 file changed, 46 insertions(+), 33 deletions(-)
> >>
> >> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> >> index 2b8ac5ff882a..de498a189646 100644
> >> --- a/Documentation/git-log.txt
> >> +++ b/Documentation/git-log.txt
> >> @@ -120,45 +120,58 @@ DIFF FORMATTING
> >>  By default, `git log` does not generate any diff output. The options
> >>  below can be used to show the changes made by each commit.
> >>
> >> -Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits
> >> -will never show a diff, even if a diff format like `--patch` is
> >> -selected, nor will they match search options like `-S`. The exception is
> >> -when `--first-parent` is in use, in which merges are treated like normal
> >> -single-parent commits (this can be overridden by providing a
> >> -combined-diff option or with `--no-diff-merges`).
> >> +Note that unless one of `--diff-merges` variants (including short
> >> +`-m`, `-c`, and `--cc` options) is explicitly given, merge commits
> >> +will not show a diff, even if a diff format like `--patch` is
> >> +selected, nor will they match search options like `-S`. The exception
> >> +is when `--first-parent` is in use, in which case
> >> +`--diff-merges=first-parent` is implied.
> >>
> >> --c::
> >> -       With this option, diff output for a merge commit
> >> -       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. Furthermore, it lists only files
> >> -       which were modified from all parents.
> >> -
> >> ---cc::
> >> -       This flag implies the `-c` option and further compresses the
> >> -       patch output by omitting uninteresting hunks whose contents in
> >> -       the parents have only two variants and the merge result picks
> >> -       one of them without modification.
> >> +--diff-merges=(off|none|first-parent|separate|combined|dense-combined)::
> >> +--no-diff-merges::
> >> +       Specify diff format to be used for merge commits. This has no
> >> +       effect unless diff output is enabled in the first place (e.g.,
> >> +       with `--patch` option.)
> >
> > This seems inconsistent with c7eaf8b4c3 ("log: when --cc is given,
> > default to -p unless told otherwise", 2015-08-20); shouldn't these
> > imply -p?
>
> Looks like it is indeed, and worse yet, the patch series don't handle
> this optimally due to my ignorance of this behavior. I think I need to
> make changes to imply -p whenever some of diff-merge options (except
> --diff-merges=none) are explicitly given, cause it's now, after these
> patches, is unclear why only combined diffs imply -p, and not, say,
> --diff-merges=first-parent.
>
> Nice catch, thanks!
>
> BTW, in the original, why only "git log" is affected? Ah, probably
> because "git show" has -p by default?
>
> While we are at it, why do we have "git show" at all? How is it
> essentially different from "git log -n1 --first-parent ..."? I mean,
> shouldn't it effectively be just an alias?

git show does not just operate on commits.  It can also display blobs,
trees, or tags.  I see people use it with blobs in the form of
REVISION:FILENAME references.  git show also is not limited to
displaying just one object, hence -n1 would be problematic; you'd need
to use --no-walk instead when operating on commits.  Also, git show
uses --cc when operating on commits, not --first-parent.

However, you are right that it is pretty close to just being something
you could alias if you limited it to commits.  If I understand
correctly, that alias would be `git log --no-walk -p --cc ...` (though
you only need the explicit -p with pretty old versions of git).

> >
> >> ++
> >> +--diff-merges=(off|none):::
> >> +--no-diff-merges:::
> >> +       (default) Disable output of diffs for merge commits. Useful to
> >> +       override implied value.
> >> ++
> >> +--diff-merges=first-parent:::
> >> +       This option makes merge commits show the full diff with
> >> +       respect to the first parent only, exactly like  regular
> >> +       commits.
> >
> > Not sure that "exactly like regular commits" is helpful here; I'd
> > personally rather cut those four words out.  I'm worried it'll be
> > taken not as an implementation explanation, but as a "this treats
> > merge commits in the natural way that regular commits are" which users
> > may mistakenly translate to "it shows what changes the user manually
> > made as part of the commit" which is not at all the correct mapping.
>
> Dunno. Don't have strict preference here. Git has no idea how the
> changes in a commit have been made in the first place. Changes are just
> changes.

If you don't have a preference, can we drop those four words?  ;-)

> To my excuse, I took this from git:5fbb4bc191 that has:
>
> +Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits
> +will never show a diff, even if a diff format like `--patch` is
> +selected, nor will they match search options like `-S`. The exception is
> +when `--first-parent` is in use, in which merges are treated like normal
> +single-parent commits (this can be overridden by providing a
> +combined-diff option or with `--no-diff-merges`).

Yeah, I can see where you're coming from, though the context change
feels like just enough different that the four words you added bother
me a bit more.  However, this existing wording does bother me now that
you highlight it.  Even though it's not something introduced by your
patch, I'd really like to drop "normal" here; I think it is prone to
cause confusion to users and as far as I can tell provides no useful
meaning for the sentence.  (There are multiple types of single-parent
commits?  What is an "unnormal" one?  How do I tell which kind I want?
 etc...).