From b5ffa9ec10a3b82a1530d6f7628bd3ef9e8dd037 Mon Sep 17 00:00:00 2001 From: Sergey Organov Date: Mon, 21 Dec 2020 18:19:56 +0300 Subject: doc/git-log: describe new --diff-merges options Describe all the new --diff-merges options in the git-log.txt and adopt description of originals accordingly. Signed-off-by: Sergey Organov Signed-off-by: Junio C Hamano --- Documentation/git-log.txt | 87 ++++++++++++++++++++++++++++------------------- 1 file changed, 52 insertions(+), 35 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 2b8ac5ff88..ff83dff14d 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -120,45 +120,62 @@ 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`). - --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. +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 `first-parent` is +the default format. + +--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc):: +--no-diff-merges:: + Specify diff format to be used for merge commits. Default is + `off` unless `--first-parent` is in use, in which case + `first-parent` is the default. ++ +--diff-merges=(off|none)::: +--no-diff-merges::: + Disable output of diffs for merge commits. Useful to override + implied value. ++ +--diff-merges=first-parent::: +--diff-merges=1::: + This option makes merge commits show the full diff with + respect to the first parent only. ++ +--diff-merges=separate::: +--diff-merges=m::: +-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. `-m` doesn't produce any output without `-p`. ++ +--diff-merges=combined::: +--diff-merges=c::: +-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. `-c` implies + `-p`. ++ +--diff-merges=dense-combined::: +--diff-merges=cc::: +--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. `--cc` implies `-p`. --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). - --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`. + 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[] -- cgit v1.2.3 From 8efd2efc32c41c7dcc2bf86a11fa89377f1c8d94 Mon Sep 17 00:00:00 2001 From: Sergey Organov Date: Mon, 21 Dec 2020 18:19:57 +0300 Subject: doc/diff-generate-patch: mention new --diff-merges option Mention --diff-merges instead of -m in a note to merge formats to aid discoverability, as -m is now described among --diff-merges options anyway. Signed-off-by: Sergey Organov Signed-off-by: Junio C Hamano --- Documentation/diff-generate-patch.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index b10ff4caa6..2db8eacc3e 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -81,9 +81,9 @@ Combined diff format Any diff-generating command can take the `-c` or `--cc` option to produce a 'combined diff' when showing a merge. This is the default format when showing merges with linkgit:git-diff[1] or -linkgit:git-show[1]. Note also that you can give the `-m` option to any -of these commands to force generation of diffs with individual parents -of a merge. +linkgit:git-show[1]. Note also that you can give suitable +`--diff-merges` option to any of these commands to force generation of +diffs in specific format. A "combined diff" format looks like this: -- cgit v1.2.3 From e58142add40e0db354eaed9554d1b0c871e23f7d Mon Sep 17 00:00:00 2001 From: Sergey Organov Date: Mon, 21 Dec 2020 18:19:58 +0300 Subject: doc/rev-list-options: document --first-parent changes merges format After introduction of the --diff-merges=first-parent, the --first-parent sets the default format for merges to the same value as this new option. Document this behavior and add corresponding reference to --diff-merges. Signed-off-by: Sergey Organov Signed-off-by: Junio C Hamano --- Documentation/rev-list-options.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 002379056a..96cc89d157 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -130,6 +130,11 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). this option allows you to ignore the individual commits brought in to your history by such a merge. +ifdef::git-log[] + This option also changes default diff format for merge commits + to `first-parent`, see `--diff-merges=first-parent` for details. +endif::git-log[] + --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. -- cgit v1.2.3 From 1d24509b7b865115836982267a5e54b2f7d77c42 Mon Sep 17 00:00:00 2001 From: Sergey Organov Date: Mon, 21 Dec 2020 18:19:59 +0300 Subject: doc/git-show: include --diff-merges description Move description of --diff-merges option from git-log.txt to diff-options.txt so that it is included in the git-show help. Signed-off-by: Sergey Organov Signed-off-by: Junio C Hamano --- Documentation/diff-options.txt | 51 ++++++++++++++++++++++++++++++++++++++++++ Documentation/git-log.txt | 51 +----------------------------------------- Documentation/git-show.txt | 7 ++++-- 3 files changed, 57 insertions(+), 52 deletions(-) (limited to 'Documentation') diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 573fb9bb71..c995e82584 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -33,6 +33,57 @@ endif::git-diff[] show the patch by default, or to cancel the effect of `--patch`. endif::git-format-patch[] +ifdef::git-log[] +--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc):: +--no-diff-merges:: + Specify diff format to be used for merge commits. Default is + {diff-merges-default} unless `--first-parent` is in use, in which case + `first-parent` is the default. ++ +--diff-merges=(off|none)::: +--no-diff-merges::: + Disable output of diffs for merge commits. Useful to override + implied value. ++ +--diff-merges=first-parent::: +--diff-merges=1::: + This option makes merge commits show the full diff with + respect to the first parent only. ++ +--diff-merges=separate::: +--diff-merges=m::: +-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. `-m` doesn't produce any output without `-p`. ++ +--diff-merges=combined::: +--diff-merges=c::: +-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. `-c` implies + `-p`. ++ +--diff-merges=dense-combined::: +--diff-merges=cc::: +--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. `--cc` implies `-p`. + +--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:: --unified=:: Generate diffs with lines of context instead of diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index ff83dff14d..727d20e1a2 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -127,57 +127,8 @@ selected, nor will they match search options like `-S`. The exception is when `--first-parent` is in use, in which case `first-parent` is the default format. ---diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc):: ---no-diff-merges:: - Specify diff format to be used for merge commits. Default is - `off` unless `--first-parent` is in use, in which case - `first-parent` is the default. -+ ---diff-merges=(off|none)::: ---no-diff-merges::: - Disable output of diffs for merge commits. Useful to override - implied value. -+ ---diff-merges=first-parent::: ---diff-merges=1::: - This option makes merge commits show the full diff with - respect to the first parent only. -+ ---diff-merges=separate::: ---diff-merges=m::: --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. `-m` doesn't produce any output without `-p`. -+ ---diff-merges=combined::: ---diff-merges=c::: --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. `-c` implies - `-p`. -+ ---diff-merges=dense-combined::: ---diff-merges=cc::: ---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. `--cc` implies `-p`. - ---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 +:diff-merges-default: `off` include::diff-options.txt[] include::diff-generate-patch.txt[] diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index fcf528c1b3..2b1bc7288d 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -45,10 +45,13 @@ include::pretty-options.txt[] include::pretty-formats.txt[] -COMMON DIFF OPTIONS -------------------- +DIFF FORMATTING +--------------- +The options below can be used to change the way `git show` generates +diff output. :git-log: 1 +:diff-merges-default: `dense-combined` include::diff-options.txt[] include::diff-generate-patch.txt[] -- cgit v1.2.3