Re: [PATCH 10/14] format-patch: add --range-diff option to embed diff in cover letter

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jul 25, 2018, 19:30 UTC
Message-ID: <CAPig+cS-haNwJha44gncB9PrXRPcEPuqDVGLgKii29h=abq6sA@mail.gmail.com>
In-Reply-To: <xmqqva93usud.fsf@gitster-ct.c.googlers.com>

On Wed, Jul 25, 2018 at 1:29 PM Junio C Hamano <gitster@pobox.com> wrote:

> A few random thoughts.
>
>  * I find it somewhat disturbing that use of dash is inconsistent
>    between "--interdiff=<arg>" and "--range-diff=<arg>".

I went with the common spellings we've seen on the mailing lists. "Interdiff", in particular, seems well established. "Range-diff" is new, so we don't have much data other than what we saw during the discussion when renaming git-branch-diff, and, of course, git-branch-diff itself is hyphenated. Another consideration: "inter" is a prefix, whereas "range" stands on its own.

I don't have a super strong opinion, as I'm used to both the hyphenated name (from discussion and the command name itself), and the unhyphenated name ("rangediff" was my local branch name). I'm open to opinions.

We probably wouldn't want to do so, but another possibility is to recognize both --range-diff and --rangediff.

>  * Perhaps "--interdiff=<previous> --range-diff" may be a possible
>    way to say "use the same <previous> and show both"?  Do we want
>    "--range-diff=<previous> --interdiff" to mean the same two
>    meta-diff but shown in different order?

That's not at all a bad shorthand. I like it better than the "--all-kinds-of-diff=<rev>" mentioned earlier. We don't need to make a decision for this series since such functionality can be added later.

The order of specification of the two options affecting the order of output is also an interesting idea. We may want to decide that before graduating this topic.

Show 7 quoted lines

>  * Do we expect that we may find a third-kind of "meta-diff" that
>    sits next to interdiff and range-diff in the future?  I *think*
>    two separate options "--interdiff=..." and "--range-diff=..." is
>    still a good way forward, and we'd add "--frotzdiff=..." when
>    such a third-kind of "meta-diff" turns out to be useful, without
>    fearing proliferation of options, and that would be OK, but I am
>    just thinking aloud to see if other people have better ideas.

I did consider other approaches, such as a more generic option. For example, --embed=range-diff:<prev>. I also considered supporting more complex use-cases. For instance, git-range-diff itself accepts the two ranges in several formats ("a..b c..d" or "x...z" or "i j k"), plus the creation-factor can be tweaked, so I weighed ways of incorporating all that detail into the single argument to --range-diff.

However, those are all difficult to use (onerous to type and remember) and difficult to document. Thus, I opted for simplicity of individual, straight-forward options (--interdiff, --range-diff, --creation-factor), which are easy to type, remember, and document.

We may want to revisit this later if git-format-patch grows additional similar options.