Elijah Newren <newren@xxxxxxxxx> writes: > 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`. Yes, I need to re-consider this, as I already admitted in my reply to your previous catch of the related problem in the documentation. They all came from single point of misunderstanding. Will try to get it right in the next re-roll. Thanks, -- Sergey Organov
