"Johannes Schindelin via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > * Disallowed the no-arg --diff-merges option (because --diff-merges > requires an argument). Yup, I was happy to see it in the range-diff output, because I was wondering where the optarg came from in the initial submission. > +--diff-merges=<format>:: > + Instead of ignoring merge commits, generate diffs for them using the > + corresponding `--diff-merges=<format>` option of linkgit:git-log[1], > + and include them in the comparison. > ++ > +Note: In the common case, the `first-parent` mode will be the most natural one > +to use, as it is consistent with the idea that a merge is kind of a "meta > +patch", comprising all the merged commits' patches into a single one. I'll let you and Elijah figure out the best phrasing around here, including whether we recommend only first-parent or give other options. For me personally, I find that use of `first-parent` here is consistent with the mindset of those users who prefer to read "git log --first-parent -p", and to a smaller degree, those who use squash merges. To them, a merge is merely bringing in lots of changes into the mainline as a single unit, and other than that these lots of changes are broken out for finer grained inspection if/when they wanted to, they prefer to treat the changes brought in by merges just like a single-parent commit. And from that point of view, (1) reordering the changes inside the side branch is immaterial for the purpose of talking about the result, the net effect the merged topic makes to the mainline, and (2) dropping or adding new changes to the side branch is treated just like a newer iteration of a single parent commit having fewer or more changes. So it is very natural that first-parent helps to make the world view very simplistic, and more readable range-diff is all about how you can present the two iterations in a simple and flattened form. There _may_ need a tweak of the matching algorithm to allow the "same" merge on both sides to match, even if they diverge a lot, though. A range-diff that pairs a merge in the previous iteration with a single patch in the updated iteration may be hard to read.
