Re: [PATCH] git-diff.txt: prefer not using <commit>..<commit>

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Mar 18 2019, Elijah Newren wrote:

> On Sun, Mar 17, 2019 at 6:41 AM Ævar Arnfjörð Bjarmason
> <avarab@gmail.com> wrote:
>> On Sun, Mar 17 2019, Denton Liu wrote:
>>
>> > diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
>> > index 72179d993c..10c7a2220c 100644
>> > --- a/Documentation/git-diff.txt
>> > +++ b/Documentation/git-diff.txt
>> > @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.
>> >
>> >  'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
>> >
>> > -     This is synonymous to the previous form.  If <commit> on
>> > +     This is synonymous to the previous form.  However,
>> > +     users should prefer the previous form over this form
>> > +     as this form may be more confusing due to the same
>> > +     notation having a logically conflicting meaning in
>> > +     linkgit:git-rev-list[1]-ish commands.  If <commit> on
>> >       one side is omitted, it will have the same effect as
>> >       using HEAD instead.
>>
>> I think we're better off just consistently recommending "A..B" instead
>> of "A B" and "fixing" any occurrence of the latter to the
>> former. I.e. not taking this patch & going in the other direction.
>>
>> As noted in the thread you linked we'll always need ".." when one side
>> is "HEAD" implicitly, and that's a really common case.
>
> By "really common" do you simply mean it is used by enough people that
> it should be supported, or are you trying to claim something about
> it's relative usage compared to "diff A B"?
>
>> So as confusing as the whole ".." v.s. "..." is in diff v.s. log I think
>> we're worse off with "A B", since we'll *still* need to document the
>> likes of "A.." and how that differs from log "A.." or "A...".
>>
>> So sometimes using the whitespace form for two revs and then the ".."
>> when we just have one side makes things more confusing, not less. The
>> reader will be left having to juggle more complexity in their head, not
>> less.
>
> Here I think you are implying that "A.." or "..A" is somehow on a
> similar magnitude of usage as "A B".  Is that accurate?  If that
> reflected real-world usage, I would be more inclined to agree with
> your course of action, but I can't fathom them having similar usage
> rates.  Personally, I don't think I've ever seen any user use "A.." or
> "..A" (well, except me), and only rarely even use "A..B"; with users I
> have worked with and supported and taught, I'd guess "diff A B" is
> used far more (at least an order of magnitude more) than any other
> form, and that only some of them and only occasionally want to use
> anything else, such as diffing against a merge base.
>
> This whole topic came up again, IMO, because for the occasional
> usecase of diffing against a merge-base, people's intuition leads them
> to '..' instead of '...', and we wanted to fix or help avoid that
> problem.  To me, your solution sounds like you want to instead embrace
> the confusion: force people to deal with it early and often so that
> they become trained on it and can articulate the differences between
> '..' and '...' for both diff and log.  Is that accurate, or am I
> misunderstanding/mis-stating your strategy?

Some of this thread's confusing, and on re-reading I see my reply hasn't
helped much.

To clarify. There's at least these things to consider:

1. What should the semantics of .. or ... be?
2. What semantics (regardless of syntax) should we recommend for common cases?
3. Depending on #1 and #2, can we make our docs less confusing?

My opinion:

1. I'd ideally like to switch the semantics of ".." and "...". I don't
   think anyone argues that it would be a bad thing in theory if we'd
   started out that way, Whether it's worth switching now is another
   matter.

   Junio chimed in in <xmqqmum0h88n.fsf@gitster-ct.c.googlers.com>
   saying he's not for it, so I'm assuming it's out for now.

2. I agree that we should generally recommend what's now "..." instead
   of "..", whatever the syntax is to invoke that.

3. And now, coming to the point I was trying to make. Assuming we'd like
   to go for #2 as I noted, and switching them around as in #1 is a
   no-go, what syntax should we prefer for "X..Z", aka. "X Y"?

   I think to reduce doc confusion we'd be better of using ".."
   consistently over the whitespace form, since we're going to need to
   show diffs with HEAD on one side. Using either "@" or "HEAD" there is
   more verbose.

   So yeah, I guess I am in a narrow sense advocating for embracing the
   confusion. I'd rather not have it in the first place, but since we
   seem stuck with it let's at least stick with and recommend *one*
   syntax for that confusion, and pick the one we can consistently use
   for 100% of our examples.

Anecdotally I've seen ".." in all forms be *way* more common among
users, even though if you sat them down and explained to them what it
does v.s. "..." they'd usually say they wanted the latter.

I did some brief scraping of .bash_history on one of our big shared
servers just now that has a lot of users (100-200) using git for daily
development. I've got many pages of things like "@{u}..",
"<tag1>..<tag2>", "<rev>.. -- <path>" etc. against just a couple of uses
of "...". The "<rev1> <rev2>" form gets a bit of use, but maybe 1/2 of
"..".