{"thread":{"id":"60213","subject":"[PATCH 0/2] diff-merges: introduce '-d' option","startedAt":"2023-09-09T12:55:06Z","lastAt":"2023-10-10T14:58:33Z","messageCount":55,"participants":["Sergey Organov","Junio C Hamano","Eric Sunshine","Elijah Newren","Emily Shaffer"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"481623","messageId":"20230909125446.142715-1-sorganov@gmail.com","threadId":"60213","inReplyTo":null,"subject":"[PATCH 0/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-09T12:54:44Z","receivedAt":"2023-09-09T12:55:06Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This new convenience option requests full diff with respect to first\nparent, so that\n\n git log -d\n\nwill output diff with respect to first parent for every commit,\nuniversally, no matter how many parents the commit turns out to have.\n\nIt's implemented as pure synonym for\n\n --diff-merges=first-parent --patch\n\nThe first commit in the series tweaks diff-merges documentation a bit,\nand is valuable by itself. It's put here as '-d' implementation commit\ndepends on it in its documentation part.\n\nNote: the need for this new convenience option mostly emerged from\ndenial by the community of patches that modify '-m' behavior to imply\n'-p' as the rest of similar options (such as --cc) do.\n\nSergey Organov (2):\n diff-merges: improve --diff-merges documentation\n diff-merges: introduce '-d' option\n\n Documentation/diff-options.txt | 101 +++++++++++++++++++--------------\n Documentation/git-log.txt | 4 +-\n diff-merges.c | 3 +\n t/t4013-diff-various.sh | 8 +++\n 4 files changed, 71 insertions(+), 45 deletions(-)\n\n-- \n2.25.1\n\n"},{"id":"481624","messageId":"20230909125446.142715-3-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230909125446.142715-1-sorganov@gmail.com","subject":"[PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-09T12:54:46Z","receivedAt":"2023-09-09T12:55:14Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This option provides a shortcut to request diff with respect to first\nparent for any kind of commit, universally. It's implemented as pure\nsynonym for \"--diff-merges=first-parent --patch\".\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 4 ++++\n Documentation/git-log.txt | 2 +-\n diff-merges.c | 3 +++\n t/t4013-diff-various.sh | 8 ++++++++\n 4 files changed, 16 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex f93aa3e46a52..d773dafcb10a 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -51,6 +51,10 @@ ifdef::git-log[]\n Note: This option not implying `-p` is legacy feature that is\n preserved for the sake of backward compatibility.\n \n+-d::\n+\tProduce diff with respect to first parent.\n+\tShortcut for '--diff-merges=first-parent -p'.\n+\n -c::\n \tProduce combined diff output for merge commits.\n \tShortcut for '--diff-merges=combined -p'.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 9b7ec96e767a..59bd74a1a596 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -120,7 +120,7 @@ By default, `git log` does not generate any diff output. The options\n below can be used to show the changes made by each commit.\n \n Note that unless one of `--diff-merges` variants (including short\n-`-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n+`-d`, `-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\ndiff --git a/diff-merges.c b/diff-merges.c\nindex ec97616db1df..6eb72e6fc28a 100644\n--- a/diff-merges.c\n+++ b/diff-merges.c\n@@ -125,6 +125,9 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n \tif (!suppress_m_parsing && !strcmp(arg, \"-m\")) {\n \t\tset_to_default(revs);\n \t\trevs->merges_need_diff = 0;\n+\t} else if (!strcmp(arg, \"-d\")) {\n+\t\tset_first_parent(revs);\n+\t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"-c\")) {\n \t\tset_combined(revs);\n \t\trevs->merges_imply_patch = 1;\ndiff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\nindex 5de1d190759f..a07d6eb6dd97 100755\n--- a/t/t4013-diff-various.sh\n+++ b/t/t4013-diff-various.sh\n@@ -473,6 +473,14 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n \ttest_cmp expected actual\n '\n \n+test_expect_success 'log -d matches --diff-merges=1 -p' '\n+\tgit log --diff-merges=1 -p master >result &&\n+\tprocess_diffs result >expected &&\n+\tgit log -d master >result &&\n+\tprocess_diffs result >actual &&\n+\ttest_cmp expected actual\n+'\n+\n test_expect_success 'deny wrong log.diffMerges config' '\n \ttest_config log.diffMerges wrong-value &&\n \ttest_expect_code 128 git log\n-- \n2.25.1\n\n"},{"id":"481625","messageId":"20230909125446.142715-2-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230909125446.142715-1-sorganov@gmail.com","subject":"[PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-09T12:54:45Z","receivedAt":"2023-09-09T12:55:14Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"* Put descriptions of convenience shortcuts first, so they are the\n first things reader observes, not lengthy stuff.\n\n* Add explanation note on '-m' not implying '-p' unlike similar\n options.\n\n* Get rid of very long line containing all the --diff-merges formats\n by replacing them with , and putting each supported format\n on its own line.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 97 +++++++++++++++++++---------------\n Documentation/git-log.txt | 2 +-\n 2 files changed, 55 insertions(+), 44 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9f33f887711d..f93aa3e46a52 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -43,66 +43,77 @@ endif::git-diff[]\n endif::git-format-patch[]\n \n ifdef::git-log[]\n---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n+-m::\n+\tShow diffs for merge commits in the default format. This is\n+\tsimilar to '--diff-merges=on' (which see) except `-m` will\n+\tproduce no output unless `-p` is given as well.\n++\n+Note: This option not implying `-p` is legacy feature that is\n+preserved for the sake of backward compatibility.\n+\n+-c::\n+\tProduce combined diff output for merge commits.\n+\tShortcut for '--diff-merges=combined -p'.\n+\n+--cc::\n+\tProduce dense combined diff output for merge commits.\n+\tShortcut for '--diff-merges=dense-combined -p'.\n+\n+--remerge-diff::\n+\tProduce diff against re-merge.\n+\tShortcut for '--diff-merges=remerge -p'.\n+\n --no-diff-merges::\n+\tSynonym for '--diff-merges=off'.\n+\n+--diff-merges=::\n \tSpecify diff format to be used for merge commits. Default is\n-\t{diff-merges-default} unless `--first-parent` is in use, in which case\n-\t`first-parent` is the default.\n+\t{diff-merges-default} unless `--first-parent` is in use, in\n+\twhich case `first-parent` is the default.\n +\n---diff-merges=(off|none):::\n---no-diff-merges:::\n+The following formats are supported:\n++\n+--\n+off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n +\n---diff-merges=on:::\n---diff-merges=m:::\n--m:::\n-\tThis option makes diff output for merge commits to be shown in\n-\tthe default format. `-m` will produce the output only if `-p`\n-\tis given as well. The default format could be changed using\n+on, m::\n+\tMake diff output for merge commits to be shown in the default\n+\tformat. The default format could be changed using\n \t`log.diffMerges` configuration parameter, which default value\n \tis `separate`.\n +\n---diff-merges=first-parent:::\n---diff-merges=1:::\n-\tThis option makes merge commits show the full diff with\n-\trespect to the first parent only.\n+first-parent, 1::\n+\tShow full diff with respect to first parent. This is the same\n+\tformat as `--patch` produces for non-merge commits.\n +\n---diff-merges=separate:::\n-\tThis makes merge commits show the full diff with respect to\n-\teach of the parents. Separate log entry and diff is generated\n-\tfor each parent.\n+separate::\n+\tShow full diff with respect to each of parents.\n+\tSeparate log entry and diff is generated for each parent.\n +\n---diff-merges=remerge:::\n---diff-merges=r:::\n---remerge-diff:::\n-\tWith this option, two-parent merge commits are remerged to\n-\tcreate a temporary tree object -- potentially containing files\n-\twith conflict markers and such. A diff is then shown between\n-\tthat temporary tree and the actual merge commit.\n+remerge, r::\n+\tRemerge two-parent merge commits to create a temporary tree\n+\tobject--potentially containing files with conflict markers\n+\tand such. A diff is then shown between that temporary tree\n+\tand the actual merge commit.\n +\n The output emitted when this option is used is subject to change, and\n so is its interaction with other options (unless explicitly\n documented).\n +\n---diff-merges=combined:::\n---diff-merges=c:::\n--c:::\n-\tWith this option, diff output for a merge commit shows the\n-\tdifferences from each of the parents to the merge result\n-\tsimultaneously instead of showing pairwise diff between a\n-\tparent and the result one at a time. Furthermore, it lists\n-\tonly files which were modified from all parents. `-c` implies\n-\t`-p`.\n+combined, c::\n+\tShow differences from each of the parents to the merge\n+\tresult simultaneously instead of showing pairwise diff between\n+\ta parent and the result one at a time. Furthermore, it lists\n+\tonly files which were modified from all parents.\n +\n---diff-merges=dense-combined:::\n---diff-merges=cc:::\n---cc:::\n-\tWith this option the output produced by\n-\t`--diff-merges=combined` is further compressed by omitting\n-\tuninteresting hunks whose contents in the parents have only\n-\ttwo variants and the merge result picks one of them without\n-\tmodification. `--cc` implies `-p`.\n+dense-combined, cc::\n+\tFurther compress output produced by `--diff-merges=combined`\n+\tby omitting uninteresting hunks whose contents in the parents\n+\thave only two variants and the merge result picks one of them\n+\twithout modification.\n+--\n \n --combined-all-paths::\n \tThis flag causes combined diffs (used for merge commits) to\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 2a66cf888074..9b7ec96e767a 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -124,7 +124,7 @@ Note that unless one of `--diff-merges` variants (including short\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\n-the default format.\n+the default format for merge commits.\n \n :git-log: 1\n :diff-merges-default: `off`\n-- \n2.25.1\n\n"},{"id":"481719","messageId":"xmqqfs3ktnvo.fsf@gitster.g","threadId":"60213","inReplyTo":"20230909125446.142715-2-sorganov@gmail.com","subject":"Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-11T21:12:59Z","receivedAt":"2023-09-11T23:16:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> ifdef::git-log[]\n> ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n> +-m::\n> +\tShow diffs for merge commits in the default format. This is\n> +\tsimilar to '--diff-merges=on' (which see) except `-m` will\n> +\tproduce no output unless `-p` is given as well.\n> ++\n> +Note: This option not implying `-p` is legacy feature that is\n> +preserved for the sake of backward compatibility.\n\nIt is more like that `-p` does not imply `-m` (which used to mean\n\"consider showing the comparison between parent(s) and the child,\neven for merge commits\"), even though newer options like `-c`,\n`--cc` and others do imply `-m` (simply because they do not make\nmuch sense if they are not allowed to work on merges) that may make\nnew people confused. If `-p` implied `-m` (or if `-m` implied\n`-p`), it would also have been utterly confusing and useless for\nhuman consumption.\n\nIn either case, unless the reason why `-p` does not imply `-m`\nunlike others is explained, I do not think the note adds that much\nvalue. I'd suggest dropping it.\n\n> --no-diff-merges::\n> +\tSynonym for '--diff-merges=off'.\n> +\n> +--diff-merges=::\n> \tSpecify diff format to be used for merge commits. Default is\n> -\t{diff-merges-default} unless `--first-parent` is in use, in which case\n> -\t`first-parent` is the default.\n> +\t{diff-merges-default} unless `--first-parent` is in use, in\n> +\twhich case `first-parent` is the default.\n> +\n> +The following formats are supported:\n> ++\n> +--\n> +off, none::\n> \tDisable output of diffs for merge commits. Useful to override\n> \timplied value.\n> +\n> +on, m::\n> +\tMake diff output for merge commits to be shown in the default\n> +\tformat. The default format could be changed using\n> \t`log.diffMerges` configuration parameter, which default value\n> \tis `separate`.\n> +\n> +first-parent, 1::\n> +\tShow full diff with respect to first parent. This is the same\n> +\tformat as `--patch` produces for non-merge commits.\n> +\n> +separate::\n> +\tShow full diff with respect to each of parents.\n> +\tSeparate log entry and diff is generated for each parent.\n> +\n> +remerge, r::\n> +\tRemerge two-parent merge commits to create a temporary tree\n> +\tobject--potentially containing files with conflict markers\n> +\tand such. A diff is then shown between that temporary tree\n> +\tand the actual merge commit.\n> +\n> The output emitted when this option is used is subject to change, and\n> so is its interaction with other options (unless explicitly\n> documented).\n> +\n> +combined, c::\n> +\tShow differences from each of the parents to the merge\n> +\tresult simultaneously instead of showing pairwise diff between\n> +\ta parent and the result one at a time. Furthermore, it lists\n> +\tonly files which were modified from all parents.\n> +\n> +dense-combined, cc::\n> +\tFurther compress output produced by `--diff-merges=combined`\n> +\tby omitting uninteresting hunks whose contents in the parents\n> +\thave only two variants and the merge result picks one of them\n> +\twithout modification.\n> +--\n\nLooks reasonable, even though I didn't quite see much problem with\nthe original. If we were shuffling the sections like this patch, I\nwonder if moving combined/dense-combined a bit higher (perhaps\nbefore the \"remerge\") may make more sense, though (the ordering\nwould simply become \"simpler to more involved\").\n"},{"id":"481728","messageId":"xmqqtts0tof8.fsf@gitster.g","threadId":"60213","inReplyTo":"20230909125446.142715-3-sorganov@gmail.com","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-11T21:01:15Z","receivedAt":"2023-09-12T01:41:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> This option provides a shortcut to request diff with respect to first\n> parent for any kind of commit, universally. It's implemented as pure\n> synonym for \"--diff-merges=first-parent --patch\".\n>\n> Signed-off-by: Sergey Organov \n> ---\n\nSounds very straight-forward.\n\nGiven that \"--first-parent\" in \"git log --first-parent -p\" already\ndefeats \"-m\" and shows the diff against the first parent only,\npeople may find it confusing if \"git log -d\" does not act as a\nshorthand for that. From the above and also from the documentation\nupdate, it is hard to tell if that is what you implemented, or it\nonly affects the \"diff-merges\" part.\n\nOther than that, the patch looks quite small and to the point.\n\nThanks.\n\n> Documentation/diff-options.txt | 4 ++++\n> Documentation/git-log.txt | 2 +-\n> diff-merges.c | 3 +++\n> t/t4013-diff-various.sh | 8 ++++++++\n> 4 files changed, 16 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index f93aa3e46a52..d773dafcb10a 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -51,6 +51,10 @@ ifdef::git-log[]\n> Note: This option not implying `-p` is legacy feature that is\n> preserved for the sake of backward compatibility.\n> \n> +-d::\n> +\tProduce diff with respect to first parent.\n> +\tShortcut for '--diff-merges=first-parent -p'.\n> +\n> -c::\n> \tProduce combined diff output for merge commits.\n> \tShortcut for '--diff-merges=combined -p'.\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index 9b7ec96e767a..59bd74a1a596 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -120,7 +120,7 @@ By default, `git log` does not generate any diff output. The options\n> below can be used to show the changes made by each commit.\n> \n> Note that unless one of `--diff-merges` variants (including short\n> -`-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n> +`-d`, `-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n> will not show a diff, even if a diff format like `--patch` is\n> selected, nor will they match search options like `-S`. The exception\n> is when `--first-parent` is in use, in which case `first-parent` is\n> diff --git a/diff-merges.c b/diff-merges.c\n> index ec97616db1df..6eb72e6fc28a 100644\n> --- a/diff-merges.c\n> +++ b/diff-merges.c\n> @@ -125,6 +125,9 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n> \tif (!suppress_m_parsing && !strcmp(arg, \"-m\")) {\n> \t\tset_to_default(revs);\n> \t\trevs->merges_need_diff = 0;\n> +\t} else if (!strcmp(arg, \"-d\")) {\n> +\t\tset_first_parent(revs);\n> +\t\trevs->merges_imply_patch = 1;\n> \t} else if (!strcmp(arg, \"-c\")) {\n> \t\tset_combined(revs);\n> \t\trevs->merges_imply_patch = 1;\n> diff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\n> index 5de1d190759f..a07d6eb6dd97 100755\n> --- a/t/t4013-diff-various.sh\n> +++ b/t/t4013-diff-various.sh\n> @@ -473,6 +473,14 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n> \ttest_cmp expected actual\n> '\n> \n> +test_expect_success 'log -d matches --diff-merges=1 -p' '\n> +\tgit log --diff-merges=1 -p master >result &&\n> +\tprocess_diffs result >expected &&\n> +\tgit log -d master >result &&\n> +\tprocess_diffs result >actual &&\n> +\ttest_cmp expected actual\n> +'\n> +\n> test_expect_success 'deny wrong log.diffMerges config' '\n> \ttest_config log.diffMerges wrong-value &&\n> \ttest_expect_code 128 git log\n"},{"id":"481744","messageId":"87ttrzhmfu.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqfs3ktnvo.fsf@gitster.g","subject":"Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-12T07:37:09Z","receivedAt":"2023-09-12T07:37:17Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> ifdef::git-log[]\n>> ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n>> +-m::\n>> +\tShow diffs for merge commits in the default format. This is\n>> +\tsimilar to '--diff-merges=on' (which see) except `-m` will\n>> +\tproduce no output unless `-p` is given as well.\n>> ++\n>> +Note: This option not implying `-p` is legacy feature that is\n>> +preserved for the sake of backward compatibility.\n>\n> It is more like that `-p` does not imply `-m` (which used to mean\n> \"consider showing the comparison between parent(s) and the child,\n> even for merge commits\"), even though newer options like `-c`,\n> `--cc` and others do imply `-m` (simply because they do not make\n> much sense if they are not allowed to work on merges) that may make\n> new people confused.\n\nNo, neither --cc nor -c imply -m.\n\n-m is documented to produce very specific output that is neither -c nor\n--cc, and it's indeed how it works.\n\n-c and --cc imply -p, not -m, and it has been documented for ages\nalready, and it's indeed how it works, and that's what corresponding\ncommits that added the features claim.\n\nOverall, --cc, -c, and --remerge-diff all imply -p, whereas -m does not.\nThis is simple fact.\n\nSo I feel we need to document why -m doesn't imply -p as other similar\noptions do.\n\n> If `-p` implied `-m` (or if `-m` implied\n> `-p`), it would also have been utterly confusing and useless for\n> human consumption.\n\nFortunately, -p does not imply -m, but if -m implied -p, similar to --cc\nand -c, it'd be rather very natural, and thus people keep asking why\nit's not the case.\n\n> In either case, unless the reason why `-p` does not imply `-m`\n> unlike others is explained, I do not think the note adds that much\n> value. I'd suggest dropping it.\n\n-p does not imply others. It's others (--cc, etc.) that imply -p.\n\nThe problem being solved is that we periodically get (valid) questions\nwhy -m does not behave similar to -c and --cc, and now --remerge-diff.\n\n>\n>> --no-diff-merges::\n>> +\tSynonym for '--diff-merges=off'.\n>> +\n>> +--diff-merges=::\n>> \tSpecify diff format to be used for merge commits. Default is\n>> -\t{diff-merges-default} unless `--first-parent` is in use, in which case\n>> -\t`first-parent` is the default.\n>> +\t{diff-merges-default} unless `--first-parent` is in use, in\n>> +\twhich case `first-parent` is the default.\n>> +\n>> +The following formats are supported:\n>> ++\n>> +--\n>> +off, none::\n>> \tDisable output of diffs for merge commits. Useful to override\n>> \timplied value.\n>> +\n>> +on, m::\n>> +\tMake diff output for merge commits to be shown in the default\n>> +\tformat. The default format could be changed using\n>> \t`log.diffMerges` configuration parameter, which default value\n>> \tis `separate`.\n>> +\n>> +first-parent, 1::\n>> +\tShow full diff with respect to first parent. This is the same\n>> +\tformat as `--patch` produces for non-merge commits.\n>> +\n>> +separate::\n>> +\tShow full diff with respect to each of parents.\n>> +\tSeparate log entry and diff is generated for each parent.\n>> +\n>> +remerge, r::\n>> +\tRemerge two-parent merge commits to create a temporary tree\n>> +\tobject--potentially containing files with conflict markers\n>> +\tand such. A diff is then shown between that temporary tree\n>> +\tand the actual merge commit.\n>> +\n>> The output emitted when this option is used is subject to change, and\n>> so is its interaction with other options (unless explicitly\n>> documented).\n>> +\n>> +combined, c::\n>> +\tShow differences from each of the parents to the merge\n>> +\tresult simultaneously instead of showing pairwise diff between\n>> +\ta parent and the result one at a time. Furthermore, it lists\n>> +\tonly files which were modified from all parents.\n>> +\n>> +dense-combined, cc::\n>> +\tFurther compress output produced by `--diff-merges=combined`\n>> +\tby omitting uninteresting hunks whose contents in the parents\n>> +\thave only two variants and the merge result picks one of them\n>> +\twithout modification.\n>> +--\n>\n> Looks reasonable, even though I didn't quite see much problem with\n> the original.\n\nThe original --diff-merge=... line was so long it didn't fit, especially\nafter \"remerge\" has been added, and also was hard to grok.\n\n> If we were shuffling the sections like this patch, I\n> wonder if moving combined/dense-combined a bit higher (perhaps\n> before the \"remerge\") may make more sense, though (the ordering\n> would simply become \"simpler to more involved\").\n\nI kept original order, but I agree combined/dense-combined fit better\nabove remerge.\n\nI'll change the order in re-roll.\n\nThanks,\n-- Sergey Organov\n"},{"id":"481747","messageId":"87o7i7hler.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqtts0tof8.fsf@gitster.g","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-12T07:59:24Z","receivedAt":"2023-09-12T08:03:17Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> This option provides a shortcut to request diff with respect to first\n>> parent for any kind of commit, universally. It's implemented as pure\n>> synonym for \"--diff-merges=first-parent --patch\".\n>>\n>> Signed-off-by: Sergey Organov \n>> ---\n>\n> Sounds very straight-forward.\n>\n> Given that \"--first-parent\" in \"git log --first-parent -p\" already\n> defeats \"-m\" and shows the diff against the first parent only,\n> people may find it confusing if \"git log -d\" does not act as a\n> shorthand for that.\n\nIt doesn't, and I believe it's a good thing, as primary function of\n--first-parent is to change history traversal rules, and if -d did that,\nit would be extremely confusing.\n\nAlso, --first-parent is correctly documented as implying\n--diff-merges=first-parent, not as defeating -m.\n\n> From the above and also from the documentation update, it is hard to\n> tell if that is what you implemented, or it only affects the\n> \"diff-merges\" part.\n\nIf we read resulting documentation with a fresh eye, -d is similar to\n--cc, and -c, just producing yet another kind of output, so I think all\nthis fits together quite nicely and shouldn't cause confusion.\n\n>\n> Other than that, the patch looks quite small and to the point.\n\nThanks,\n-- Sergey Organov\n"},{"id":"481794","messageId":"xmqqcyymly5m.fsf@gitster.g","threadId":"60213","inReplyTo":"87ttrzhmfu.fsf@osv.gnss.ru","subject":"Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-13T00:22:45Z","receivedAt":"2023-09-13T00:22:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n>> It is more like that `-p` does not imply `-m` (which used to mean\n>> \"consider showing the comparison between parent(s) and the child,\n>> even for merge commits\"), even though newer options like `-c`,\n>> `--cc` and others do imply `-m` (simply because they do not make\n>> much sense if they are not allowed to work on merges) that may make\n>> new people confused.\n>\n> No, neither --cc nor -c imply -m.\n\nI was only trying to help you polish the text you added to explain\nwhat you called the \"legacy feature\" to reflect the reason behind\nthat legacy. As you obviously were not there back then when I made\n\"--cc\" imply \"-m\" while keeping \"-p\" not to imply \"-m\".\n\nOur \"git log [--diff-output-options]\" logic was (and still is) not\nto show the comparison between parents and the child by default for\nmerge commits even with -p/--raw/--stat (these were what existed and\nwere common back then) and \"git log --raw/--stat/-p\" showed the\nraw/diffstat/patch after the log message for one-parent commits but\nonly the log message for merges.\n\nThe reason behind that design choice is that Linus (and I and\nothers) did not find that the patches for merges are as useful as\npatches for regular commits. We made \"git log -p\" to omit\npatches for merges that tend to become large.\n\n\tSide note: the first-parent patch is sort of readable, but\n\tif you are not doing the \"--first-parent\" traversal (which\n\tis a much later invention, so it wasn't even an option), you\n\tare showing individual commits and their patches while\n\ttraversing the side branch, then the first-parent patch of a\n\tmerge amounts to the squash of individual changes on the\n\tside branch that got merged. It was deemed redundant\n\tpresentation that is just wasteful and harder to grok than\n\treading individual commits. Worse, the patch against second\n\tand later parent(s) have no real value (it shows how behind\n\tthe fork point of the side branch was relative to the tip of\n\tthe trunk, which is rarely useful).\n\nBut we also wanted to have a mode of \"git log -p\" that spews\neverything to the output that could be used to reconstruct the\nhistory, hence we added \"-m\" to tell \"git log\":\n\n\tBy default, you are designed not to show comparison between\n\tparents and the child for merge commit. But when \"-m\" is\n\tgiven, do show the comparison for merge commit in the format\n\tthat other options given to you, like --raw, --patch,\n\tspecifies.\n\nWe however didn't have a good idea how to represent such a\ncomparison between parents and the child, so we chose the most\nredundant, verbose, and obvious, which is N pairwise patches with\neach of N parents to the child (for a N-parent patch).\n\nLater \"--cc\" and \"-c\" came as an alternative way to represent\ncomparison between parents and the child.\n\nGiven that I, together with Linus, invented \"--cc\" and \"-c\", taking\ninspiration from how Paul Mackerras showed a merge in his 'gitk'\ntool, and made the design decision not to require \"-m\" to get the\noutput in the format they specify when the \"git log\" traversal shows\nmerge commits, I do not know what to say when you repeat that \"--cc\"\ndoes not imply \"-m\". It simply is not true.\n\nI think this is the second time you claimed the above after I\nexplained the same to you, if I am not mistaken. If you do not want\nto be corrected, that is fine, and I'll stop wasting my time trying\nto correct you.\n\nBut I still have to make sure that you (or anybody else) do not\nspread misinformation to other users by writing incorrect statements\nin documentation patches.\n\n"},{"id":"481856","messageId":"xmqqled8h01w.fsf@gitster.g","threadId":"60213","inReplyTo":"87o7i7hler.fsf@osv.gnss.ru","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-14T22:17:31Z","receivedAt":"2023-09-14T22:17:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n>> Sounds very straight-forward.\n>>\n>> Given that \"--first-parent\" in \"git log --first-parent -p\" already\n>> defeats \"-m\" and shows the diff against the first parent only,\n>> people may find it confusing if \"git log -d\" does not act as a\n>> shorthand for that.\n>\n> It doesn't, and I believe it's a good thing, as primary function of\n> --first-parent is to change history traversal rules, and if -d did that,\n> it would be extremely confusing.\n\nI am not sure about that.\n\n> Also, --first-parent is correctly documented as implying\n> --diff-merges=first-parent, not as defeating -m.\n\nYes, exactly. That makes me even more convinced that the intuitive\nbehaviour, when we say \"we have this great short-hand option that\nlets your 'git log' to do the first-parent thing with patch output\",\nis to do the first-parent traversal _and_ show first-parent patches.\n\n\"-d\" is documented as a short-hand for \"--diff-merges=first-parent\n--patch\" and not for \"--first-parent --patch\", so the behaviour may\ncorrectly match documentation, but that does not make the documented\nbehaviour an intuitive one. And a behaviour that is not intuitive\nis confusing.\n\n> If we read resulting documentation with a fresh eye, -d is similar to\n> --cc, and -c, just producing yet another kind of output, so I think all\n> this fits together quite nicely and shouldn't cause confusion.\n\nAnother thing is that showing first-parent patch for merges while\nletting the traversal also visit the second-parent chain is not as\nuseful an option as it could be, even though it is not so bad as the\noriginal \"-m -p\" that also showed second-parent patch for merges as\nwell. People would have to say \"log --first-parent -p\" to get the\nfirst-parent traversal with first-parent patch output, and they\nwould not behefit from having \"-d\".\n"},{"id":"481860","messageId":"87y1h8wbpo.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqled8h01w.fsf@gitster.g","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-14T23:56:35Z","receivedAt":"2023-09-14T23:56:40Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> Sounds very straight-forward.\n>>>\n>>> Given that \"--first-parent\" in \"git log --first-parent -p\" already\n>>> defeats \"-m\" and shows the diff against the first parent only,\n>>> people may find it confusing if \"git log -d\" does not act as a\n>>> shorthand for that.\n>>\n>> It doesn't, and I believe it's a good thing, as primary function of\n>> --first-parent is to change history traversal rules, and if -d did that,\n>> it would be extremely confusing.\n>\n> I am not sure about that.\n>\n>> Also, --first-parent is correctly documented as implying\n>> --diff-merges=first-parent, not as defeating -m.\n>\n> Yes, exactly. That makes me even more convinced that the intuitive\n> behaviour, when we say \"we have this great short-hand option that\n> lets your 'git log' to do the first-parent thing with patch output\",\n> is to do the first-parent traversal _and_ show first-parent patches.\n>\n> \"-d\" is documented as a short-hand for \"--diff-merges=first-parent\n> --patch\" and not for \"--first-parent --patch\", so the behaviour may\n> correctly match documentation, but that does not make the documented\n> behaviour an intuitive one. And a behaviour that is not intuitive\n> is confusing.\n\nI think both behaviors make sense, provided they are correctly\ndocumented. I just prefer the one that is more basic, yet allows to\nachieve things that another one does not.\n\n>\n>> If we read resulting documentation with a fresh eye, -d is similar to\n>> --cc, and -c, just producing yet another kind of output, so I think all\n>> this fits together quite nicely and shouldn't cause confusion.\n>\n> Another thing is that showing first-parent patch for merges while\n> letting the traversal also visit the second-parent chain is not as\n> useful an option as it could be, even though it is not so bad as the\n> original \"-m -p\" that also showed second-parent patch for merges as\n> well.\n\nI don't see why desire to look at diff-to-first-parent on \"side\"\nbranches is any different from desire to look at them on \"primary\"\nbranch, sorry, so I still don't want \"-d\" to affect traversal or other\ncommit filtering rules. We do have --first-parent as well as a few\nothers for that.\n\n> People would have to say \"log --first-parent -p\" to get the\n> first-parent traversal with first-parent patch output, and they\n> would not behefit from having \"-d\".\n\nWell, at least they can now say \"log --first-parent -d\" as well ;)\n\nHonestly, the \"log --first-parent -p\" (without \"-m\") suddenly producing\ndiffs for merge commits is already unnatural, needs yet another\nspecial-casing in documentation, and then, finally, this relatively new\nbehavior was introduced exactly because there were no \"-d\" at that time,\nto save typing \"-m\". The latter is yet another example of why \"-d\" in\nits current form is a good idea.\n\nThat said, if you feel like there is place for a short-cut for this\nparticular use-case, it'd be fine with me, say:\n\n--fpd:\n short-cut for \"--first-parent -d\"\n\nwould fit quite nicely into the picture, I think.\n\nThanks,\n-- Sergey Organov\n"},{"id":"481878","messageId":"xmqqzg1nfixw.fsf@gitster.g","threadId":"60213","inReplyTo":"87y1h8wbpo.fsf@osv.gnss.ru","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-15T17:24:43Z","receivedAt":"2023-09-15T17:25:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> I don't see why desire to look at diff-to-first-parent on \"side\"\n> branches is any different from desire to look at them on \"primary\"\n> branch\n\nYeah, but that is not what I meant. The above argues for why\n\"--diff-merges=first-parent\" should exist independently from the\n\"--first-parent\" traversal *and* display option. I am not saying\nit should not exist.\n\nBut I view that the desire to look at any commits and its changes on\nthe \"side\" branch at all *is* at odds with the wish to look at\nfirst-parent change for merge commits. Once you decide to look at\nfirst-parent change for a merge commit, then every change you see\nfor each commit on the \"side\" branch, whether it is shown as\nfirst-parent diff or N pairwise diffs, is what you have already seen\nin the change in the merge commit, because \"git log\" goes newer to\nolder, and the commits on the side branches appear after the merge\nthat brings them to the mainline.\n\nMaking \"log -d\" mean \"log --diff-merges=first-parent --patch\" lets\nthat less useful combination (\"show first-parent patches but\ntraverse side branches as well\") squat on the short and sweet \"-d\"\nthat could be used for more useful \"log --first-parent --patch\",\nwhich would also be more common and intuitive to users, and that is\nwhat I suspect will become problematic in the longer run.\n\nThanks.\n\n"},{"id":"481933","messageId":"87ttrudkw9.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqzg1nfixw.fsf@gitster.g","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-16T18:37:42Z","receivedAt":"2023-09-16T18:38:56Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> I don't see why desire to look at diff-to-first-parent on \"side\"\n>> branches is any different from desire to look at them on \"primary\"\n>> branch\n>\n> Yeah, but that is not what I meant. The above argues for why\n> \"--diff-merges=first-parent\" should exist independently from the\n> \"--first-parent\" traversal *and* display option. I am not saying\n> it should not exist.\n\nI was not assuming you were saying this, as it has been discussed and\nagreed upon when --diff-merges=first-parent was introduced, though I\nthink I now see your point more clearly.\n\n>\n> But I view that the desire to look at any commits and its changes on\n> the \"side\" branch at all *is* at odds with the wish to look at\n> first-parent change for merge commits.\n\nI think I do now understand what you mean, yet I have alternative view\non the issue.\n\n> Once you decide to look at first-parent change for a merge commit,\n> then every change you see for each commit on the \"side\" branch,\n> whether it is shown as first-parent diff or N pairwise diffs, is what\n> you have already seen in the change in the merge commit,\n\nActually, this happens to be exactly one of intended use-cases for \"-d\".\nIt's useful to see how some change introduced by the merge looked in the\ncontext of the original commit, or to figure where the change came from.\n\n> because \"git log\" goes newer to older, and the commits on the side\n> branches appear after the merge that brings them to the mainline.\n\nThe exact order is orthogonal to the issue at hands, I think.\n\n> Making \"log -d\" mean \"log --diff-merges=first-parent --patch\" lets\n> that less useful combination (\"show first-parent patches but\n> traverse side branches as well\") squat on the short and sweet \"-d\"\n> that could be used for more useful \"log --first-parent --patch\",\n> which would also be more common and intuitive to users, and that is\n> what I suspect will become problematic in the longer run.\n\nSorry, \"-d ≡ --first-parent --patch\" you suggest contradicts my view on\nthe whole scheme of things, for several reasons:\n\n* I still find it problematic if -d, intended to fit nicely among --cc,\n-c, -d, -m, -p, --remerge-diff options, suddenly implies --first-parent.\nThis would bring yet another inconsistency, and I don't want to be the\none who introduced it.\n\n* In its current state -d conveniently means: \"gimme simple diff output\nfor everything\", where --first-parent you suggest doesn't fit at all.\n\n* Current -d implementation is semantically as close to -p as possible,\ntweaking exactly one thing compared to -p: the format of output for\nmerge commits, so is simpler than what you suggest from all angles, as\n--first-parent tweaks more than one thing.\n\n* To me what you argue for looks mostly like a desire to have a\nshort-cut for \"--first-parent --patch\", and my patch in question does\nnot seem to contradict this desire, as it'd be very surprising if\nsomebody came up with the name \"-d\" for such a short-cut. Definitely not\nme.\n\n* Finally, if -d becomes \"--patch --first-parent\", how do I get back\nuseful \"--patch --diff-merges=first-parent\" part of it, provided\n--first-parent is unreversable? And even if it were reversable, then\n\n git log -d --no-first-parent =\n git log --patch --first-parent --no-first-parent =\n git log --patch\n\nis definitely not what is needed, nor frequent demand to revert implied\nthings indicates optimal design. Compare this to\n\n git log -d --first-parent\n\nthat current -d provides for you to get what you need, and that\nunambiguously reads: \"gimme *d*iff for all commits while following\n*first parent* through the history\" (while, unlike, -p not requiring\n--first-parent to implicitly tweak diff for merges output).\n\nOverall, after considering your concern, I'd still prefer to leave \"-d\"\nsemantics as implemented, consistent with the rest of similar options,\nand let somebody else define more shortcuts for their frequent use-cases\nif they feel like it.\n\nThanks,\n-- Sergey Organov\n\nP.S. I also figure that maybe our divergence comes from the fact that I\nconsider merge commits to be primarily commits (introducing particular\nset of changes, and then having reference to the source of the changes),\nwhereas you consider them primarily merges (joining two histories, and\nthen maybe some artificial changes that make merges \"evil\"). That's why\nwe often end up agreeing to disagree, as both these points of view seem\npretty valid.\n"},{"id":"481959","messageId":"87v8c7mp1j.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqcyymly5m.fsf@gitster.g","subject":"Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-18T16:20:08Z","receivedAt":"2023-09-18T16:26:27Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>>> It is more like that `-p` does not imply `-m` (which used to mean\n>>> \"consider showing the comparison between parent(s) and the child,\n>>> even for merge commits\"), even though newer options like `-c`,\n>>> `--cc` and others do imply `-m` (simply because they do not make\n>>> much sense if they are not allowed to work on merges) that may make\n>>> new people confused.\n>>\n>> No, neither --cc nor -c imply -m.\n>\n> I was only trying to help you polish the text you added to explain\n> what you called the \"legacy feature\" to reflect the reason behind\n> that legacy. As you obviously were not there back then when I made\n> \"--cc\" imply \"-m\" while keeping \"-p\" not to imply \"-m\".\n\nYour help is appreciated, yet unfortunately I still can't figure how to\nimprove the text based on your advice.\n\nYour \"I made --cc imply -m\" does not explain why later, when you made\n--cc imply -p (did you, or was it somebody else?), you didn't make -m\nimply -p at the same time, and then \"while keeping -p not to imply -m\"\nsounds out of place as we rather try to figure why \"-m not implies -p\".\n\nThe \"--c imply -m\" part of the help raises yet another question: if --cc\nimplied -m, why it was not -m that was made to imply -p instead of --cc\n(and -c)? Then both --cc and -c would imply -p automatically as a\nside-effect of implication of -p by -m (do not confuse with agreed\nnon-implication of -m by -p), and then all the relevant options were\nconsistent. This consideration renders current situation more surprising\ninstead of clarifying it, I'm afraid.\n\n\"-p does not imply -m\" fact is fine with me and is not the cause of user\nconfusion I'm trying to address. How does it help us to explain why \"-m\ndoes not imply -p\" though?\n\n[...]\n\n>\n> Given that I, together with Linus, invented \"--cc\" and \"-c\", taking\n> inspiration from how Paul Mackerras showed a merge in his 'gitk'\n> tool, and made the design decision not to require \"-m\" to get the\n> output in the format they specify when the \"git log\" traversal shows\n> merge commits, I do not know what to say when you repeat that \"--cc\"\n> does not imply \"-m\". It simply is not true.\n\nI keep saying \"--cc does not imply -m\" because it does not seem to,\nunless you either use some vague meaning of \"imply\", or mean some other\n\"-m\", not the one used in \"git log\". Please check:\n\n$ cd src/git\n$ git --version\ngit version 2.42.0.111.gd814540bb75b\n$ git describe\nv2.42.0-111-gd814540bb75b\n$ git log 74a2e88700efc -n1 -p --cc > diff.actual\n$ git log 74a2e88700efc -n1 -p --cc -m > diff.expected\n$ cmp diff.expected diff.actual\ndiff.expected diff.actual differ: byte 706, line 18\n$\n\nThis test tells us that \"--c\" is not the same as \"--cc -m\", that for me\nin turn reads \"--cc does not imply -m\", and that's what I continue to\nsay.\n\n>\n> I think this is the second time you claimed the above after I\n> explained the same to you, if I am not mistaken. If you do not want\n> to be corrected, that is fine, and I'll stop wasting my time trying\n> to correct you.\n\nI'd love to be corrected, but I think I carefully checked my grounds\nbefore saying that --cc does not imply -m, please consider:\n\n1. \"--cc implies -m\" is not documented. Please point to the\n documentation in case I missed it.\n\n2. Git does not behave as if \"--cc implied -m\", see the test-case above.\n\nIf it's neither documented nor matches actual behavior, it's not there,\nat least from the POV of random user, to whom my original clarification\nof \"why -m does not imply -p?\" has been addressed.\n\nOn top of that, I even can't figure why we argue about it in the first\nplace, as it seems to be irrelevant to the issue at hand: explain why -m\ndoes not imply -p?\n\n>\n> But I still have to make sure that you (or anybody else) do not\n> spread misinformation to other users by writing incorrect statements\n> in documentation patches.\n\nI'm all against spreading misinformation, and try my best to avoid it\nmyself. I still fail to see what misinformation, exactly, you find in\nthis particular explanation by me:\n\n\" Note: This option [`-m`] not implying `-p` is legacy feature that is\n preserved for the sake of backward compatibility. \"\n\nThat's exactly what I figured out from a lot of discussions over my\nmultiple attempts to make `-m` behave more usefully. Is it that \"legacy\nfeature\" somehow sounds offensive, or what?\n\nAs, despite your help, I fail to come up with better edition of the\nnote, please, if you feel like it, suggest your own variant of\nexplanation to the user why `-m` is left inconsistent with the rest of\ndiff for merges options, provided current matching documentation reads\nroughly like this (from more recent options to oldest):\n\n --remrege-diff: produces \"remerge\" output. Implies -p.\n --cc: produces dense combined output. Implies -p.\n -c: produces combined output. Implies -p.\n -m: produces separate output, provided -p is given as well (?!).\n\nand so why\n\n git log -m\n\nsurprisingly has no visible effect, and then the user needs to\ntype:\n\n git log -m -p\n\n\nThat's all I wanted to explain to the user in a few words with the note\nyou argue against.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482017","messageId":"xmqqh6nqgltw.fsf@gitster.g","threadId":"60213","inReplyTo":"87v8c7mp1j.fsf@osv.gnss.ru","subject":"Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-19T16:38:19Z","receivedAt":"2023-09-19T16:38:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> Junio C Hamano writes:\n>\n>> I was only trying to help you polish the text you added to explain\n>> what you called the \"legacy feature\" to reflect the reason behind\n>> that legacy. As you obviously were not there back then when I made\n>> \"--cc\" imply \"-m\" while keeping \"-p\" not to imply \"-m\".\n>\n> Your help is appreciated, yet unfortunately I still can't figure how to\n> improve the text based on your advice.\n\nIf I were doing this patch, I would start from something like this:\n\n-m::\n\tBy default, comparisons between parent commits and the child\n\tcommit are not shown for merge commits, but with the `-m`\n\toption, `git log` can be told to show comparisons for merges\n\tin chosen formats (e.g. `--raw`, `-p`, `--stat`). When\n\toutput formats (e.g. `--cc`) that are specifically designed\n\tto show better comparisons for merges are given, this option\n\tis implied; in other words, you do not have to say e.g. `git\n\tlog -m --cc`. `git log --cc` suffices.\n\n\nThe rest is a tangent that is not related to the above. I suspect\nthat this also applies to newer `--remerge-diff`, as it also targets\nto show merges better than the original \"pairwise patches\" that were\nlargely useless, but the right way to view what `--cc` and other\nformats do for non-merge commits is *not* to think that they \"imply\"\n`-p`. It is more like that the output from these formats on\nnon-merge commits happen to be identical to what `-p` would produce.\nYou could say that the \"magic\" these options know to show merge\ncommits better degenerates to what `-p` gives when applied to\nnon-merge commits.\n\nAnother way to look at it is that `--cc` and friends, even though\nthey are meant as improvements for showing merges over \"-m -p\" that\ngives human-unreadable pair-wise diffs, do not imply \"--merges\"\n(i.e. show only merge commits)---hence they have to show something\nfor non-merge commits. Because output formats for all of them were\nmodeled loosely [*] after \"-p\" output, we happened to pick it as the\nformat they fall back to when they are not showing comparisons for\nmerge commits.\n\n\n[Footnote]\n\n * Here, `-p` roughly means \"what GNU patch and `git apply` take\".\n Output from `-c` and `--cc` on merge commits do not qualify, but\n they are loosely modeled after it.\n"},{"id":"482032","messageId":"87il86q6sq.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqh6nqgltw.fsf@gitster.g","subject":"Re: [PATCH 1/2] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-19T19:52:53Z","receivedAt":"2023-09-19T19:53:00Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> Junio C Hamano writes:\n>>\n>>> I was only trying to help you polish the text you added to explain\n>>> what you called the \"legacy feature\" to reflect the reason behind\n>>> that legacy. As you obviously were not there back then when I made\n>>> \"--cc\" imply \"-m\" while keeping \"-p\" not to imply \"-m\".\n>>\n>> Your help is appreciated, yet unfortunately I still can't figure how to\n>> improve the text based on your advice.\n>\n> If I were doing this patch, I would start from something like this:\n>\n> -m::\n> \tBy default, comparisons between parent commits and the child\n> \tcommit are not shown for merge commits, but with the `-m`\n> \toption, `git log` can be told to show comparisons for merges\n> \tin chosen formats (e.g. `--raw`, `-p`, `--stat`). When\n> \toutput formats (e.g. `--cc`) that are specifically designed\n> \tto show better comparisons for merges are given, this option\n> \tis implied; in other words, you do not have to say e.g. `git\n> \tlog -m --cc`. `git log --cc` suffices.\n\nWell, to me this piece looks much harder to understand than current Git\ndocumentation, and then seemingly contradicts current Git behavior and\nimplementation, as \"log --cc -m\" is not the same as \"log --cc\" in the\ncurrent Git (so we can't say that --cc implies -m), and \"log -m --cc\" is\nthe same as \"log --cc\" due to absolutely different reason: -m and --cc\nare mutually exclusive options, so the last one simply takes precedence.\n\nIn the current Git, as documented, -m just produces separate diff with\nrespect to every parent. Simple and straightforward. Users don't need to\nlearn about --cc, -c, --raw, --stat... to figure what -m does and if\nit's what they need. Unfortunately they still need to learn about -p,\nbut I'm already done trying to promote this simple change.\n\n>\n> The rest is a tangent that is not related to the above. I suspect\n> that this also applies to newer `--remerge-diff`, as it also targets\n> to show merges better than the original \"pairwise patches\" that were\n> largely useless, but the right way to view what `--cc` and other\n> formats do for non-merge commits is *not* to think that they \"imply\"\n> `-p`. It is more like that the output from these formats on\n> non-merge commits happen to be identical to what `-p` would produce.\n> You could say that the \"magic\" these options know to show merge\n> commits better degenerates to what `-p` gives when applied to\n> non-merge commits.\n>\n> Another way to look at it is that `--cc` and friends, even though\n> they are meant as improvements for showing merges over \"-m -p\" that\n> gives human-unreadable pair-wise diffs, do not imply \"--merges\"\n> (i.e. show only merge commits)---hence they have to show something\n> for non-merge commits. Because output formats for all of them were\n> modeled loosely [*] after \"-p\" output, we happened to pick it as the\n> format they fall back to when they are not showing comparisons for\n> merge commits.\n\nI admit you are very creative producing these views,, but currently\nthese options just imply -p. Simple to understand, useful, works.\n\nOverall, as you don't like my simple clarification, and I don't like the\ndirection(s) you propose, I figure I rather withdraw the part of patch\ncausing contention in the re-roll.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482069","messageId":"20230920150244.171772-1-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230909125446.142715-1-sorganov@gmail.com","subject":"[PATCH v2 0/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-20T15:02:42Z","receivedAt":"2023-09-20T15:02:57Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This new convenience option requests full diff with respect to first\nparent, so that\n\n git log -d\n\nwill output diff with respect to first parent for every commit,\nuniversally, no matter how many parents the commit turns out to have.\n\nIt's implemented as pure synonym for\n\n --diff-merges=first-parent --patch\n\nThe first commit in the series tweaks diff-merges documentation a bit,\nand is valuable by itself. It's put here as '-d' implementation commit\ndepends on it in its documentation part.\n\nNote: the need for this new convenience option mostly emerged from\ndenial by the community of patches that modify '-m' behavior to imply\n'-p' as the rest of similar options (such as --cc) do.\n\nUpdates in v2:\n\n * Reordered documentation for diff-merges formats in accordance with\n Junio recommendation.\n\n * Removed clarification of surprising -m behavior due to controversy\n with Junio on how exactly it should look like.\n\nSergey Organov (2):\n diff-merges: improve --diff-merges documentation\n diff-merges: introduce '-d' option\n\n Documentation/diff-options.txt | 102 ++++++++++++++++++---------------\n Documentation/git-log.txt | 4 +-\n diff-merges.c | 3 +\n t/t4013-diff-various.sh | 8 +++\n 4 files changed, 70 insertions(+), 47 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex d773dafcb10a..19bb78ff6652 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -47,9 +47,6 @@ ifdef::git-log[]\n \tShow diffs for merge commits in the default format. This is\n \tsimilar to '--diff-merges=on' (which see) except `-m` will\n \tproduce no output unless `-p` is given as well.\n-+\n-Note: This option not implying `-p` is legacy feature that is\n-preserved for the sake of backward compatibility.\n \n -d::\n \tProduce diff with respect to first parent.\n@@ -96,16 +93,6 @@ separate::\n \tShow full diff with respect to each of parents.\n \tSeparate log entry and diff is generated for each parent.\n +\n-remerge, r::\n-\tRemerge two-parent merge commits to create a temporary tree\n-\tobject--potentially containing files with conflict markers\n-\tand such. A diff is then shown between that temporary tree\n-\tand the actual merge commit.\n-+\n-The output emitted when this option is used is subject to change, and\n-so is its interaction with other options (unless explicitly\n-documented).\n-+\n combined, c::\n \tShow differences from each of the parents to the merge\n \tresult simultaneously instead of showing pairwise diff between\n@@ -117,6 +104,16 @@ dense-combined, cc::\n \tby omitting uninteresting hunks whose contents in the parents\n \thave only two variants and the merge result picks one of them\n \twithout modification.\n++\n+remerge, r::\n+\tRemerge two-parent merge commits to create a temporary tree\n+\tobject--potentially containing files with conflict markers\n+\tand such. A diff is then shown between that temporary tree\n+\tand the actual merge commit.\n++\n+The output emitted when this option is used is subject to change, and\n+so is its interaction with other options (unless explicitly\n+documented).\n --\n \n --combined-all-paths::\n-- \n2.25.1\n\n"},{"id":"482070","messageId":"20230920150244.171772-3-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230920150244.171772-1-sorganov@gmail.com","subject":"[PATCH v2 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-20T15:02:44Z","receivedAt":"2023-09-20T15:02:59Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This option provides a shortcut to request diff with respect to first\nparent for any kind of commit, universally. It's implemented as pure\nsynonym for \"--diff-merges=first-parent --patch\".\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 4 ++++\n Documentation/git-log.txt | 2 +-\n diff-merges.c | 3 +++\n t/t4013-diff-various.sh | 8 ++++++++\n 4 files changed, 16 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 8035210c1418..19bb78ff6652 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -48,6 +48,10 @@ ifdef::git-log[]\n \tsimilar to '--diff-merges=on' (which see) except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n+-d::\n+\tProduce diff with respect to first parent.\n+\tShortcut for '--diff-merges=first-parent -p'.\n+\n -c::\n \tProduce combined diff output for merge commits.\n \tShortcut for '--diff-merges=combined -p'.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 9b7ec96e767a..59bd74a1a596 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -120,7 +120,7 @@ By default, `git log` does not generate any diff output. The options\n below can be used to show the changes made by each commit.\n \n Note that unless one of `--diff-merges` variants (including short\n-`-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n+`-d`, `-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\ndiff --git a/diff-merges.c b/diff-merges.c\nindex ec97616db1df..6eb72e6fc28a 100644\n--- a/diff-merges.c\n+++ b/diff-merges.c\n@@ -125,6 +125,9 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n \tif (!suppress_m_parsing && !strcmp(arg, \"-m\")) {\n \t\tset_to_default(revs);\n \t\trevs->merges_need_diff = 0;\n+\t} else if (!strcmp(arg, \"-d\")) {\n+\t\tset_first_parent(revs);\n+\t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"-c\")) {\n \t\tset_combined(revs);\n \t\trevs->merges_imply_patch = 1;\ndiff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\nindex 5de1d190759f..a07d6eb6dd97 100755\n--- a/t/t4013-diff-various.sh\n+++ b/t/t4013-diff-various.sh\n@@ -473,6 +473,14 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n \ttest_cmp expected actual\n '\n \n+test_expect_success 'log -d matches --diff-merges=1 -p' '\n+\tgit log --diff-merges=1 -p master >result &&\n+\tprocess_diffs result >expected &&\n+\tgit log -d master >result &&\n+\tprocess_diffs result >actual &&\n+\ttest_cmp expected actual\n+'\n+\n test_expect_success 'deny wrong log.diffMerges config' '\n \ttest_config log.diffMerges wrong-value &&\n \ttest_expect_code 128 git log\n-- \n2.25.1\n\n"},{"id":"482071","messageId":"20230920150244.171772-2-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230920150244.171772-1-sorganov@gmail.com","subject":"[PATCH v2 1/2] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-20T15:02:43Z","receivedAt":"2023-09-20T15:03:02Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"* Put descriptions of convenience shortcuts first, so they are the\n first things reader observes rather than lengthy detailed stuff.\n\n* Get rid of very long line containing all the --diff-merges formats\n by replacing them with , and putting each supported format\n on its own line.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 98 ++++++++++++++++++----------------\n Documentation/git-log.txt | 2 +-\n 2 files changed, 54 insertions(+), 46 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9f33f887711d..8035210c1418 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -43,66 +43,74 @@ endif::git-diff[]\n endif::git-format-patch[]\n \n ifdef::git-log[]\n---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n+-m::\n+\tShow diffs for merge commits in the default format. This is\n+\tsimilar to '--diff-merges=on' (which see) except `-m` will\n+\tproduce no output unless `-p` is given as well.\n+\n+-c::\n+\tProduce combined diff output for merge commits.\n+\tShortcut for '--diff-merges=combined -p'.\n+\n+--cc::\n+\tProduce dense combined diff output for merge commits.\n+\tShortcut for '--diff-merges=dense-combined -p'.\n+\n+--remerge-diff::\n+\tProduce diff against re-merge.\n+\tShortcut for '--diff-merges=remerge -p'.\n+\n --no-diff-merges::\n+\tSynonym for '--diff-merges=off'.\n+\n+--diff-merges=::\n \tSpecify diff format to be used for merge commits. Default is\n-\t{diff-merges-default} unless `--first-parent` is in use, in which case\n-\t`first-parent` is the default.\n+\t{diff-merges-default} unless `--first-parent` is in use, in\n+\twhich case `first-parent` is the default.\n +\n---diff-merges=(off|none):::\n---no-diff-merges:::\n+The following formats are supported:\n++\n+--\n+off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n +\n---diff-merges=on:::\n---diff-merges=m:::\n--m:::\n-\tThis option makes diff output for merge commits to be shown in\n-\tthe default format. `-m` will produce the output only if `-p`\n-\tis given as well. The default format could be changed using\n+on, m::\n+\tMake diff output for merge commits to be shown in the default\n+\tformat. The default format could be changed using\n \t`log.diffMerges` configuration parameter, which default value\n \tis `separate`.\n +\n---diff-merges=first-parent:::\n---diff-merges=1:::\n-\tThis option makes merge commits show the full diff with\n-\trespect to the first parent only.\n+first-parent, 1::\n+\tShow full diff with respect to first parent. This is the same\n+\tformat as `--patch` produces for non-merge commits.\n +\n---diff-merges=separate:::\n-\tThis makes merge commits show the full diff with respect to\n-\teach of the parents. Separate log entry and diff is generated\n-\tfor each parent.\n+separate::\n+\tShow full diff with respect to each of parents.\n+\tSeparate log entry and diff is generated for each parent.\n +\n---diff-merges=remerge:::\n---diff-merges=r:::\n---remerge-diff:::\n-\tWith this option, two-parent merge commits are remerged to\n-\tcreate a temporary tree object -- potentially containing files\n-\twith conflict markers and such. A diff is then shown between\n-\tthat temporary tree and the actual merge commit.\n+combined, c::\n+\tShow differences from each of the parents to the merge\n+\tresult simultaneously instead of showing pairwise diff between\n+\ta parent and the result one at a time. Furthermore, it lists\n+\tonly files which were modified from all parents.\n++\n+dense-combined, cc::\n+\tFurther compress output produced by `--diff-merges=combined`\n+\tby omitting uninteresting hunks whose contents in the parents\n+\thave only two variants and the merge result picks one of them\n+\twithout modification.\n++\n+remerge, r::\n+\tRemerge two-parent merge commits to create a temporary tree\n+\tobject--potentially containing files with conflict markers\n+\tand such. A diff is then shown between that temporary tree\n+\tand the actual merge commit.\n +\n The output emitted when this option is used is subject to change, and\n so is its interaction with other options (unless explicitly\n documented).\n-+\n---diff-merges=combined:::\n---diff-merges=c:::\n--c:::\n-\tWith this option, diff output for a merge commit shows the\n-\tdifferences from each of the parents to the merge result\n-\tsimultaneously instead of showing pairwise diff between a\n-\tparent and the result one at a time. Furthermore, it lists\n-\tonly files which were modified from all parents. `-c` implies\n-\t`-p`.\n-+\n---diff-merges=dense-combined:::\n---diff-merges=cc:::\n---cc:::\n-\tWith this option the output produced by\n-\t`--diff-merges=combined` is further compressed by omitting\n-\tuninteresting hunks whose contents in the parents have only\n-\ttwo variants and the merge result picks one of them without\n-\tmodification. `--cc` implies `-p`.\n+--\n \n --combined-all-paths::\n \tThis flag causes combined diffs (used for merge commits) to\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 2a66cf888074..9b7ec96e767a 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -124,7 +124,7 @@ Note that unless one of `--diff-merges` variants (including short\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\n-the default format.\n+the default format for merge commits.\n \n :git-log: 1\n :diff-merges-default: `off`\n-- \n2.25.1\n\n"},{"id":"482316","messageId":"xmqqjzsdps0h.fsf@gitster.g","threadId":"60213","inReplyTo":"87ttrudkw9.fsf@osv.gnss.ru","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-26T02:50:22Z","receivedAt":"2023-09-26T02:50:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> P.S. I also figure that maybe our divergence comes from the fact that I\n> consider merge commits to be primarily commits (introducing particular\n> set of changes, and then having reference to the source of the changes),\n> whereas you consider them primarily merges (joining two histories, and\n> then maybe some artificial changes that make merges \"evil\"). That's why\n> we often end up agreeing to disagree, as both these points of view seem\n> pretty valid.\n\nIt rarely is the case that two opposing world views are equally\nvalid, though.\n\nIf there were an option that forbids any comparison output from a\nsingle parent commit (say --ndfnm \"no-diff-for-non-merge\"), then\nthose with \"merges are the primary thing, single-parent commits on\nthe merged branches are implementation details\" worldview would be\ncommonly using \"--diff-merges=first-parent --patch --ndfnm\" and (1)\nviewing only the combined effect of merging side branches without\nseeing noise from individual commits whose effects are already shown\nin these merges, and (2) traversing the side branches as well, so\nthat merges from side-side branches into the side branches are\nviewable the same way as merges into the mainline.\n\nBut because no such option exists and nobody asked for such an\noption during the whole lifetime of the project, I highly doubt\nthat it is a valid world view with wide backing from the users.\n\nEven if it were a valid world view with wide backing, the\ncombination \"--diff-merges=first-parent --patch\" would be less than\nideal presentation for them (due to lack of \"--ndfnm\"). And as I\nalready said, it would not be useful without --first-parent\ntraversal for the worldview git has supported.\n\nThat is why I find it of dubious value to let short-and-sweet '-d'\nbe squatted by less than ideal \"--diff-merges=first-parent --patch\"\ncombination. Shorthands are scarse resources, and we want to be\ncareful before handing them out.\n\nThanks.\n\n\n"},{"id":"482333","messageId":"87bkdpl2yx.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqjzsdps0h.fsf@gitster.g","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-26T09:04:54Z","receivedAt":"2023-09-26T09:05:00Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> P.S. I also figure that maybe our divergence comes from the fact that I\n>> consider merge commits to be primarily commits (introducing particular\n>> set of changes, and then having reference to the source of the changes),\n>> whereas you consider them primarily merges (joining two histories, and\n>> then maybe some artificial changes that make merges \"evil\"). That's why\n>> we often end up agreeing to disagree, as both these points of view seem\n>> pretty valid.\n>\n> It rarely is the case that two opposing world views are equally\n> valid, though.\n\nYes. In this particular case the two are not opposing though, rather\northogonal, as they reflect the intrinsic dualism of the concept of\n\"merge commit\". Merge commit is both a new state, and history junction,\nneither of which is more or less valid or essential, and I use both\nviews myself, depending on situation.\n\nAn electron is both a particle and a wave, and one just uses its side\nthat is more convenient for explanation of the case in hand.\n\nI promote features that I routinely need in my workflows, yet respecting\nthe other side of the coin as well, even though I may rarely find this\nother side useful. I mean, for me, this -c/--cc (let alone -m) output is\nonly confusing, yet I won't be saying that it's somehow less valid than\nproposed -d.\n\n> If there were an option that forbids any comparison output from a\n> single parent commit (say --ndfnm \"no-diff-for-non-merge\"),\n> then those with \"merges are the primary thing, single-parent commits\n> on the merged branches are implementation details\" worldview would be\n> commonly using \"--diff-merges=first-parent --patch --ndfnm\" and (1)\n> viewing only the combined effect of merging side branches without\n> seeing noise from individual commits whose effects are already shown\n> in these merges, and (2) traversing the side branches as well, so that\n> merges from side-side branches into the side branches are viewable the\n> same way as merges into the mainline.\n\nNo need to ask for a new option, as the behavior you describe is already\nthere, and is spelled \"git log --diff-merges=first-parent\"\n(--diff-merges=1 for short).\n\n> But because no such option exists and nobody asked for such an\n> option during the whole lifetime of the project, I highly doubt\n> that it is a valid world view with wide backing from the users.\n\nYour concern above seems to be void, so this doesn't hold either.\n\nAs a side-note though, something like this has been asked recently, as\nwhat you describe by --ndfnm should in fact have been what --no-patch\ndoes, but surprisingly does not (please recall recent discussion of this\nissue).\n\n> Even if it were a valid world view with wide backing,\n\nApparently it is valid, otherwise there would be no need for diff to\nfirst parent at all, let alone \"git log --first-parent -p\" have used it\nby default.\n\n> the combination \"--diff-merges=first-parent --patch\" would be less\n> than ideal presentation for them (due to lack of \"--ndfnm\").\n\nFirst, as we figured above, --ndfnm is not needed, and second, me, being\none of \"them\", tries hard to convince you it is the best presentation\n\"them\" can get, while \"ideal\" simply never exists.\n\n> And as I already said, it would not be useful without --first-parent\n> traversal for the worldview git has supported.\n\nYes, you said it earlier in this thread, and as well I already explained\nhow it is useful without --first-parent.\n\n> That is why I find it of dubious value to let short-and-sweet '-d'\n> be squatted by less than ideal \"--diff-merges=first-parent --patch\"\n> combination.\n\nHopefully I do understand your concerns, yet I believe\n\"--diff-merges=first-parent --patch\" is way better for \"-d\" shortcut\nthan \"--first-parent --patch\", for the reasons I already explained\nearlier in this thread.\n\n> Shorthands are scarse resources, and we want to be careful before\n> handing them out.\n\nYep, agreed.\n\nI believe I carefully thought it over though, weighing all pros and\ncons, and thus -d fits nicely among -c and --cc, being yet another\nfrequently desired format for merges, plays nice with -p as well, and is\nvery mnemonic, giving us convenient, user-friendly, and consistent user\ninterface overall.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482349","messageId":"xmqqa5t8ooaj.fsf@gitster.g","threadId":"60213","inReplyTo":"87bkdpl2yx.fsf@osv.gnss.ru","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-26T17:08:20Z","receivedAt":"2023-09-26T17:08:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> No need to ask for a new option, as the behavior you describe is already\n> there, and is spelled \"git log --diff-merges=first-parent\"\n> (--diff-merges=1 for short).\n\nAh, that changes things. \n\nMaking \"--diff-merges=\" only about the presentation of merge\ncommits, requiring a separate \"-p\" for single-parent commits [*],\ndoes make the life for those in the \"merges are the only interesting\nthings\" camp a lot easier, exactly because the lack of \"-p\" can be\nused to say \"I am not interested in chanages by single-parent\ncommits\".\n\n\tSide note: I personally think it is a design mistake of\n\t--diff-merges= (e.g., --cc and --diff-merges=cc do not\n\tbehave the same way) but that is a different story, and it\n\tis way too late now anyway to \"fix\" or change.\n\nSo \"-d\" that stands for \"--diff-merges=first-parent -p\" makes the\nmore useful (to those who think \"merges are the only interesting\nthings\", which I do not belong to) \"--diff-merges=first-parent\"\n(without \"-p\") less useful. And the combination is not useful for\nthose of us who find individual patches plus tweaks by merges\n(either --cc or --remerge-diff) are the way to look at the history.\n\nI still do not think that we want to give a short-and-sweet single\nletter option for such a combination.\n\nThanks for clarification.\n"},{"id":"482356","messageId":"87o7hok8dx.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqa5t8ooaj.fsf@gitster.g","subject":"Re: [PATCH 2/2] diff-merges: introduce '-d' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-26T20:05:30Z","receivedAt":"2023-09-26T20:05:38Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> No need to ask for a new option, as the behavior you describe is already\n>> there, and is spelled \"git log --diff-merges=first-parent\"\n>> (--diff-merges=1 for short).\n>\n> Ah, that changes things.\n\nOnly a tiny bit, unfortunately, as I'm still struggling to finally\nconvince you (((\n\n>\n> Making \"--diff-merges=\" only about the presentation of merge\n> commits, requiring a separate \"-p\" for single-parent commits [*],\n> does make the life for those in the \"merges are the only interesting\n> things\" camp a lot easier, exactly because the lack of \"-p\" can be\n> used to say \"I am not interested in chanages by single-parent\n> commits\".\n>\n> \tSide note: I personally think it is a design mistake of\n> \t--diff-merges= (e.g., --cc and --diff-merges=cc do not\n> \tbehave the same way) but that is a different story, and it\n> \tis way too late now anyway to \"fix\" or change.\n\n Side note: This has been considered and agreed upon when\n --diff-merges= options were introduced, and as far as I recall,\n at that time you explicitly agreed it might be useful to be able\n to get output only for merge commits.\n\n --cc is a simple alias for \"--diff-merges=cc --patch\" nowadays,\n so yes, they do behave differently, and that's by design. Dunno\n see any design mistake here, as we get all useful variations of\n behavior with a straightforward design, more frequent use-cases\n served by shorter options. Looks fine.\n\n>\n> So \"-d\" that stands for \"--diff-merges=first-parent -p\" makes the\n> more useful (to those who think \"merges are the only interesting\n> things\", which I do not belong to) \"--diff-merges=first-parent\"\n> (without \"-p\") less useful. And the combination is not useful for\n> those of us who find individual patches plus tweaks by merges\n> (either --cc or --remerge-diff) are the way to look at the history.\n\nYes, you have your --cc, -c, and --remerge-diff (that I'd call something\nlike --rd probably, but anyway). Could I please have my simple,\nstraightforward, mnemonic, and terribly useful \"-d\" as well?\n\nIn other words, will I finally be faced with \"if you need it, do it\nyourself\" argument? ;)\n\n> I still do not think that we want to give a short-and-sweet single\n> letter option for such a combination.\n\nI have very simple desire: convenient way to tell Git to show me diff to\nthe first parent for merge commits, as that's the thing I need 99% of\ntimes when I do request diff output at all. That's exactly what I'd have\nseen as changes when I was about to commit the merge as well, similar to\nany other commit. It's so natural that I can't figure why it looks so\ndamn rare or unusual to you, and that it makes you argue so hard against\n-d, especially when -p, -c, --cc, or even -m, are already there?\n\nI do sympathize your desire to be careful about short options, but what\nreservation for \"-d\" do you still have in mind? It seems that it was\njust waiting for me to come and finally bring it to life with the best\nmeaning possible. How long should I wait for it to remain unused to\nfinally be able to make use of it?\n\nThanks,\n-- Sergey Organov\n"},{"id":"482670","messageId":"20231004214558.210339-3-sorganov@gmail.com","threadId":"60213","inReplyTo":"20231004214558.210339-1-sorganov@gmail.com","subject":"[PATCH v3 2/3] diff-merges: introduce '--dd' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-04T21:45:57Z","receivedAt":"2023-10-04T21:46:32Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This option provides a shortcut to request diff with respect to first\nparent for any kind of commit, universally. It's implemented as pure\nsynonym for \"--diff-merges=first-parent --patch\".\n\nNOTE: originally proposed as '-d', and renamed to '--dd' due to Junio\nrequest to keep \"short-and-sweet\" '-d' reserved for other uses.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 5 +++++\n Documentation/git-log.txt | 2 +-\n diff-merges.c | 3 +++\n t/t4013-diff-various.sh | 8 ++++++++\n 4 files changed, 17 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 8035210c1418..f80d493dd4c8 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -56,6 +56,11 @@ ifdef::git-log[]\n \tProduce dense combined diff output for merge commits.\n \tShortcut for '--diff-merges=dense-combined -p'.\n \n+--dd::\n+\tProduce diff with respect to first parent for both merge and\n+\tregular commits.\n+\tShortcut for '--diff-merges=first-parent -p'.\n+\n --remerge-diff::\n \tProduce diff against re-merge.\n \tShortcut for '--diff-merges=remerge -p'.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 9b7ec96e767a..579682172fe4 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -120,7 +120,7 @@ By default, `git log` does not generate any diff output. The options\n below can be used to show the changes made by each commit.\n \n Note that unless one of `--diff-merges` variants (including short\n-`-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n+`-m`, `-c`, `--cc`, and `--dd` options) is explicitly given, merge commits\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\ndiff --git a/diff-merges.c b/diff-merges.c\nindex ec97616db1df..45507588a279 100644\n--- a/diff-merges.c\n+++ b/diff-merges.c\n@@ -131,6 +131,9 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n \t} else if (!strcmp(arg, \"--cc\")) {\n \t\tset_dense_combined(revs);\n \t\trevs->merges_imply_patch = 1;\n+\t} else if (!strcmp(arg, \"--dd\")) {\n+\t\tset_first_parent(revs);\n+\t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"--remerge-diff\")) {\n \t\tset_remerge_diff(revs);\n \t\trevs->merges_imply_patch = 1;\ndiff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\nindex 5de1d190759f..4b474808311e 100755\n--- a/t/t4013-diff-various.sh\n+++ b/t/t4013-diff-various.sh\n@@ -473,6 +473,14 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n \ttest_cmp expected actual\n '\n \n+test_expect_success 'log --dd matches --diff-merges=1 -p' '\n+\tgit log --diff-merges=1 -p master >result &&\n+\tprocess_diffs result >expected &&\n+\tgit log --dd master >result &&\n+\tprocess_diffs result >actual &&\n+\ttest_cmp expected actual\n+'\n+\n test_expect_success 'deny wrong log.diffMerges config' '\n \ttest_config log.diffMerges wrong-value &&\n \ttest_expect_code 128 git log\n-- \n2.25.1\n\n"},{"id":"482671","messageId":"20231004214558.210339-2-sorganov@gmail.com","threadId":"60213","inReplyTo":"20231004214558.210339-1-sorganov@gmail.com","subject":"[PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-04T21:45:56Z","receivedAt":"2023-10-04T21:46:32Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"* Put descriptions of convenience shortcuts first, so they are the\n first things reader observes rather than lengthy detailed stuff.\n\n* Get rid of very long line containing all the --diff-merges formats\n by replacing them with , and putting each supported format\n on its own line.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 98 ++++++++++++++++++----------------\n Documentation/git-log.txt | 2 +-\n 2 files changed, 54 insertions(+), 46 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9f33f887711d..8035210c1418 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -43,66 +43,74 @@ endif::git-diff[]\n endif::git-format-patch[]\n \n ifdef::git-log[]\n---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n+-m::\n+\tShow diffs for merge commits in the default format. This is\n+\tsimilar to '--diff-merges=on' (which see) except `-m` will\n+\tproduce no output unless `-p` is given as well.\n+\n+-c::\n+\tProduce combined diff output for merge commits.\n+\tShortcut for '--diff-merges=combined -p'.\n+\n+--cc::\n+\tProduce dense combined diff output for merge commits.\n+\tShortcut for '--diff-merges=dense-combined -p'.\n+\n+--remerge-diff::\n+\tProduce diff against re-merge.\n+\tShortcut for '--diff-merges=remerge -p'.\n+\n --no-diff-merges::\n+\tSynonym for '--diff-merges=off'.\n+\n+--diff-merges=::\n \tSpecify diff format to be used for merge commits. Default is\n-\t{diff-merges-default} unless `--first-parent` is in use, in which case\n-\t`first-parent` is the default.\n+\t{diff-merges-default} unless `--first-parent` is in use, in\n+\twhich case `first-parent` is the default.\n +\n---diff-merges=(off|none):::\n---no-diff-merges:::\n+The following formats are supported:\n++\n+--\n+off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n +\n---diff-merges=on:::\n---diff-merges=m:::\n--m:::\n-\tThis option makes diff output for merge commits to be shown in\n-\tthe default format. `-m` will produce the output only if `-p`\n-\tis given as well. The default format could be changed using\n+on, m::\n+\tMake diff output for merge commits to be shown in the default\n+\tformat. The default format could be changed using\n \t`log.diffMerges` configuration parameter, which default value\n \tis `separate`.\n +\n---diff-merges=first-parent:::\n---diff-merges=1:::\n-\tThis option makes merge commits show the full diff with\n-\trespect to the first parent only.\n+first-parent, 1::\n+\tShow full diff with respect to first parent. This is the same\n+\tformat as `--patch` produces for non-merge commits.\n +\n---diff-merges=separate:::\n-\tThis makes merge commits show the full diff with respect to\n-\teach of the parents. Separate log entry and diff is generated\n-\tfor each parent.\n+separate::\n+\tShow full diff with respect to each of parents.\n+\tSeparate log entry and diff is generated for each parent.\n +\n---diff-merges=remerge:::\n---diff-merges=r:::\n---remerge-diff:::\n-\tWith this option, two-parent merge commits are remerged to\n-\tcreate a temporary tree object -- potentially containing files\n-\twith conflict markers and such. A diff is then shown between\n-\tthat temporary tree and the actual merge commit.\n+combined, c::\n+\tShow differences from each of the parents to the merge\n+\tresult simultaneously instead of showing pairwise diff between\n+\ta parent and the result one at a time. Furthermore, it lists\n+\tonly files which were modified from all parents.\n++\n+dense-combined, cc::\n+\tFurther compress output produced by `--diff-merges=combined`\n+\tby omitting uninteresting hunks whose contents in the parents\n+\thave only two variants and the merge result picks one of them\n+\twithout modification.\n++\n+remerge, r::\n+\tRemerge two-parent merge commits to create a temporary tree\n+\tobject--potentially containing files with conflict markers\n+\tand such. A diff is then shown between that temporary tree\n+\tand the actual merge commit.\n +\n The output emitted when this option is used is subject to change, and\n so is its interaction with other options (unless explicitly\n documented).\n-+\n---diff-merges=combined:::\n---diff-merges=c:::\n--c:::\n-\tWith this option, diff output for a merge commit shows the\n-\tdifferences from each of the parents to the merge result\n-\tsimultaneously instead of showing pairwise diff between a\n-\tparent and the result one at a time. Furthermore, it lists\n-\tonly files which were modified from all parents. `-c` implies\n-\t`-p`.\n-+\n---diff-merges=dense-combined:::\n---diff-merges=cc:::\n---cc:::\n-\tWith this option the output produced by\n-\t`--diff-merges=combined` is further compressed by omitting\n-\tuninteresting hunks whose contents in the parents have only\n-\ttwo variants and the merge result picks one of them without\n-\tmodification. `--cc` implies `-p`.\n+--\n \n --combined-all-paths::\n \tThis flag causes combined diffs (used for merge commits) to\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 2a66cf888074..9b7ec96e767a 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -124,7 +124,7 @@ Note that unless one of `--diff-merges` variants (including short\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\n-the default format.\n+the default format for merge commits.\n \n :git-log: 1\n :diff-merges-default: `off`\n-- \n2.25.1\n\n"},{"id":"482673","messageId":"20231004214558.210339-4-sorganov@gmail.com","threadId":"60213","inReplyTo":"20231004214558.210339-1-sorganov@gmail.com","subject":"[PATCH v3 3/3] completion: complete '--dd'","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-04T21:45:58Z","receivedAt":"2023-10-04T21:46:32Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"'--dd' only makes sense for 'git log' and 'git show', so add it to\n__git_log_show_options which is referenced in the completion for these\ntwo commands.\n\nSigned-off-by: Sergey Organov \n---\n contrib/completion/git-completion.bash | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 133ec92bfae7..ca4fa39f3ff8 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -2042,7 +2042,7 @@ __git_log_shortlog_options=\"\n \"\n # Options accepted by log and show\n __git_log_show_options=\"\n-\t--diff-merges --diff-merges= --no-diff-merges --remerge-diff\n+\t--diff-merges --diff-merges= --no-diff-merges --dd --remerge-diff\n \"\n \n __git_diff_merges_opts=\"off none on first-parent 1 separate m combined c dense-combined cc remerge r\"\n-- \n2.25.1\n\n"},{"id":"482672","messageId":"20231004214558.210339-1-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230909125446.142715-1-sorganov@gmail.com","subject":"[PATCH v3 0/3] diff-merges: introduce '--dd' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-04T21:45:55Z","receivedAt":"2023-10-04T21:46:33Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This new convenience option requests full diff with respect to first\nparent, so that\n\n git log --dd\n\nwill output diff with respect to first parent for every commit,\nuniversally, no matter how many parents the commit turns out to have.\n\n'--dd' is implemented as pure synonym for \"--diff-merges=first-parent\n--patch\".\n\nThe first commit in the series tweaks diff-merges documentation a bit,\nand is valuable by itself. It's put here as '--dd' implementation\ncommit depends on it in its documentation part.\n\nNote: the need for this new convenience option mostly emerged from\ndenial by the community of patches that modify '-m' behavior to imply\n'-p' as the rest of similar options (such as --cc) do. So, basically,\n'--dd' is what '-m' should have been to be more useful.\n\nUpdates in v3:\n\n * Option renamed from '-d' to '--dd' due to Junio overpowering\n request to keep short-and-sweet '-d' reserved for another (yet\n unspecified) use.\n\n * Added completion of '--dd' to git-completion.bash.\n\nUpdates in v2:\n\n * Reordered documentation for diff-merges formats in accordance with\n Junio recommendation.\n\n * Removed clarification of surprising -m behavior due to controversy\n with Junio on how exactly it should look like.\n\nSergey Organov (3):\n diff-merges: improve --diff-merges documentation\n diff-merges: introduce '--dd' option\n completion: complete '--dd'\n\n Documentation/diff-options.txt | 103 ++++++++++++++-----------\n Documentation/git-log.txt | 4 +-\n contrib/completion/git-completion.bash | 2 +-\n diff-merges.c | 3 +\n t/t4013-diff-various.sh | 8 ++\n 5 files changed, 72 insertions(+), 48 deletions(-)\n\nInterdiff against v2:\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 19bb78ff6652..f80d493dd4c8 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -48,10 +48,6 @@ ifdef::git-log[]\n \tsimilar to '--diff-merges=on' (which see) except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n--d::\n-\tProduce diff with respect to first parent.\n-\tShortcut for '--diff-merges=first-parent -p'.\n-\n -c::\n \tProduce combined diff output for merge commits.\n \tShortcut for '--diff-merges=combined -p'.\n@@ -60,6 +56,11 @@ ifdef::git-log[]\n \tProduce dense combined diff output for merge commits.\n \tShortcut for '--diff-merges=dense-combined -p'.\n \n+--dd::\n+\tProduce diff with respect to first parent for both merge and\n+\tregular commits.\n+\tShortcut for '--diff-merges=first-parent -p'.\n+\n --remerge-diff::\n \tProduce diff against re-merge.\n \tShortcut for '--diff-merges=remerge -p'.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 59bd74a1a596..579682172fe4 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -120,7 +120,7 @@ By default, `git log` does not generate any diff output. The options\n below can be used to show the changes made by each commit.\n \n Note that unless one of `--diff-merges` variants (including short\n-`-d`, `-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n+`-m`, `-c`, `--cc`, and `--dd` options) is explicitly given, merge commits\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 133ec92bfae7..ca4fa39f3ff8 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -2042,7 +2042,7 @@ __git_log_shortlog_options=\"\n \"\n # Options accepted by log and show\n __git_log_show_options=\"\n-\t--diff-merges --diff-merges= --no-diff-merges --remerge-diff\n+\t--diff-merges --diff-merges= --no-diff-merges --dd --remerge-diff\n \"\n \n __git_diff_merges_opts=\"off none on first-parent 1 separate m combined c dense-combined cc remerge r\"\ndiff --git a/diff-merges.c b/diff-merges.c\nindex 6eb72e6fc28a..45507588a279 100644\n--- a/diff-merges.c\n+++ b/diff-merges.c\n@@ -125,15 +125,15 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n \tif (!suppress_m_parsing && !strcmp(arg, \"-m\")) {\n \t\tset_to_default(revs);\n \t\trevs->merges_need_diff = 0;\n-\t} else if (!strcmp(arg, \"-d\")) {\n-\t\tset_first_parent(revs);\n-\t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"-c\")) {\n \t\tset_combined(revs);\n \t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"--cc\")) {\n \t\tset_dense_combined(revs);\n \t\trevs->merges_imply_patch = 1;\n+\t} else if (!strcmp(arg, \"--dd\")) {\n+\t\tset_first_parent(revs);\n+\t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"--remerge-diff\")) {\n \t\tset_remerge_diff(revs);\n \t\trevs->merges_imply_patch = 1;\ndiff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\nindex a07d6eb6dd97..4b474808311e 100755\n--- a/t/t4013-diff-various.sh\n+++ b/t/t4013-diff-various.sh\n@@ -473,10 +473,10 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n \ttest_cmp expected actual\n '\n \n-test_expect_success 'log -d matches --diff-merges=1 -p' '\n+test_expect_success 'log --dd matches --diff-merges=1 -p' '\n \tgit log --diff-merges=1 -p master >result &&\n \tprocess_diffs result >expected &&\n-\tgit log -d master >result &&\n+\tgit log --dd master >result &&\n \tprocess_diffs result >actual &&\n \ttest_cmp expected actual\n '\n-- \n2.25.1\n\n"},{"id":"482674","messageId":"CAPig+cT63L2+XmDRKw4Pc+iDmUL+UFcyummOcOtS+3wYaNbFvg@mail.gmail.com","threadId":"60213","inReplyTo":"20231004214558.210339-2-sorganov@gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-10-04T22:02:26Z","receivedAt":"2023-10-04T22:02:41Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Oct 4, 2023 at 5:51 PM Sergey Organov wrote:\n> * Put descriptions of convenience shortcuts first, so they are the\n> first things reader observes rather than lengthy detailed stuff.\n>\n> * Get rid of very long line containing all the --diff-merges formats\n> by replacing them with , and putting each supported format\n> on its own line.\n>\n> Signed-off-by: Sergey Organov \n> ---\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> @@ -43,66 +43,74 @@ endif::git-diff[]\n> +-m::\n> + Show diffs for merge commits in the default format. This is\n> + similar to '--diff-merges=on' (which see) except `-m` will\n> + produce no output unless `-p` is given as well.\n\nI'm having difficulty grasping the parenthetical \"(which see)\" comment.\n"},{"id":"482675","messageId":"87r0madoji.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"CAPig+cT63L2+XmDRKw4Pc+iDmUL+UFcyummOcOtS+3wYaNbFvg@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-04T22:13:21Z","receivedAt":"2023-10-04T22:14:57Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Eric Sunshine writes:\n\n> On Wed, Oct 4, 2023 at 5:51 PM Sergey Organov wrote:\n>> * Put descriptions of convenience shortcuts first, so they are the\n>> first things reader observes rather than lengthy detailed stuff.\n>>\n>> * Get rid of very long line containing all the --diff-merges formats\n>> by replacing them with , and putting each supported format\n>> on its own line.\n>>\n>> Signed-off-by: Sergey Organov \n>> ---\n>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n>> @@ -43,66 +43,74 @@ endif::git-diff[]\n>> +-m::\n>> + Show diffs for merge commits in the default format. This is\n>> + similar to '--diff-merges=on' (which see) except `-m` will\n>> + produce no output unless `-p` is given as well.\n>\n> I'm having difficulty grasping the parenthetical \"(which see)\" comment.\n\nI believe it's translated full form of q.v., see:\n\nhttps://en.wikipedia.org/wiki/List_of_Latin_abbreviations\n\n\"q.v.\n quod vide\n \"which see\"\n\nImperative, used after a term or phrase that should be looked up\nelsewhere in the current document or book.\"\n\nHTH,\n-- Sergey Organov\n"},{"id":"482718","messageId":"xmqqcyxshizq.fsf@gitster.g","threadId":"60213","inReplyTo":"CAPig+cT63L2+XmDRKw4Pc+iDmUL+UFcyummOcOtS+3wYaNbFvg@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-05T21:11:53Z","receivedAt":"2023-10-05T21:11:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n>> @@ -43,66 +43,74 @@ endif::git-diff[]\n>> +-m::\n>> + Show diffs for merge commits in the default format. This is\n>> + similar to '--diff-merges=on' (which see) except `-m` will\n>> + produce no output unless `-p` is given as well.\n>\n> I'm having difficulty grasping the parenthetical \"(which see)\" comment.\n\nI am, too. I know what it means when written in the more common\nLatin abbreviation (q.v.), but I suspect it may be rare to spell it\nin English like this. I found\n\nhttps://writingcenter.unc.edu/tips-and-tools/latin-terms-and-abbreviations/\n\nthat starts its explanation with this:\n\n The abbreviation q.v. stands for quod vide, which translates\n literally as “which see,” although in practice it mea\n something more like “for which see elsewhere.\n\nand it goes on to say:\n\n The reader is expected to know how to locate this information\n without further assistance. Since there is always the\n possibility that the reader won’t be able to find the\n information cited by q.v., it’s better to use a simple English\n phrase such as “for more on this topic, see pages 72-3” or\n “a detailed definition appears on page 16.” Such phrases are\n immediately comprehensible to the reader (who may not even know\n what q.v. means) and remove any ambiguity about where\n additional information is located.\n\nwhich only applies halfway to this example, as with the text before\nit makes it very clear for readers that they need to learn about\n\"--diff-merges=on\". It is so clear to the point that the only\neffect \"(which see)\" here has is to waste bytes and confuses\nreaders, I am afraid.\n\n"},{"id":"482719","messageId":"xmqq34yog3ux.fsf@gitster.g","threadId":"60213","inReplyTo":"20231004214558.210339-2-sorganov@gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-05T21:24:06Z","receivedAt":"2023-10-05T21:24:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n> +-m::\n> +\tShow diffs for merge commits in the default format. This is\n> +\tsimilar to '--diff-merges=on' (which see) except `-m` will\n> +\tproduce no output unless `-p` is given as well.\n\nI think the sentence reads better without the translated (q.v.) that\nconfused Eric.\n\n> +-c::\n> +\tProduce combined diff output for merge commits.\n> +\tShortcut for '--diff-merges=combined -p'.\n> +\n> +--cc::\n> +\tProduce dense combined diff output for merge commits.\n> +\tShortcut for '--diff-merges=dense-combined -p'.\n\nGood.\n\n> +--remerge-diff::\n> +\tProduce diff against re-merge.\n> +\tShortcut for '--diff-merges=remerge -p'.\n\nI suspect that many people do not get what \"re-merge\" in \"against\nre-merge\" really is. As \"combined diff\" and \"dense combined diff\"\nare not explained in the previous two entries either, and expect the\nreaders to read the real description (which more or less matches\nwhat the original description for \"-c\" and \"--cc\" had, which is\ngood), it would be better to say \"Produce remerge-diff output for\nmerge commits.\" here, too. It makes it consistent, and \"for merge\ncommits\" makes it clear the \"magic\" does not apply to regular\ncommits (which the above entries for \"-c\" and \"--cc\" do, which is\nvery good).\n\n> --no-diff-merges::\n> +\tSynonym for '--diff-merges=off'.\n> +\n> +--diff-merges=::\n> \tSpecify diff format to be used for merge commits. Default is\n> -\t{diff-merges-default} unless `--first-parent` is in use, in which case\n> -\t`first-parent` is the default.\n> +\t{diff-merges-default} unless `--first-parent` is in use, in\n> +\twhich case `first-parent` is the default.\n\nThis reads well.\n\nIn the longer term, \"--diff-merge=first-parent\" that is used without\nfirst-parent traversal should be discouraged and be deprecated, I\nthink, but that is a separate story [*].\n\n> ---diff-merges=(off|none):::\n> ---no-diff-merges:::\n> +The following formats are supported:\n> ++\n> +--\n> +off, none::\n> \tDisable output of diffs for merge commits. Useful to override\n> \timplied value.\n> +\n> ---diff-merges=on:::\n> ---diff-merges=m:::\n> --m:::\n> -\tThis option makes diff output for merge commits to be shown in\n> -\tthe default format. `-m` will produce the output only if `-p`\n> -\tis given as well. The default format could be changed using\n> +on, m::\n> +\tMake diff output for merge commits to be shown in the default\n> +\tformat. The default format could be changed using\n> \t`log.diffMerges` configuration parameter, which default value\n> \tis `separate`.\n\nThe original is already wrong so these are not problems this patch\nintroduces, but\n\n - \"configuration variable\" is how we refer to these entities.\n - \"which default value\" -> \"whose default value\".\n\n> ---diff-merges=first-parent:::\n> ---diff-merges=1:::\n> -\tThis option makes merge commits show the full diff with\n> -\trespect to the first parent only.\n> +first-parent, 1::\n> +\tShow full diff with respect to first parent. This is the same\n> +\tformat as `--patch` produces for non-merge commits.\n> +\n\nYes, this is the same output as `-p`, as if parents other than the\nfirst parent of the merge commit did not exist.\n\nThis was inherited from the original elsewhere, but it makes it\nunnecessary confusing to say \"full diff\" here and in the next one.\n\n Show `--patch` output with respoect to the first parent for a\n merge commit, as if the other parents did not exist.\n\nperhaps?\n\n> +separate::\n> +\tShow full diff with respect to each of parents.\n> +\tSeparate log entry and diff is generated for each parent.\n\nIn the early days of Git before -c/--cc were invented, we explained\nthis mode as \"pairwise comparison\", and the phrase \"pairwise\" still\nmay be the best one to describe the behaviour here. In fact, we see\nin the updated description of combined below the exact phrase is used\nto refer to this oldest output format.\n\n Show the `--patch` output pairwise, together with the commit\n header, repeated for each parent for a merge commit.\n\nor something, perhaps. I added \"repeated\" here to make the contrast\nwith \"simultaneously\" stand out.\n\n> +combined, c::\n> +\tShow differences from each of the parents to the merge\n> +\tresult simultaneously instead of showing pairwise diff between\n> +\ta parent and the result one at a time. Furthermore, it lists\n> +\tonly files which were modified from all parents.\n> ++\n> +dense-combined, cc::\n> +\tFurther compress output produced by `--diff-merges=combined`\n> +\tby omitting uninteresting hunks whose contents in the parents\n> +\thave only two variants and the merge result picks one of them\n> +\twithout modification.\n> ++\n> +remerge, r::\n> +\tRemerge two-parent merge commits to create a temporary tree\n> +\tobject--potentially containing files with conflict markers\n> +\tand such. A diff is then shown between that temporary tree\n> +\tand the actual merge commit.\n\nThe original says \"two-parent merge comimts are remerged\" so it is\nnot a failure of this patch, but the first verb \"Remerge\" sounds\nunnecessarily unfriendly to the readers.\n\n\tFor a two-parent merge commit, a merge of these two commits\n\tis retried to create a temporary tree object, potentially\n\tcontaining files with conflict markers. A `--patch` output\n\tthen is shown between ...\n\nwould be easier to follow and more faithful to the original\ndescription added by db757e8b (show, log: provide a --remerge-diff\ncapability, 2022-02-02).\n\nEither way, it makes readers wonder what happens to merges with more\nthan 2 parents (octopus merges). It is not a new problem and this\ntopic should not attempt to fix it.\n\nLooks very good otherwise. Let me read on.\n\nThanks.\n\n\n[Footnote]\n\n* When a project allows fast-forward merges, something like this can\n happen (and Git was _designed_ to allow and even encourage it)\n\n - Linus pulls from Sergey and sees merge conflicts that are very\n messy. Sergey is asked to resolve the conflict, as Linus knows\n Sergey understands the changes he is asking Linus to pull much\n better than Linus does.\n\n - Sergey does \"git pull origin\" that would give the same set of\n conflicts Linus saw, perhaps ours/theirs sides swapped, resolves\n the conflicts, and comits the merge result. He may even add a\n few other improvements on top (or may not). He tells Linus that\n his tree is ready to be pulled again.\n\n - Linus pulls from Sergey again. This time it is fast-forward,\n without an extra merge commit that records the Linus's previous\n tip as the first parent and Sergey's work as the second parent.\n\n - Linus continues working from here.\n\n In such a workflow, merges are nothing more than \"combining\n multiple histories together\" and the first parenthood is NOT\n inherently special among parents at all. The original \"-m -p\"\n (aka \"pairwise diff\") output reflects this world view and ensures\n that all parents are shown more or less as equals (yes, the first\n parent diff is shown first before the other parents, but you\n cannot avoid it when outputting to a single dimension medium).\n\n This world view was the only world view Git supported, until I\n added the \"--first-parent\" traversal in 0053e902 (git-log\n --first-parent: show only the first parent log, 2007-03-13).\n\n With the \"--first-parent\", with \"--no-ff\" option to \"git merge\", a\n different world view becomes possible. A merge is not merely\n combining multiple histories, which are equals. It is bringing\n work done on a side branch into the trunk. To see the overview of\n the history, \"git log --first-parent\" would give the outline,\n which would be full of merges from side branches, each of which\n can be seen as summarizing the work done on the side branch that\n was merged, and it may occasionally have single-parent commits\n that are hotfixes or trivial clean-ups or project administrivia\n commits. With \"-p\", \"git log\" would show the changes the work\n done on a side branch as a single unit for a merge, and individual\n commits if they are single-parent. The life is good.\n\n It all breaks down if the \"diff against the first parent\" is done\n on a merge that is not bringing the work on a side branch in to\n the trunk. The merge done in the second step Sergey did for Linus\n in the above example will have his work on the history leading to\n its first parent, and from the overall project's point of view,\n the second parent is the tip of the history of the trunk. Showing\n first-parent diff for a merge that was *not* discovered via the\n first-parent traversal would show such a meaningless patch. This\n is an illustration of the fallout from mixing two incompatible\n world views together, \"--diff-merges=first-parent\" wants to work\n in a world where the first-parent is special among parents, but\n traversal without \"--first-parent\" wants to treat all the branches\n equally.\n\n All the other s accepted by the \"--diff-merges=\"\n option are symmetrical and they work equally well when in a\n history of a project that considers the first-parenthood special\n (i.e. work on a side branch is brought into the trunk history) or\n in a history with merges whose parent order should not matter, so\n unlike \"--diff-merges=first-parent\", it makes sense to apply them\n with or without first-parent traversal. It however is not true\n for the \"--diff-merges=first-parent\" variant, which is asymmetric.\n\n And that is why I think use of \"--diff-merges=first-parent\"\n without \"--first-parent\" traversal is a bad thing to teach users\n to use.\n"},{"id":"482724","messageId":"xmqqlecgeoan.fsf@gitster.g","threadId":"60213","inReplyTo":"20231004214558.210339-4-sorganov@gmail.com","subject":"Re: [PATCH v3 3/3] completion: complete '--dd'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-05T21:45:36Z","receivedAt":"2023-10-05T21:45:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> '--dd' only makes sense for 'git log' and 'git show', so add it to\n> __git_log_show_options which is referenced in the completion for these\n> two commands.\n>\n> Signed-off-by: Sergey Organov \n> ---\n> contrib/completion/git-completion.bash | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\n> index 133ec92bfae7..ca4fa39f3ff8 100644\n> --- a/contrib/completion/git-completion.bash\n> +++ b/contrib/completion/git-completion.bash\n> @@ -2042,7 +2042,7 @@ __git_log_shortlog_options=\"\n> \"\n> # Options accepted by log and show\n> __git_log_show_options=\"\n> -\t--diff-merges --diff-merges= --no-diff-merges --remerge-diff\n> +\t--diff-merges --diff-merges= --no-diff-merges --dd --remerge-diff\n> \"\n> \n> __git_diff_merges_opts=\"off none on first-parent 1 separate m combined c dense-combined cc remerge r\"\n\nQuite straight-forward. I am kind of surprised that we do not have\nto list \"--cc\" here. Perhaps it is so short and common that people\ndo not need completion help?\n\nBut that is not a new problem caused by this series, so it is OK.\n\nUnless \"--cc\" gets completed without being listed here, using some\nautomation like the \"--git-completion-helper\" option, in which case\nwe may want to see if we can remove all of the above and complete\nthem the same way as \"--cc\" gets completed. I didn't check.\n\nThanks.\n\n"},{"id":"482725","messageId":"xmqqr0m8eoaq.fsf@gitster.g","threadId":"60213","inReplyTo":"20231004214558.210339-3-sorganov@gmail.com","subject":"Re: [PATCH v3 2/3] diff-merges: introduce '--dd' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-05T21:45:33Z","receivedAt":"2023-10-05T21:45:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> This option provides a shortcut to request diff with respect to first\n> parent for any kind of commit, universally. It's implemented as pure\n> synonym for \"--diff-merges=first-parent --patch\".\n\nThat explains what the patch does, but it does not tell us why it is\nuseful [*].\n\n> NOTE: originally proposed as '-d', and renamed to '--dd' due to Junio\n> request to keep \"short-and-sweet\" '-d' reserved for other uses.\n\nThe note is not grammatical, and more importantly, readers of \"git\nlog\" 6 months down the road would not care. I'd rather not see it\nin the proposed log message. It is suitable material to place after\nthe three-dash line, or in the cover letter for the iteration.\n\n> diff --git a/diff-merges.c b/diff-merges.c\n> index ec97616db1df..45507588a279 100644\n> --- a/diff-merges.c\n> +++ b/diff-merges.c\n> @@ -131,6 +131,9 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n> \t} else if (!strcmp(arg, \"--cc\")) {\n> \t\tset_dense_combined(revs);\n> \t\trevs->merges_imply_patch = 1;\n> +\t} else if (!strcmp(arg, \"--dd\")) {\n> +\t\tset_first_parent(revs);\n> +\t\trevs->merges_imply_patch = 1;\n\nQuite straight-forward as expected. I do not think \"--dd\" clicks\nfor many people as \"first parent diffs all over\", though.\n\n> \t} else if (!strcmp(arg, \"--remerge-diff\")) {\n> \t\tset_remerge_diff(revs);\n> \t\trevs->merges_imply_patch = 1;\n> diff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\n> index 5de1d190759f..4b474808311e 100755\n> --- a/t/t4013-diff-various.sh\n> +++ b/t/t4013-diff-various.sh\n> @@ -473,6 +473,14 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n> \ttest_cmp expected actual\n> '\n> \n> +test_expect_success 'log --dd matches --diff-merges=1 -p' '\n> +\tgit log --diff-merges=1 -p master >result &&\n> +\tprocess_diffs result >expected &&\n> +\tgit log --dd master >result &&\n> +\tprocess_diffs result >actual &&\n> +\ttest_cmp expected actual\n> +'\n> +\n> test_expect_success 'deny wrong log.diffMerges config' '\n> \ttest_config log.diffMerges wrong-value &&\n> \ttest_expect_code 128 git log\n\nLooking good.\n\nThanks.\n\n\n[Footnote]\n\n* As I said elsewhere, I do not think it is a good idea to encourage\n users' to adopt a screwed-up worldview in which first parent is\n special but not special, and does the wrong thing for reverse\n merges. If the option were short-hand for \"--first-parent -p\",\n at least I would be more sympathetic.\n"},{"id":"482739","messageId":"CABPp-BFsrt0zS3NHsVAyOSW6vGioe8Z-iN2M3_JNBpP2fWVq9g@mail.gmail.com","threadId":"60213","inReplyTo":"xmqq34yog3ux.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-10-06T14:41:51Z","receivedAt":"2023-10-06T14:42:50Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"Hi,\n\nOn Thu, Oct 5, 2023 at 2:24 PM Junio C Hamano wrote:\n>\n> Sergey Organov writes:\n>\n> > ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n> > +-m::\n> > + Show diffs for merge commits in the default format. This is\n> > + similar to '--diff-merges=on' (which see) except `-m` will\n> > + produce no output unless `-p` is given as well.\n>\n> I think the sentence reads better without the translated (q.v.) that\n> confused Eric.\n\nAgreed; confused me too.\n\n> > +-c::\n> > + Produce combined diff output for merge commits.\n> > + Shortcut for '--diff-merges=combined -p'.\n> > +\n> > +--cc::\n> > + Produce dense combined diff output for merge commits.\n> > + Shortcut for '--diff-merges=dense-combined -p'.\n>\n> Good.\n>\n> > +--remerge-diff::\n> > + Produce diff against re-merge.\n> > + Shortcut for '--diff-merges=remerge -p'.\n>\n> I suspect that many people do not get what \"re-merge\" in \"against\n> re-merge\" really is. As \"combined diff\" and \"dense combined diff\"\n> are not explained in the previous two entries either, and expect the\n> readers to read the real description (which more or less matches\n> what the original description for \"-c\" and \"--cc\" had, which is\n> good), it would be better to say \"Produce remerge-diff output for\n> merge commits.\" here, too. It makes it consistent, and \"for merge\n> commits\" makes it clear the \"magic\" does not apply to regular\n> commits (which the above entries for \"-c\" and \"--cc\" do, which is\n> very good).\n\nPerhaps:\n\nProduce remerge-diff output for merge commits, in order to show how\nconflicts were resolved.\n\n> > +separate::\n> > + Show full diff with respect to each of parents.\n> > + Separate log entry and diff is generated for each parent.\n>\n> In the early days of Git before -c/--cc were invented, we explained\n> this mode as \"pairwise comparison\", and the phrase \"pairwise\" still\n> may be the best one to describe the behaviour here. In fact, we see\n> in the updated description of combined below the exact phrase is used\n> to refer to this oldest output format.\n>\n> Show the `--patch` output pairwise, together with the commit\n> header, repeated for each parent for a merge commit.\n\nI like this.\n\n> or something, perhaps. I added \"repeated\" here to make the contrast\n> with \"simultaneously\" stand out.\n>\n> > +combined, c::\n> > + Show differences from each of the parents to the merge\n> > + result simultaneously instead of showing pairwise diff between\n> > + a parent and the result one at a time. Furthermore, it lists\n> > + only files which were modified from all parents.\n> > ++\n> > +dense-combined, cc::\n> > + Further compress output produced by `--diff-merges=combined`\n> > + by omitting uninteresting hunks whose contents in the parents\n> > + have only two variants and the merge result picks one of them\n> > + without modification.\n> > ++\n> > +remerge, r::\n> > + Remerge two-parent merge commits to create a temporary tree\n> > + object--potentially containing files with conflict markers\n> > + and such. A diff is then shown between that temporary tree\n> > + and the actual merge commit.\n>\n> The original says \"two-parent merge comimts are remerged\" so it is\n> not a failure of this patch, but the first verb \"Remerge\" sounds\n> unnecessarily unfriendly to the readers.\n>\n> For a two-parent merge commit, a merge of these two commits\n> is retried to create a temporary tree object, potentially\n> containing files with conflict markers. A `--patch` output\n> then is shown between ...\n>\n> would be easier to follow and more faithful to the original\n> description added by db757e8b (show, log: provide a --remerge-diff\n> capability, 2022-02-02).\n\nI like it. Perhaps it may also benefit from explaining why this mode\nis useful as well:\n\n For a two-parent merge commit, a merge of these two commits is\n retried to create a temporary tree object, potentially containing\n files with conflict markers. A diff is then shown between that\n temporary tree and the actual merge commit. This has the effect\n of showing whether and how both semantic and textual conflicts\n were resolved by the user (i.e. what changes the user made after\n running 'git merge' and before finally committing).\n\n> Either way, it makes readers wonder what happens to merges with more\n> than 2 parents (octopus merges). It is not a new problem and this\n> topic should not attempt to fix it.\n\nWe could add:\n\n For octopus merges (merges with more than two parents), currently\nonly shows a warning about skipping such commits.\n\nif wanted.\n\nBut perhaps I've distracted too much from Sergey's topic, and I should\nsubmit these wording tweaks as a patch on top? I'm fine either way.\n\n> [Footnote]\n>\n> * When a project allows fast-forward merges, something like this can\n> happen (and Git was _designed_ to allow and even encourage it)\n>\n> - Linus pulls from Sergey and sees merge conflicts that are very\n> messy. Sergey is asked to resolve the conflict, as Linus knows\n> Sergey understands the changes he is asking Linus to pull much\n> better than Linus does.\n>\n> - Sergey does \"git pull origin\" that would give the same set of\n> conflicts Linus saw, perhaps ours/theirs sides swapped, resolves\n> the conflicts, and comits the merge result. He may even add a\n> few other improvements on top (or may not). He tells Linus that\n> his tree is ready to be pulled again.\n>\n> - Linus pulls from Sergey again. This time it is fast-forward,\n> without an extra merge commit that records the Linus's previous\n> tip as the first parent and Sergey's work as the second parent.\n>\n> - Linus continues working from here.\n>\n> In such a workflow, merges are nothing more than \"combining\n> multiple histories together\" and the first parenthood is NOT\n> inherently special among parents at all. The original \"-m -p\"\n> (aka \"pairwise diff\") output reflects this world view and ensures\n> that all parents are shown more or less as equals (yes, the first\n> parent diff is shown first before the other parents, but you\n> cannot avoid it when outputting to a single dimension medium).\n>\n> This world view was the only world view Git supported, until I\n> added the \"--first-parent\" traversal in 0053e902 (git-log\n> --first-parent: show only the first parent log, 2007-03-13).\n>\n> With the \"--first-parent\", with \"--no-ff\" option to \"git merge\", a\n> different world view becomes possible. A merge is not merely\n> combining multiple histories, which are equals. It is bringing\n> work done on a side branch into the trunk. To see the overview of\n> the history, \"git log --first-parent\" would give the outline,\n> which would be full of merges from side branches, each of which\n> can be seen as summarizing the work done on the side branch that\n> was merged, and it may occasionally have single-parent commits\n> that are hotfixes or trivial clean-ups or project administrivia\n> commits. With \"-p\", \"git log\" would show the changes the work\n> done on a side branch as a single unit for a merge, and individual\n> commits if they are single-parent. The life is good.\n>\n> It all breaks down if the \"diff against the first parent\" is done\n> on a merge that is not bringing the work on a side branch in to\n> the trunk. The merge done in the second step Sergey did for Linus\n> in the above example will have his work on the history leading to\n> its first parent, and from the overall project's point of view,\n> the second parent is the tip of the history of the trunk. Showing\n> first-parent diff for a merge that was *not* discovered via the\n> first-parent traversal would show such a meaningless patch. This\n> is an illustration of the fallout from mixing two incompatible\n> world views together, \"--diff-merges=first-parent\" wants to work\n> in a world where the first-parent is special among parents, but\n> traversal without \"--first-parent\" wants to treat all the branches\n> equally.\n>\n> All the other s accepted by the \"--diff-merges=\"\n> option are symmetrical and they work equally well when in a\n> history of a project that considers the first-parenthood special\n> (i.e. work on a side branch is brought into the trunk history) or\n> in a history with merges whose parent order should not matter, so\n> unlike \"--diff-merges=first-parent\", it makes sense to apply them\n> with or without first-parent traversal. It however is not true\n> for the \"--diff-merges=first-parent\" variant, which is asymmetric.\n>\n> And that is why I think use of \"--diff-merges=first-parent\"\n> without \"--first-parent\" traversal is a bad thing to teach users\n> to use.\n\nThanks for writing this up. In the past, I didn't know how to put\ninto words why I didn't particularly care for this mode. You explain\nit rather well.\n"},{"id":"482741","messageId":"874jj3smym.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqcyxshizq.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T17:02:57Z","receivedAt":"2023-10-06T17:03:06Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Eric Sunshine writes:\n>\n>>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n>>> @@ -43,66 +43,74 @@ endif::git-diff[]\n>>> +-m::\n>>> + Show diffs for merge commits in the default format. This is\n>>> + similar to '--diff-merges=on' (which see) except `-m` will\n>>> + produce no output unless `-p` is given as well.\n>>\n>> I'm having difficulty grasping the parenthetical \"(which see)\" comment.\n>\n> I am, too. I know what it means when written in the more common\n> Latin abbreviation (q.v.), but I suspect it may be rare to spell it\n> in English like this. I found\n\nWell, I didn't invent it, and didn't lookup it until asked, it just\npopped-up out of my head somehow.\n\nI'll remove it as causes confusion.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482742","messageId":"87zg0vr8cx.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"CABPp-BFsrt0zS3NHsVAyOSW6vGioe8Z-iN2M3_JNBpP2fWVq9g@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T17:03:42Z","receivedAt":"2023-10-06T17:03:49Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Elijah Newren writes:\n\n> Hi,\n>\n> On Thu, Oct 5, 2023 at 2:24 PM Junio C Hamano wrote:\n>>\n>> Sergey Organov writes:\n>>\n>> > ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n>> > +-m::\n>> > + Show diffs for merge commits in the default format. This is\n>> > + similar to '--diff-merges=on' (which see) except `-m` will\n>> > + produce no output unless `-p` is given as well.\n>>\n>> I think the sentence reads better without the translated (q.v.) that\n>> confused Eric.\n>\n> Agreed; confused me too.\n\nWill remove, no problem.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482743","messageId":"87v8bjr8a7.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqr0m8eoaq.fsf@gitster.g","subject":"Re: [PATCH v3 2/3] diff-merges: introduce '--dd' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T17:05:20Z","receivedAt":"2023-10-06T17:05:28Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> This option provides a shortcut to request diff with respect to first\n>> parent for any kind of commit, universally. It's implemented as pure\n>> synonym for \"--diff-merges=first-parent --patch\".\n>\n> That explains what the patch does, but it does not tell us why it is\n> useful [*].\n>\n>> NOTE: originally proposed as '-d', and renamed to '--dd' due to Junio\n>> request to keep \"short-and-sweet\" '-d' reserved for other uses.\n>\n> The note is not grammatical, and more importantly, readers of \"git\n> log\" 6 months down the road would not care. I'd rather not see it\n> in the proposed log message. It is suitable material to place after\n> the three-dash line, or in the cover letter for the iteration.\n\nOK, will get rid of it.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482745","messageId":"87r0m7r863.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"CABPp-BFsrt0zS3NHsVAyOSW6vGioe8Z-iN2M3_JNBpP2fWVq9g@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T17:07:48Z","receivedAt":"2023-10-06T17:07:55Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Elijah Newren writes:\n\n> Hi,\n>\n> On Thu, Oct 5, 2023 at 2:24 PM Junio C Hamano wrote:\n>>\n>> Sergey Organov writes:\n>> > +--remerge-diff::\n>> > + Produce diff against re-merge.\n>> > + Shortcut for '--diff-merges=remerge -p'.\n>>\n>> I suspect that many people do not get what \"re-merge\" in \"against\n>> re-merge\" really is. As \"combined diff\" and \"dense combined diff\"\n>> are not explained in the previous two entries either, and expect the\n>> readers to read the real description (which more or less matches\n>> what the original description for \"-c\" and \"--cc\" had, which is\n>> good), it would be better to say \"Produce remerge-diff output for\n>> merge commits.\" here, too. It makes it consistent, and \"for merge\n>> commits\" makes it clear the \"magic\" does not apply to regular\n>> commits (which the above entries for \"-c\" and \"--cc\" do, which is\n>> very good).\n>\n> Perhaps:\n>\n> Produce remerge-diff output for merge commits, in order to show how\n> conflicts were resolved.\n\nWill use this description in re-roll.\n\n>\n>> > +separate::\n>> > + Show full diff with respect to each of parents.\n>> > + Separate log entry and diff is generated for each parent.\n>>\n>> In the early days of Git before -c/--cc were invented, we explained\n>> this mode as \"pairwise comparison\", and the phrase \"pairwise\" still\n>> may be the best one to describe the behaviour here. In fact, we see\n>> in the updated description of combined below the exact phrase is used\n>> to refer to this oldest output format.\n>>\n>> Show the `--patch` output pairwise, together with the commit\n>> header, repeated for each parent for a merge commit.\n>\n> I like this.\n>\n>> or something, perhaps. I added \"repeated\" here to make the contrast\n>> with \"simultaneously\" stand out.\n\nPlease let's left it for some follow-up, as this patch does not rephrase\noriginal, just changes the presentation.\n\n>>\n>> > +combined, c::\n>> > + Show differences from each of the parents to the merge\n>> > + result simultaneously instead of showing pairwise diff between\n>> > + a parent and the result one at a time. Furthermore, it lists\n>> > + only files which were modified from all parents.\n>> > ++\n>> > +dense-combined, cc::\n>> > + Further compress output produced by `--diff-merges=combined`\n>> > + by omitting uninteresting hunks whose contents in the parents\n>> > + have only two variants and the merge result picks one of them\n>> > + without modification.\n>> > ++\n>> > +remerge, r::\n>> > + Remerge two-parent merge commits to create a temporary tree\n>> > + object--potentially containing files with conflict markers\n>> > + and such. A diff is then shown between that temporary tree\n>> > + and the actual merge commit.\n>>\n>> The original says \"two-parent merge comimts are remerged\" so it is\n>> not a failure of this patch, but the first verb \"Remerge\" sounds\n>> unnecessarily unfriendly to the readers.\n>>\n>> For a two-parent merge commit, a merge of these two commits\n>> is retried to create a temporary tree object, potentially\n>> containing files with conflict markers. A `--patch` output\n>> then is shown between ...\n>>\n>> would be easier to follow and more faithful to the original\n>> description added by db757e8b (show, log: provide a --remerge-diff\n>> capability, 2022-02-02).\n>\n> I like it. Perhaps it may also benefit from explaining why this mode\n> is useful as well:\n>\n> For a two-parent merge commit, a merge of these two commits is\n> retried to create a temporary tree object, potentially containing\n> files with conflict markers. A diff is then shown between that\n> temporary tree and the actual merge commit. This has the effect\n> of showing whether and how both semantic and textual conflicts\n> were resolved by the user (i.e. what changes the user made after\n> running 'git merge' and before finally committing).\n>\n>> Either way, it makes readers wonder what happens to merges with more\n>> than 2 parents (octopus merges). It is not a new problem and this\n>> topic should not attempt to fix it.\n>\n> We could add:\n>\n> For octopus merges (merges with more than two parents), currently\n> only shows a warning about skipping such commits.\n>\n> if wanted.\n>\n> But perhaps I've distracted too much from Sergey's topic, and I should\n> submit these wording tweaks as a patch on top? I'm fine either way.\n>\n>> [Footnote]\n>>\n>> * When a project allows fast-forward merges, something like this can\n>> happen (and Git was _designed_ to allow and even encourage it)\n>>\n>> - Linus pulls from Sergey and sees merge conflicts that are very\n>> messy. Sergey is asked to resolve the conflict, as Linus knows\n>> Sergey understands the changes he is asking Linus to pull much\n>> better than Linus does.\n>>\n>> - Sergey does \"git pull origin\" that would give the same set of\n>> conflicts Linus saw, perhaps ours/theirs sides swapped, resolves\n>> the conflicts, and comits the merge result. He may even add a\n>> few other improvements on top (or may not). He tells Linus that\n>> his tree is ready to be pulled again.\n>>\n>> - Linus pulls from Sergey again. This time it is fast-forward,\n>> without an extra merge commit that records the Linus's previous\n>> tip as the first parent and Sergey's work as the second parent.\n>>\n>> - Linus continues working from here.\n>>\n>> In such a workflow, merges are nothing more than \"combining\n>> multiple histories together\" and the first parenthood is NOT\n>> inherently special among parents at all. The original \"-m -p\"\n>> (aka \"pairwise diff\") output reflects this world view and ensures\n>> that all parents are shown more or less as equals (yes, the first\n>> parent diff is shown first before the other parents, but you\n>> cannot avoid it when outputting to a single dimension medium).\n>>\n>> This world view was the only world view Git supported, until I\n>> added the \"--first-parent\" traversal in 0053e902 (git-log\n>> --first-parent: show only the first parent log, 2007-03-13).\n>>\n>> With the \"--first-parent\", with \"--no-ff\" option to \"git merge\", a\n>> different world view becomes possible. A merge is not merely\n>> combining multiple histories, which are equals. It is bringing\n>> work done on a side branch into the trunk. To see the overview of\n>> the history, \"git log --first-parent\" would give the outline,\n>> which would be full of merges from side branches, each of which\n>> can be seen as summarizing the work done on the side branch that\n>> was merged, and it may occasionally have single-parent commits\n>> that are hotfixes or trivial clean-ups or project administrivia\n>> commits. With \"-p\", \"git log\" would show the changes the work\n>> done on a side branch as a single unit for a merge, and individual\n>> commits if they are single-parent. The life is good.\n>>\n>> It all breaks down if the \"diff against the first parent\" is done\n>> on a merge that is not bringing the work on a side branch in to\n>> the trunk. The merge done in the second step Sergey did for Linus\n>> in the above example will have his work on the history leading to\n>> its first parent, and from the overall project's point of view,\n>> the second parent is the tip of the history of the trunk. Showing\n>> first-parent diff for a merge that was *not* discovered via the\n>> first-parent traversal would show such a meaningless patch. This\n>> is an illustration of the fallout from mixing two incompatible\n>> world views together, \"--diff-merges=first-parent\" wants to work\n>> in a world where the first-parent is special among parents, but\n>> traversal without \"--first-parent\" wants to treat all the branches\n>> equally.\n>>\n>> All the other s accepted by the \"--diff-merges=\"\n>> option are symmetrical and they work equally well when in a\n>> history of a project that considers the first-parenthood special\n>> (i.e. work on a side branch is brought into the trunk history) or\n>> in a history with merges whose parent order should not matter, so\n>> unlike \"--diff-merges=first-parent\", it makes sense to apply them\n>> with or without first-parent traversal. It however is not true\n>> for the \"--diff-merges=first-parent\" variant, which is asymmetric.\n>>\n>> And that is why I think use of \"--diff-merges=first-parent\"\n>> without \"--first-parent\" traversal is a bad thing to teach users\n>> to use.\n>\n> Thanks for writing this up. In the past, I didn't know how to put\n> into words why I didn't particularly care for this mode. You explain\n> it rather well.\n"},{"id":"482747","messageId":"87mswvr7oo.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqq34yog3ux.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T17:18:15Z","receivedAt":"2023-10-06T17:18:22Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n\n[...]\n\n>> --no-diff-merges::\n>> +\tSynonym for '--diff-merges=off'.\n>> +\n>> +--diff-merges=::\n>> \tSpecify diff format to be used for merge commits. Default is\n>> -\t{diff-merges-default} unless `--first-parent` is in use, in which case\n>> -\t`first-parent` is the default.\n>> +\t{diff-merges-default} unless `--first-parent` is in use, in\n>> +\twhich case `first-parent` is the default.\n>\n> This reads well.\n>\n> In the longer term, \"--diff-merge=first-parent\" that is used without\n> first-parent traversal should be discouraged and be deprecated, I\n> think, but that is a separate story [*].\n\nI fail to see why useful harmless feature is to be deprecated. I believe\nusers are pretty capable to decide if they need it by themselves,\nwithout our guidance.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482749","messageId":"xmqq7cnzaav0.fsf@gitster.g","threadId":"60213","inReplyTo":"CABPp-BFsrt0zS3NHsVAyOSW6vGioe8Z-iN2M3_JNBpP2fWVq9g@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-06T18:01:39Z","receivedAt":"2023-10-06T18:01:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n>> > +--cc::\n>> > + Produce dense combined diff output for merge commits.\n>> > + Shortcut for '--diff-merges=dense-combined -p'.\n>>\n>> Good.\n>>\n>> > +--remerge-diff::\n>> > + Produce diff against re-merge.\n>> > + Shortcut for '--diff-merges=remerge -p'.\n>> ...\n> Perhaps:\n>\n> Produce remerge-diff output for merge commits, in order to show how\n> conflicts were resolved.\n\nI do not mind it, but then I'd prefer to see \", in order to show\nhow\" also in the description of \"--cc\" and \"-c\" for consistency.\n\nA succinct way to say what they do may be hard to come by, but I\nthink of them showing places that did not have obvious natural\nresolution.\n\n> For a two-parent merge commit, a merge of these two commits is\n> retried to create a temporary tree object, potentially containing\n> files with conflict markers. A diff is then shown between that\n> temporary tree and the actual merge commit. This has the effect\n> of showing whether and how both semantic and textual conflicts\n> were resolved by the user (i.e. what changes the user made after\n> running 'git merge' and before finally committing).\n\nYes, and because we do not have a back reference from here to the\ndescription for \"--remerge-diff\" we saw earlier, we'd need the \"in\norder to\" you suggested earlier there, too.\n\n>> Either way, it makes readers wonder what happens to merges with more\n>> than 2 parents (octopus merges). It is not a new problem and this\n>> topic should not attempt to fix it.\n>\n> We could add:\n>\n> For octopus merges (merges with more than two parents), currently\n> only shows a warning about skipping such commits.\n>\n> if wanted.\n>\n> But perhaps I've distracted too much from Sergey's topic, and I should\n> submit these wording tweaks as a patch on top? I'm fine either way.\n\nThe primary purpose of polishing during a review cycle should be to\nhelp the original contributor to express what they wanted to express\nbetter, so talking about octopus behaviour, which wasn't covered in\nthe original nor the patch under review, can be left out to avoid\nextending the scope of the topic further.\n\nBut everything else you said in the message I am responding to falls\ninto the scope of the \"improving existing documentation for various\nmerge presentation modes\" topic, I would think, and they are more or\nless usable verbatim, so it would not be too much of a burden to\nmake sure they are used in the next iteration.\n\nThanks for a review, and thanks Sergey for streamlining the\ndocumentation around here.\n\n\n"},{"id":"482756","messageId":"875y3jr42h.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqq7cnzaav0.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T18:36:22Z","receivedAt":"2023-10-06T18:36:30Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Elijah Newren writes:\n>\n>>> > +--cc::\n>>> > + Produce dense combined diff output for merge commits.\n>>> > + Shortcut for '--diff-merges=dense-combined -p'.\n>>>\n>>> Good.\n>>>\n>>> > +--remerge-diff::\n>>> > + Produce diff against re-merge.\n>>> > + Shortcut for '--diff-merges=remerge -p'.\n>>> ...\n>> Perhaps:\n>>\n>> Produce remerge-diff output for merge commits, in order to show how\n>> conflicts were resolved.\n>\n> I do not mind it, but then I'd prefer to see \", in order to show\n> how\" also in the description of \"--cc\" and \"-c\" for consistency.\n>\n> A succinct way to say what they do may be hard to come by, but I\n> think of them showing places that did not have obvious natural\n> resolution.\n\nSo, is it OK with both of you if I leave it as:\n\n\"Produce remerge-diff output for merge commits.\"\n\nfor now, and let you tweak the descriptions later on, if needed?\n\nThanks,\n-- Sergey Organov\n"},{"id":"482757","messageId":"871qe7r3rk.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqq34yog3ux.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T18:42:55Z","receivedAt":"2023-10-06T18:43:01Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n\n[...]\n\n>> +on, m::\n>> +\tMake diff output for merge commits to be shown in the default\n>> +\tformat. The default format could be changed using\n>> \t`log.diffMerges` configuration parameter, which default value\n>> \tis `separate`.\n>\n> The original is already wrong so these are not problems this patch\n> introduces, but\n>\n> - \"configuration variable\" is how we refer to these entities.\n> - \"which default value\" -> \"whose default value\".\n\nAdded this amendment to the patch.\n\nThanks,\n-- Sergey Organov\n"},{"id":"482758","messageId":"87v8bjpopq.fsf@osv.gnss.ru","threadId":"60213","inReplyTo":"xmqqlecgeoan.fsf@gitster.g","subject":"Re: [PATCH v3 3/3] completion: complete '--dd'","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-06T18:53:21Z","receivedAt":"2023-10-06T18:55:06Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano writes:\n\n> Sergey Organov writes:\n>\n>> '--dd' only makes sense for 'git log' and 'git show', so add it to\n>> __git_log_show_options which is referenced in the completion for these\n>> two commands.\n>>\n>> Signed-off-by: Sergey Organov \n>> ---\n>> contrib/completion/git-completion.bash | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\n>> index 133ec92bfae7..ca4fa39f3ff8 100644\n>> --- a/contrib/completion/git-completion.bash\n>> +++ b/contrib/completion/git-completion.bash\n>> @@ -2042,7 +2042,7 @@ __git_log_shortlog_options=\"\n>> \"\n>> # Options accepted by log and show\n>> __git_log_show_options=\"\n>> -\t--diff-merges --diff-merges= --no-diff-merges --remerge-diff\n>> +\t--diff-merges --diff-merges= --no-diff-merges --dd --remerge-diff\n>> \"\n>> \n>> __git_diff_merges_opts=\"off none on first-parent 1 separate m combined c dense-combined cc remerge r\"\n>\n> Quite straight-forward. I am kind of surprised that we do not have\n> to list \"--cc\" here. Perhaps it is so short and common that people\n> do not need completion help?\n>\n> But that is not a new problem caused by this series, so it is OK.\n>\n> Unless \"--cc\" gets completed without being listed here, using some\n> automation like the \"--git-completion-helper\" option, in which case\n> we may want to see if we can remove all of the above and complete\n> them the same way as \"--cc\" gets completed. I didn't check.\n\nI checked, though with rather old 2.25.1 running on my Ubuntu, and it\nis not completed.\n\nI think that it's still a good idea to add --cc to completions, so that\nit's there in the suggested completion list, for the sake of\ndiscoverability. That's why I bothered to add --dd to the completions.\n\nThanks,\n-- Sergey Organov\n\n\n>\n> Thanks.\n"},{"id":"482777","messageId":"xmqqv8bj5ofq.fsf@gitster.g","threadId":"60213","inReplyTo":"875y3jr42h.fsf@osv.gnss.ru","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-06T23:19:37Z","receivedAt":"2023-10-06T23:19:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> Junio C Hamano writes:\n>\n>> Elijah Newren writes:\n>>\n>>>> > +--cc::\n>>>> > + Produce dense combined diff output for merge commits.\n>>>> > + Shortcut for '--diff-merges=dense-combined -p'.\n>>>>\n>>>> Good.\n>>>>\n>>>> > +--remerge-diff::\n>>>> > + Produce diff against re-merge.\n>>>> > + Shortcut for '--diff-merges=remerge -p'.\n>>>> ...\n>>> Perhaps:\n>>>\n>>> Produce remerge-diff output for merge commits, in order to show how\n>>> conflicts were resolved.\n>>\n>> I do not mind it, but then I'd prefer to see \", in order to show\n>> how\" also in the description of \"--cc\" and \"-c\" for consistency.\n>>\n>> A succinct way to say what they do may be hard to come by, but I\n>> think of them showing places that did not have obvious natural\n>> resolution.\n>\n> So, is it OK with both of you if I leave it as:\n>\n> \"Produce remerge-diff output for merge commits.\"\n>\n> for now, and let you tweak the descriptions later on, if needed?\n\nI do not know what Elijah would say, but in one of iterations of my\ndraft response to him indeed suggested that \"in order to\" here is\nnot necessary if it is described for the \"--diff-merges=remerge\"\noption, because those who know enough to skip referring to the other\nentry are expected to know why it exists. So I think I am OK with\nthat.\n\nThanks.\n"},{"id":"482782","messageId":"CABPp-BGxVnhnmoajWyqY_gMvQ42W5S6VX5EOXq3PW=GLVQwe0g@mail.gmail.com","threadId":"60213","inReplyTo":"xmqq7cnzaav0.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-10-07T01:31:00Z","receivedAt":"2023-10-07T01:32:34Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Fri, Oct 6, 2023 at 11:01 AM Junio C Hamano wrote:\n>\n> Elijah Newren writes:\n>\n> >> > +--cc::\n> >> > + Produce dense combined diff output for merge commits.\n> >> > + Shortcut for '--diff-merges=dense-combined -p'.\n> >>\n> >> Good.\n> >>\n> >> > +--remerge-diff::\n> >> > + Produce diff against re-merge.\n> >> > + Shortcut for '--diff-merges=remerge -p'.\n> >> ...\n> > Perhaps:\n> >\n> > Produce remerge-diff output for merge commits, in order to show how\n> > conflicts were resolved.\n>\n> I do not mind it, but then I'd prefer to see \", in order to show\n> how\" also in the description of \"--cc\" and \"-c\" for consistency.\n\nThe problem is it's really hard for me to come up with an answer to\nthat, in part because...\n\n> A succinct way to say what they do may be hard to come by, but I\n> think of them showing places that did not have obvious natural\n> resolution.\n\nIn my opinion, --remerge-diff does this better; wouldn't we want a\nrationale where these particular modes shine? Is that a non-empty\nset? (It may well be, but to me, --cc was never worse than -c while\noften being better, and likewise, --remerge-diff is never worse than\n--cc while often being better, at least on anything I had thought to\nuse any of these for. Maybe there are other usecases for -c and --cc\nI'm just not thinking of?)\n"},{"id":"482783","messageId":"xmqqjzrz5hgn.fsf@gitster.g","threadId":"60213","inReplyTo":"CABPp-BGxVnhnmoajWyqY_gMvQ42W5S6VX5EOXq3PW=GLVQwe0g@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-07T01:50:16Z","receivedAt":"2023-10-07T01:50:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n> In my opinion, --remerge-diff does this better; wouldn't we want a\n> rationale where these particular modes shine? Is that a non-empty\n> set? (It may well be, but to me, --cc was never worse than -c while\n> often being better, and likewise, --remerge-diff is never worse than\n> --cc while often being better, at least on anything I had thought to\n> use any of these for. Maybe there are other usecases for -c and --cc\n> I'm just not thinking of?)\n\nBetween -c and --cc, I do not think there is anything that makes us\nfavor -c over --cc. While the algorithm to decide which hunks out\nof -c's output to omit was being polished, comparison with -c served\na good way to give baseline, but once --cc has become solid, I do\nnot think I've used -c myself.\n\nI personally find that a very trivial merge resolution is far easier\nto read with --cc than --remerge-diff, the latter being way too\nverbose.\n\nAlso, --cc and -c should work inside a read-only repository where\nyou only have read access to. If remerge needs to write some\nobjects to the repository, then you'd need some hack to give a\nwritable object store overlay via the alternate odb mechanism, or\nsomething, right?\n\n\n$ git show --oneline --cc -U1 9fde277c338\n9fde277c33 Merge branch 'cc/git-replay' into seen\n\ndiff --cc Makefile\nindex cf60c16deb,05a504dc28..c581c1ddba\n--- a/Makefile\n+++ b/Makefile\n@@@ -803,4 -801,2 +803,3 @@@ TEST_BUILTINS_OBJS += test-env-helper.\n TEST_BUILTINS_OBJS += test-example-decorate.o\n- TEST_BUILTINS_OBJS += test-fast-rebase.o\n +TEST_BUILTINS_OBJS += test-find-pack.o\n TEST_BUILTINS_OBJS += test-fsmonitor-client.o\ndiff --cc t/helper/test-tool.c\nindex 9010ac6de7,9ca1586de7..77b1d7c15d\n--- a/t/helper/test-tool.c\n+++ b/t/helper/test-tool.c\n@@@ -32,4 -32,2 +32,3 @@@ static struct test_cmd cmds[] = \n \t{ \"example-decorate\", cmd__example_decorate },\n- \t{ \"fast-rebase\", cmd__fast_rebase },\n +\t{ \"find-pack\", cmd__find_pack },\n \t{ \"fsmonitor-client\", cmd__fsmonitor_client },\ndiff --cc t/helper/test-tool.h\nindex f134f96b97,a03bbfc6b2..5deeca66fe\n--- a/t/helper/test-tool.h\n+++ b/t/helper/test-tool.h\n@@@ -26,4 -26,2 +26,3 @@@ int cmd__env_helper(int argc, const cha\n int cmd__example_decorate(int argc, const char **argv);\n- int cmd__fast_rebase(int argc, const char **argv);\n +int cmd__find_pack(int argc, const char **argv);\n int cmd__fsmonitor_client(int argc, const char **argv);\n$ git show --oneline --remerge-diff -U1 9fde277c338\n9fde277c33 Merge branch 'cc/git-replay' into seen\ndiff --git a/Makefile b/Makefile\nremerge CONFLICT (content): Merge conflict in Makefile\nindex 987c8e3569..c581c1ddba 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -803,9 +803,3 @@ TEST_BUILTINS_OBJS += test-env-helper.o\n TEST_BUILTINS_OBJS += test-example-decorate.o\n-<<<<<<< 0fd7a144c5 (Merge branch 'js/doc-unit-tests-with-cmake' into seen)\n-TEST_BUILTINS_OBJS += test-fast-rebase.o\n TEST_BUILTINS_OBJS += test-find-pack.o\n-||||||| 1fc548b2d6\n-TEST_BUILTINS_OBJS += test-fast-rebase.o\n-=======\n->>>>>>> 0b853ad4db (replay: stop assuming replayed branches do not diverge)\n TEST_BUILTINS_OBJS += test-fsmonitor-client.o\ndiff --git a/t/helper/test-tool.c b/t/helper/test-tool.c\nremerge CONFLICT (content): Merge conflict in t/helper/test-tool.c\nindex 87a9794564..77b1d7c15d 100644\n--- a/t/helper/test-tool.c\n+++ b/t/helper/test-tool.c\n@@ -32,9 +32,3 @@ static struct test_cmd cmds[] = {\n \t{ \"example-decorate\", cmd__example_decorate },\n-<<<<<<< 0fd7a144c5 (Merge branch 'js/doc-unit-tests-with-cmake' into seen)\n-\t{ \"fast-rebase\", cmd__fast_rebase },\n \t{ \"find-pack\", cmd__find_pack },\n-||||||| 1fc548b2d6\n-\t{ \"fast-rebase\", cmd__fast_rebase },\n-=======\n->>>>>>> 0b853ad4db (replay: stop assuming replayed branches do not diverge)\n \t{ \"fsmonitor-client\", cmd__fsmonitor_client },\ndiff --git a/t/helper/test-tool.h b/t/helper/test-tool.h\nremerge CONFLICT (content): Merge conflict in t/helper/test-tool.h\nindex e8abf4c42f..5deeca66fe 100644\n--- a/t/helper/test-tool.h\n+++ b/t/helper/test-tool.h\n@@ -26,9 +26,3 @@ int cmd__env_helper(int argc, const char **argv);\n int cmd__example_decorate(int argc, const char **argv);\n-<<<<<<< 0fd7a144c5 (Merge branch 'js/doc-unit-tests-with-cmake' into seen)\n-int cmd__fast_rebase(int argc, const char **argv);\n int cmd__find_pack(int argc, const char **argv);\n-||||||| 1fc548b2d6\n-int cmd__fast_rebase(int argc, const char **argv);\n-=======\n->>>>>>> 0b853ad4db (replay: stop assuming replayed branches do not diverge)\n int cmd__fsmonitor_client(int argc, const char **argv);\n\n"},{"id":"482785","messageId":"xmqqmswv3p11.fsf@gitster.g","threadId":"60213","inReplyTo":"xmqqjzrz5hgn.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-07T06:49:46Z","receivedAt":"2023-10-07T06:50:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Elijah Newren writes:\n>\n>> In my opinion, --remerge-diff does this better; wouldn't we want a\n>> ...\n> I personally find that a very trivial merge resolution is far easier\n> to read with --cc than --remerge-diff, the latter being way too\n> verbose.\n>\n> Also, --cc and -c should work inside a read-only repository where\n> you only have read access to. If remerge needs to write some\n> objects to the repository, then you'd need some hack to give a\n> writable object store overlay via the alternate odb mechanism, or\n> something, right?\n\nWell, the above did not come out as well as I intended, as I forgot\nto prefix it with something I thought was obvious from what I said\nin the recent discussion in the earlier iteration of this topic,\nwhere I said that it would be \"--remerge-diff\", if I were to pick an\noption that is so useful that it deserves short and sweet single\nletter. Narutally, it came after we gained experience with \"--cc\",\nso it would be surprising if it did worse. Just like it is natural\nto expect that \"--cc\" would give more useful output than \"-m -p\"\nthat predates everybody else.\n\nIn short, I would say \"--remerge-diff\" would give output that is the\neasiest to grok among the three modern variants to show the changes\na merge introduces.\n\nThe above two cases, where I said cc does better than remerge-diff,\nwere meant as _exceptions_ for that general sentiment.\n"},{"id":"482867","messageId":"20231009160535.236523-1-sorganov@gmail.com","threadId":"60213","inReplyTo":"20230909125446.142715-1-sorganov@gmail.com","subject":"[PATCH v4 0/3] diff-merges: introduce '--dd' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-09T16:05:32Z","receivedAt":"2023-10-09T16:06:50Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This new convenience option requests full diff with respect to first\nparent, so that\n\n git log --dd\n\nwill output diff with respect to first parent for every commit,\nuniversally, no matter how many parents the commit turns out to have.\n\nGives user quick and universal way to see what changes, exactly, were\nbrought to a branch by merges as well as by regular commits.\n\n'--dd' is implemented as pure synonym for \"--diff-merges=first-parent\n--patch\".\n\nThe first commit in the series tweaks diff-merges documentation a bit,\nand is valuable by itself. It's put here as '--dd' implementation\ncommit depends on it in its documentation part.\n\nNote: the need for this new convenience option mostly emerged from\ndenial by the community of patches that modify '-m' behavior to imply\n'-p' as the rest of similar options (such as --cc) do. So, basically,\n'--dd' is what '-m' should have been to be more useful.\n\nUpdates in v4:\n\n * Removed \"(which see)\" reference from documentation that caused\n confusion.\n\n * Removed explanation why it's --dd and not simply -d from commit\n message.\n\n * Refined --remerge-diff short description according to Junio and\n Elijah comments.\n\n * Added explanation of --dd purpose.\n\n * Fixed style and syntax of \"on,m::\" description.\n\nUpdates in v3:\n\n * Option renamed from '-d' to '--dd' due to Junio overpowering\n request to keep short-and-sweet '-d' reserved for another (yet\n unspecified) use.\n\n * Added completion of '--dd' to git-completion.bash.\n\nUpdates in v2:\n\n * Reordered documentation for diff-merges formats in accordance with\n Junio recommendation.\n\n * Removed clarification of surprising -m behavior due to controversy\n with Junio on how exactly it should look like.\n\nSergey Organov (3):\n diff-merges: improve --diff-merges documentation\n diff-merges: introduce '--dd' option\n completion: complete '--dd'\n\n Documentation/diff-options.txt | 105 ++++++++++++++-----------\n Documentation/git-log.txt | 4 +-\n contrib/completion/git-completion.bash | 2 +-\n diff-merges.c | 3 +\n t/t4013-diff-various.sh | 8 ++\n 5 files changed, 73 insertions(+), 49 deletions(-)\n\nInterdiff against v3:\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex f80d493dd4c8..23f95e6172b9 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -45,7 +45,7 @@ endif::git-format-patch[]\n ifdef::git-log[]\n -m::\n \tShow diffs for merge commits in the default format. This is\n-\tsimilar to '--diff-merges=on' (which see) except `-m` will\n+\tsimilar to '--diff-merges=on', except `-m` will\n \tproduce no output unless `-p` is given as well.\n \n -c::\n@@ -62,7 +62,7 @@ ifdef::git-log[]\n \tShortcut for '--diff-merges=first-parent -p'.\n \n --remerge-diff::\n-\tProduce diff against re-merge.\n+\tProduce remerge-diff output for merge commits.\n \tShortcut for '--diff-merges=remerge -p'.\n \n --no-diff-merges::\n@@ -83,7 +83,7 @@ off, none::\n on, m::\n \tMake diff output for merge commits to be shown in the default\n \tformat. The default format could be changed using\n-\t`log.diffMerges` configuration parameter, which default value\n+\t`log.diffMerges` configuration variable, whose default value\n \tis `separate`.\n +\n first-parent, 1::\n-- \n2.25.1\n\n"},{"id":"482868","messageId":"20231009160535.236523-3-sorganov@gmail.com","threadId":"60213","inReplyTo":"20231009160535.236523-1-sorganov@gmail.com","subject":"[PATCH v4 2/3] diff-merges: introduce '--dd' option","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-09T16:05:34Z","receivedAt":"2023-10-09T16:06:52Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"This option provides a shortcut to request diff with respect to first\nparent for any kind of commit, universally. It's implemented as pure\nsynonym for \"--diff-merges=first-parent --patch\".\n\nGives user quick and universal way to see what changes, exactly, were\nbrought to a branch by merges as well as by regular commits.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 5 +++++\n Documentation/git-log.txt | 2 +-\n diff-merges.c | 3 +++\n t/t4013-diff-various.sh | 8 ++++++++\n 4 files changed, 17 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 69065c0e90a8..23f95e6172b9 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -56,6 +56,11 @@ ifdef::git-log[]\n \tProduce dense combined diff output for merge commits.\n \tShortcut for '--diff-merges=dense-combined -p'.\n \n+--dd::\n+\tProduce diff with respect to first parent for both merge and\n+\tregular commits.\n+\tShortcut for '--diff-merges=first-parent -p'.\n+\n --remerge-diff::\n \tProduce remerge-diff output for merge commits.\n \tShortcut for '--diff-merges=remerge -p'.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 9b7ec96e767a..579682172fe4 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -120,7 +120,7 @@ By default, `git log` does not generate any diff output. The options\n below can be used to show the changes made by each commit.\n \n Note that unless one of `--diff-merges` variants (including short\n-`-m`, `-c`, and `--cc` options) is explicitly given, merge commits\n+`-m`, `-c`, `--cc`, and `--dd` options) is explicitly given, merge commits\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\ndiff --git a/diff-merges.c b/diff-merges.c\nindex ec97616db1df..45507588a279 100644\n--- a/diff-merges.c\n+++ b/diff-merges.c\n@@ -131,6 +131,9 @@ int diff_merges_parse_opts(struct rev_info *revs, const char **argv)\n \t} else if (!strcmp(arg, \"--cc\")) {\n \t\tset_dense_combined(revs);\n \t\trevs->merges_imply_patch = 1;\n+\t} else if (!strcmp(arg, \"--dd\")) {\n+\t\tset_first_parent(revs);\n+\t\trevs->merges_imply_patch = 1;\n \t} else if (!strcmp(arg, \"--remerge-diff\")) {\n \t\tset_remerge_diff(revs);\n \t\trevs->merges_imply_patch = 1;\ndiff --git a/t/t4013-diff-various.sh b/t/t4013-diff-various.sh\nindex 5de1d190759f..4b474808311e 100755\n--- a/t/t4013-diff-various.sh\n+++ b/t/t4013-diff-various.sh\n@@ -473,6 +473,14 @@ test_expect_success 'log --diff-merges=on matches --diff-merges=separate' '\n \ttest_cmp expected actual\n '\n \n+test_expect_success 'log --dd matches --diff-merges=1 -p' '\n+\tgit log --diff-merges=1 -p master >result &&\n+\tprocess_diffs result >expected &&\n+\tgit log --dd master >result &&\n+\tprocess_diffs result >actual &&\n+\ttest_cmp expected actual\n+'\n+\n test_expect_success 'deny wrong log.diffMerges config' '\n \ttest_config log.diffMerges wrong-value &&\n \ttest_expect_code 128 git log\n-- \n2.25.1\n\n"},{"id":"482869","messageId":"20231009160535.236523-2-sorganov@gmail.com","threadId":"60213","inReplyTo":"20231009160535.236523-1-sorganov@gmail.com","subject":"[PATCH v4 1/3] diff-merges: improve --diff-merges documentation","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-09T16:05:33Z","receivedAt":"2023-10-09T16:06:54Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"* Put descriptions of convenience shortcuts first, so they are the\n first things reader observes rather than lengthy detailed stuff.\n\n* Get rid of very long line containing all the --diff-merges formats\n by replacing them with , and putting each supported format\n on its own line.\n\nSigned-off-by: Sergey Organov \n---\n Documentation/diff-options.txt | 100 ++++++++++++++++++---------------\n Documentation/git-log.txt | 2 +-\n 2 files changed, 55 insertions(+), 47 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9f33f887711d..69065c0e90a8 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -43,66 +43,74 @@ endif::git-diff[]\n endif::git-format-patch[]\n \n ifdef::git-log[]\n---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::\n+-m::\n+\tShow diffs for merge commits in the default format. This is\n+\tsimilar to '--diff-merges=on', except `-m` will\n+\tproduce no output unless `-p` is given as well.\n+\n+-c::\n+\tProduce combined diff output for merge commits.\n+\tShortcut for '--diff-merges=combined -p'.\n+\n+--cc::\n+\tProduce dense combined diff output for merge commits.\n+\tShortcut for '--diff-merges=dense-combined -p'.\n+\n+--remerge-diff::\n+\tProduce remerge-diff output for merge commits.\n+\tShortcut for '--diff-merges=remerge -p'.\n+\n --no-diff-merges::\n+\tSynonym for '--diff-merges=off'.\n+\n+--diff-merges=::\n \tSpecify diff format to be used for merge commits. Default is\n-\t{diff-merges-default} unless `--first-parent` is in use, in which case\n-\t`first-parent` is the default.\n+\t{diff-merges-default} unless `--first-parent` is in use, in\n+\twhich case `first-parent` is the default.\n +\n---diff-merges=(off|none):::\n---no-diff-merges:::\n+The following formats are supported:\n++\n+--\n+off, none::\n \tDisable output of diffs for merge commits. Useful to override\n \timplied value.\n +\n---diff-merges=on:::\n---diff-merges=m:::\n--m:::\n-\tThis option makes diff output for merge commits to be shown in\n-\tthe default format. `-m` will produce the output only if `-p`\n-\tis given as well. The default format could be changed using\n-\t`log.diffMerges` configuration parameter, which default value\n+on, m::\n+\tMake diff output for merge commits to be shown in the default\n+\tformat. The default format could be changed using\n+\t`log.diffMerges` configuration variable, whose default value\n \tis `separate`.\n +\n---diff-merges=first-parent:::\n---diff-merges=1:::\n-\tThis option makes merge commits show the full diff with\n-\trespect to the first parent only.\n+first-parent, 1::\n+\tShow full diff with respect to first parent. This is the same\n+\tformat as `--patch` produces for non-merge commits.\n +\n---diff-merges=separate:::\n-\tThis makes merge commits show the full diff with respect to\n-\teach of the parents. Separate log entry and diff is generated\n-\tfor each parent.\n+separate::\n+\tShow full diff with respect to each of parents.\n+\tSeparate log entry and diff is generated for each parent.\n +\n---diff-merges=remerge:::\n---diff-merges=r:::\n---remerge-diff:::\n-\tWith this option, two-parent merge commits are remerged to\n-\tcreate a temporary tree object -- potentially containing files\n-\twith conflict markers and such. A diff is then shown between\n-\tthat temporary tree and the actual merge commit.\n+combined, c::\n+\tShow differences from each of the parents to the merge\n+\tresult simultaneously instead of showing pairwise diff between\n+\ta parent and the result one at a time. Furthermore, it lists\n+\tonly files which were modified from all parents.\n++\n+dense-combined, cc::\n+\tFurther compress output produced by `--diff-merges=combined`\n+\tby omitting uninteresting hunks whose contents in the parents\n+\thave only two variants and the merge result picks one of them\n+\twithout modification.\n++\n+remerge, r::\n+\tRemerge two-parent merge commits to create a temporary tree\n+\tobject--potentially containing files with conflict markers\n+\tand such. A diff is then shown between that temporary tree\n+\tand the actual merge commit.\n +\n The output emitted when this option is used is subject to change, and\n so is its interaction with other options (unless explicitly\n documented).\n-+\n---diff-merges=combined:::\n---diff-merges=c:::\n--c:::\n-\tWith this option, diff output for a merge commit shows the\n-\tdifferences from each of the parents to the merge result\n-\tsimultaneously instead of showing pairwise diff between a\n-\tparent and the result one at a time. Furthermore, it lists\n-\tonly files which were modified from all parents. `-c` implies\n-\t`-p`.\n-+\n---diff-merges=dense-combined:::\n---diff-merges=cc:::\n---cc:::\n-\tWith this option the output produced by\n-\t`--diff-merges=combined` is further compressed by omitting\n-\tuninteresting hunks whose contents in the parents have only\n-\ttwo variants and the merge result picks one of them without\n-\tmodification. `--cc` implies `-p`.\n+--\n \n --combined-all-paths::\n \tThis flag causes combined diffs (used for merge commits) to\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 2a66cf888074..9b7ec96e767a 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -124,7 +124,7 @@ Note that unless one of `--diff-merges` variants (including short\n will not show a diff, even if a diff format like `--patch` is\n selected, nor will they match search options like `-S`. The exception\n is when `--first-parent` is in use, in which case `first-parent` is\n-the default format.\n+the default format for merge commits.\n \n :git-log: 1\n :diff-merges-default: `off`\n-- \n2.25.1\n\n"},{"id":"482870","messageId":"20231009160535.236523-4-sorganov@gmail.com","threadId":"60213","inReplyTo":"20231009160535.236523-1-sorganov@gmail.com","subject":"[PATCH v4 3/3] completion: complete '--dd'","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-10-09T16:05:35Z","receivedAt":"2023-10-09T16:06:56Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"'--dd' only makes sense for 'git log' and 'git show', so add it to\n__git_log_show_options which is referenced in the completion for these\ntwo commands.\n\nSigned-off-by: Sergey Organov \n---\n contrib/completion/git-completion.bash | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash\nindex 133ec92bfae7..ca4fa39f3ff8 100644\n--- a/contrib/completion/git-completion.bash\n+++ b/contrib/completion/git-completion.bash\n@@ -2042,7 +2042,7 @@ __git_log_shortlog_options=\"\n \"\n # Options accepted by log and show\n __git_log_show_options=\"\n-\t--diff-merges --diff-merges= --no-diff-merges --remerge-diff\n+\t--diff-merges --diff-merges= --no-diff-merges --dd --remerge-diff\n \"\n \n __git_diff_merges_opts=\"off none on first-parent 1 separate m combined c dense-combined cc remerge r\"\n-- \n2.25.1\n\n"},{"id":"482876","messageId":"CABPp-BGL_QzRd3mRhSF7rHYNA4pFWfKPA+UuZDODFgEv-1BHhA@mail.gmail.com","threadId":"60213","inReplyTo":"xmqqmswv3p11.fsf@gitster.g","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-10-09T17:04:28Z","receivedAt":"2023-10-09T17:04:52Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Fri, Oct 6, 2023 at 11:49 PM Junio C Hamano wrote:\n>\n> Junio C Hamano writes:\n>\n> > Elijah Newren writes:\n> >\n> >> In my opinion, --remerge-diff does this better; wouldn't we want a\n> >> ...\n> > Between -c and --cc, I do not think there is anything that makes us\n> > favor -c over --cc. While the algorithm to decide which hunks out\n> > of -c's output to omit was being polished, comparison with -c served\n> > a good way to give baseline, but once --cc has become solid, I do\n> > not think I've used -c myself.\n\nPerhaps, then, the user manual should either omit -c, or recommend\nusers use --cc instead?\n\n> > I personally find that a very trivial merge resolution is far easier\n> > to read with --cc than --remerge-diff, the latter being way too\n> > verbose.\n\nAh, indeed, for those that know the --cc output format well (it takes\na bit to figure out for newcomers), your example demonstrates this\nnicely. Thanks.\n\n> > Also, --cc and -c should work inside a read-only repository where\n> > you only have read access to. If remerge needs to write some\n> > objects to the repository, then you'd need some hack to give a\n> > writable object store overlay via the alternate odb mechanism, or\n> > something, right?\n\nWell, it does use a temporary object store with the alternate odb\nmechanism already, but I don't think there's any code to allow the\nuser to input the location for the temporary store, and thus we'd\nprobably attempt to write it underneath the same read-only directory.\nSo, yes, read-only repositories would likely be problematic for\n--remerge-diff.\n\nHowever, are read-only repositories worth mentioning in the documentation here?\n\n> Well, the above did not come out as well as I intended, as I forgot\n> to prefix it with something I thought was obvious from what I said\n> in the recent discussion in the earlier iteration of this topic,\n> where I said that it would be \"--remerge-diff\", if I were to pick an\n> option that is so useful that it deserves short and sweet single\n> letter. Narutally, it came after we gained experience with \"--cc\",\n> so it would be surprising if it did worse. Just like it is natural\n> to expect that \"--cc\" would give more useful output than \"-m -p\"\n> that predates everybody else.\n>\n> In short, I would say \"--remerge-diff\" would give output that is the\n> easiest to grok among the three modern variants to show the changes\n> a merge introduces.\n>\n> The above two cases, where I said cc does better than remerge-diff,\n> were meant as _exceptions_ for that general sentiment.\n\nThanks, this is useful. This does make me wonder, though: Should we\nperhaps guide users as to what we recommend (and recommend against) in\nthis documentation?\n\nIf we have lots of options and they all shine on different usecases,\nit makes sense to just provide a long list of possibilities for users.\nBut if we generally feel that one is entirely supplanted by another\n(e.g. -c by --cc) it seems beneficial to mention that, and if we\ngenerally feel that one will often be clearer or more useful than the\nothers (e.g. --remerge-diff), it seems beneficial to recommend it.\nThoughts?\n\nAlso, perhaps this would be best to include in a follow-up series (as\nit appears from Sergey's latest iteration that we are leaving other\ntweaks for a later series anyway), if we do decide we want to do it...\n"},{"id":"482899","messageId":"xmqqmswry36z.fsf@gitster.g","threadId":"60213","inReplyTo":"20231009160535.236523-1-sorganov@gmail.com","subject":"Re: [PATCH v4 0/3] diff-merges: introduce '--dd' option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-09T20:02:28Z","receivedAt":"2023-10-09T20:02:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov writes:\n\n> Updates in v4:\n>\n> * Removed \"(which see)\" reference from documentation that caused\n> confusion.\n>\n> * Removed explanation why it's --dd and not simply -d from commit\n> message.\n>\n> * Refined --remerge-diff short description according to Junio and\n> Elijah comments.\n>\n> * Added explanation of --dd purpose.\n>\n> * Fixed style and syntax of \"on,m::\" description.\n\nWill replace. Thanks.\n\n"},{"id":"482943","messageId":"xmqqa5srwcik.fsf@gitster.g","threadId":"60213","inReplyTo":"CABPp-BGL_QzRd3mRhSF7rHYNA4pFWfKPA+UuZDODFgEv-1BHhA@mail.gmail.com","subject":"Re: [PATCH v3 1/3] diff-merges: improve --diff-merges documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-10T00:24:03Z","receivedAt":"2023-10-10T00:24:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n>> >> In my opinion, --remerge-diff does this better; wouldn't we want a\n>> >> ...\n>> > Between -c and --cc, I do not think there is anything that makes us\n>> > favor -c over --cc. While the algorithm to decide which hunks out\n>> > of -c's output to omit was being polished, comparison with -c served\n>> > a good way to give baseline, but once --cc has become solid, I do\n>> > not think I've used -c myself.\n>\n> Perhaps, then, the user manual should either omit -c, or recommend\n> users use --cc instead?\n\nI do not think I'd miss \"-c\", but I do not know about others.\n\n>> > I personally find that a very trivial merge resolution is far easier\n>> > to read with --cc than --remerge-diff, the latter being way too\n>> > verbose.\n>\n> Ah, indeed, for those that know the --cc output format well (it takes\n> a bit to figure out for newcomers), your example demonstrates this\n> nicely. Thanks.\n\nYup. And newcomers would take a bit to figure out remerge-diff\noutput, too, so my answers were written from the \"nobody will stay\nnewcomer forever. now once they get proficient enough, which ones\nare good for them\" viewpoint.\n"},{"id":"482947","messageId":"xmqqo7h7urgd.fsf@gitster.g","threadId":"60213","inReplyTo":"CABPp-BFsrt0zS3NHsVAyOSW6vGioe8Z-iN2M3_JNBpP2fWVq9g@mail.gmail.com","subject":"[silly] worldview documents?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-10T02:44:18Z","receivedAt":"2023-10-10T02:44:32Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n>> [Footnote]\n>> ...\n>\n> Thanks for writing this up. In the past, I didn't know how to put\n> into words why I didn't particularly care for this mode. You explain\n> it rather well.\n\nI am glad it helped non-zero number of people.\n\nIt probably owes big to my failing, but because we strongly view it\na virtue not to be opinionated, we have many discrete tools and\nfeatures that can be used in combination to support a workflow well,\neven when some of these tools and features are not useful for a\ndifferent workflow. It indeed is a good thing to be flexible and to\nsupport different workflows well, and we tend not to single out a\nworkflow among many and advocate it, but because our documentation\nlacks description of major possible workflows, what their underlying\nphilosophies and their strengths are, how some of our tools and\nfeatures support them, and why some others are not good fit. Being\ngiven a toolbox with too many tools without being taught how they\nare to be used together and for what purpose may be a fun puzzle to\nfigure out for tinkerers, but when you have a problem to solve and\ntinkering is not your main focus, which is true for most people, it\nis not fun. \n\nIn short, in pursuit of not to be opinionated, we fail to give the\nreaders best current practices. The first place to start rectifying\nit might be to have some write-ups for various major workflows and\nthe worldview behind them. The importance given to first-parenthood\noffers two quite different worldviews that affects the choice of\ntools (e.g. \"merge --no-ff\", \"checkout origin/master && merge mine\n&& branch -f mine\" aka \"reverse merge\").\n\nI suspect that this also relates to your \"would --cc be totally\nunnecessary now we have --remerge-diff?\" as well. What kind of\nconflicts are interesting highly depends on what you are looking\nfor, which in turn is influenced by the workflow employed by the\nproject and what role you are playing in it.\n"},{"id":"482985","messageId":"CAJoAoZk+RjPWrSUyTLoP_La216Se_tgvBpri-zOZntFzUh4_1g@mail.gmail.com","threadId":"60213","inReplyTo":"xmqqo7h7urgd.fsf@gitster.g","subject":"Re: [silly] worldview documents?","fromName":"Emily Shaffer","fromEmail":"nasamuffin@google.com","sentAt":"2023-10-10T14:58:06Z","receivedAt":"2023-10-10T14:58:33Z","isPatch":false,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Mon, Oct 9, 2023 at 7:44 PM Junio C Hamano wrote:\n>\n> Elijah Newren writes:\n>\n> >> [Footnote]\n> >> ...\n> >\n> > Thanks for writing this up. In the past, I didn't know how to put\n> > into words why I didn't particularly care for this mode. You explain\n> > it rather well.\n>\n> I am glad it helped non-zero number of people.\n>\n> It probably owes big to my failing, but because we strongly view it\n> a virtue not to be opinionated, we have many discrete tools and\n> features that can be used in combination to support a workflow well,\n> even when some of these tools and features are not useful for a\n> different workflow. It indeed is a good thing to be flexible and to\n> support different workflows well, and we tend not to single out a\n> workflow among many and advocate it, but because our documentation\n> lacks description of major possible workflows, what their underlying\n> philosophies and their strengths are, how some of our tools and\n> features support them, and why some others are not good fit. Being\n> given a toolbox with too many tools without being taught how they\n> are to be used together and for what purpose may be a fun puzzle to\n> figure out for tinkerers, but when you have a problem to solve and\n> tinkering is not your main focus, which is true for most people, it\n> is not fun.\n>\n> In short, in pursuit of not to be opinionated, we fail to give the\n> readers best current practices. The first place to start rectifying\n> it might be to have some write-ups for various major workflows and\n> the worldview behind them.\n\nI completely agree with you. The #1 conversation I have with friends\nwho are new to Git is figuring out which of the major workflows they\nshould use, and what are the drawbacks and benefits. And how to\ndiagnose based on the existing commit history, review tool in use, etc\nwhich one is used by their peers. Having this documented somewhere -\nmaybe in Pro Git book, maybe in manpage - would be hugely useful. I\ncould envision a diagram of a sample commit history, and \"if it\nalready looks like this or you want it to look like this, your\nworkflow should be blah\" and finally a list of some drawbacks,\nbenefits, and warnings about what to avoid in that workflow. Plus,\nperhaps, many shout-outs to `git reflog` for fixing when you\nmisunderstood and made a mess. (that's the #2 conversation I have :) )\n\n> The importance given to first-parenthood\n> offers two quite different worldviews that affects the choice of\n> tools (e.g. \"merge --no-ff\", \"checkout origin/master && merge mine\n> && branch -f mine\" aka \"reverse merge\").\n>\n> I suspect that this also relates to your \"would --cc be totally\n> unnecessary now we have --remerge-diff?\" as well. What kind of\n> conflicts are interesting highly depends on what you are looking\n> for, which in turn is influenced by the workflow employed by the\n> project and what role you are playing in it.\n"}]}