Hi,
On Sun, Nov 8, 2020 at 1:44 PM Sergey Organov <sorganov@xxxxxxxxx> wrote:
>
> Move description of --diff-merges option from git-log.txt to
> diff-options.txt so that it is included in the git-show help.
>
> While we are at it, make git-show closer to git-log in this area by
> providing similar wording in the introduction of diff options.
>
> Signed-off-by: Sergey Organov <sorganov@xxxxxxxxx>
> ---
> Documentation/diff-options.txt | 54 ++++++++++++++++++++++++++++++++++
> Documentation/git-log.txt | 52 --------------------------------
> Documentation/git-show.txt | 8 +++--
> 3 files changed, 60 insertions(+), 54 deletions(-)
>
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index 573fb9bb71e2..f1629887103e 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -33,6 +33,60 @@ endif::git-diff[]
> show the patch by default, or to cancel the effect of `--patch`.
> endif::git-format-patch[]
>
> +ifdef::git-log[]
> +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.
So, now diff-options says that no diffs are the defaults for merge commits...
> +
> +--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.)
> ++
> +--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.
> ++
> +--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 `--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).
> +endif::git-log[]
> +
> -U<n>::
> --unified=<n>::
> Generate diffs with <n> lines of context instead of
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index de498a189646..0cacc780bf30 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -120,58 +120,6 @@ 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 `--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.
> -
> ---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.)
> -+
> ---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.
> -+
> ---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 `--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).
> -
>
> :git-log: 1
> include::diff-options.txt[]
> diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
> index fcf528c1b30d..abe58ce5d3a8 100644
> --- a/Documentation/git-show.txt
> +++ b/Documentation/git-show.txt
> @@ -45,8 +45,12 @@ include::pretty-options.txt[]
> include::pretty-formats.txt[]
>
>
> -COMMON DIFF OPTIONS
> --------------------
> +DIFF FORMATTING
> +---------------
> +
> +By default, `git show` does not generate any diff output. The options
> +below can be used to show the changes made by each commit.
> +
This is not right, `git show` generates diff output by default for
both normal commits and merge commits -- it defaults to -p --cc (see
show_setup_revisions_tweak() of builtin/log.c). Also see earlier in
git-show.txt where it says
For commits it shows the log message and textual diff. It also presents
the merge commit in a special format as produced by git diff-tree --cc.
> :git-log: 1
> include::diff-options.txt[]
...and the included text will contain the repeated claim that no diffs
are shown by default for merge commits, which is true for `git log`
but not `git show`.
