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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Nov 12, 2020, 20:06 UTC
Message-ID: <CAPig+cTeiLDFQD6HDhr-or4F+2POfsMkQ2f0H5ipvi7DCkmLRw@mail.gmail.com>
In-Reply-To: <xmqqblg2jt95.fsf@gitster.c.googlers.com>

On Thu, Nov 12, 2020 at 2:00 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 17 quoted lines

> 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`.