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

[Elijah Newren <newren@gmail.com>]

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?