Re: git format-patch --range-diff bug?

[Eric Sunshine <sunshine@sunshineco.com>]

On Thu, Nov 12, 2020 at 2:00 PM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > [...] the best "fix" likely would be for `git format-patch --range-diff` to
> > error out when it sees a 3-dot range.
>
> And possibly rename the option.  Giving "--range-diff=<prev>" is not
> an instruction to run "git range-diff <prev>", so it is clear that
> the option is misnamed.
>
> It probably should have been "--[no-]range-diff" boolean that
> controls if we add the range-diff from the previous, whose default
> may be affected by the user of the "-v$n" option, plus another
> option that gives where to find the "previous series", whose
> presence probably trigger "--range-diff" implicitly, or something
> like that.
>
> And the option whose value we are having problem with is exactly
> that "--previous-series=<prev>" option.

You may be right that, due to the name similarity, some people
misinterpret --range-diff as providing one-to-one parity with the `git
range-diff` command, but that was never the intention (as was
discussed during review). Instead, the intention all along was only to
make it easy to embed range-diffs in `git format-patch` output with a
simple and concise invocation, and only for common cases. For
instance, it is quite common for v2 to share a common base with v1, in
which case `git format-patch -v2 --range-diff=v1 <base>` would be
sufficient (when v2 is the checked-out branch). Anything more complex
can be achieved by utilizing `git range-diff` directly; for instance:
`git range-diff {complexity} >>0000-cover-letter.patch`

As discussed during review, I had considered more complex invocation
possibilities for `git format-patch` but ended up rejecting them and
opting instead for simplicity since `git range-diff` itself is a
suitable escape hatch for accomplishing complex cases not handled by
the intentionally simplistic --range-diff option. Thus, I'm hesitant
to go in a direction which adds more complexity to the `git
format-patch` invocation, thus making it more difficult to use
range-diff with `git format-patch`.