On Sun, Nov 8, 2020 at 1:46 PM Sergey Organov <sorganov@xxxxxxxxx> wrote:
>
> Describe all the new --diff-merges options in the git-log.txt
>
> Signed-off-by: Sergey Organov <sorganov@xxxxxxxxx>
> ---
> 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?
> ++
> +--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.
> ++
> +--diff-merges=separate:::
> +-m:::
> + This makes merge commits show the full diff with respect to
> + each of the parents. Separate log entry and diff is generated
> + for each parent.
> ++
> +--diff-merges=combined:::
> +-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.
> ++
> +--diff-merges=dense-combined:::
> +--cc:::
> + With this option the output produced by
> + `--diff-merges=combined` is further compressed by omitting
> + uninteresting hunks whose contents in the parents have only
> + two variants and the merge result picks one of them without
> + modification.
>
> --combined-all-paths::
> This flag causes combined diffs (used for merge commits) to
> list the name of the file from all parents. It thus only has
> - effect when -c or --cc are specified, and is likely only
> - useful if filename changes are detected (i.e. when either
> - rename or copy detection have been requested).
> + effect when `--diff-merges=[dense-]combined` is in use, and
> + is likely only useful if filename changes are detected (i.e.
> + when either rename or copy detection have been requested).
>
> --m::
> - This flag makes the merge commits show the full diff like
> - regular commits; for each merge parent, a separate log entry
> - and diff is generated. An exception is that only diff against
> - the first parent is shown when `--first-parent` option is given;
> - in that case, the output represents the changes the merge
> - brought _into_ the then-current branch.
> -
> ---diff-merges=off::
> ---no-diff-merges::
> - Disable output of diffs for merge commits (default). Useful to
> - override `-m`, `-c`, or `--cc`.
>
> :git-log: 1
> include::diff-options.txt[]
> --
> 2.25.1
