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

[Denton Liu <liu.denton@gmail.com>]

Hi Elijah,

Sorry for the late reply, I've been mulling over it for the past couple
of days.

On Mon, Mar 18, 2019 at 10:59:56AM -0700, Elijah Newren wrote:
> Hi Denton,
> 
> Thanks for working on this.  Some thoughts...
> 
> On Sun, Mar 17, 2019 at 4:09 AM Denton Liu <liu.denton@gmail.com> wrote:
> >
> > The documentation used to consider
> >
> >         git diff <commit> <commit>
> >
> > and
> >
> >         git diff <commit>..<commit>
> >
> > to be equal counterparts. However, rev-list-ish commands also use the
> > <commit>..<commit> notation, but in a logically conflicting manner which
> > was confusing for some users (including me!).
> >
> > Deprecating the notation entirely is not really an option because it
> > would be an arduous process without much end-value. In addition, there
> > are some valid use-cases that we don't want to break.
> 
> Yes, there were multiple people who commented that they liked to
> copy-paste the "A..B" output from fetch/pull in combination with diff
> and log (even though one suggested that this gave the wrong output and
> what they really wanted was "diff A...B").
> 
> However, "removal of functionality" isn't the only form of
> deprecation/warning.  Updating the manpage is another one which you
> implemented, but I'd like to suggest yet another: Prefix the diff with
> a warning message, e.g.
> 
> "WARNING: You ran 'git diff A..B' (which means the same thing as 'git
> diff A B').  Many users confuse 'git diff A..B' and 'git diff A...B'.
> Please see 'git diff --help' for more details."
> 
> Having extra text (e.g. commit message or warning) at the beginning of
> the diff does not prevent tools like patch(1) or git-apply(1) from
> successfully applying it, it still makes sense to humans (and who as
> an added bonus happen to be really good at filtering out common
> messages if they do encounter them more than a few times), and gives
> us a chance in the future to figure out how to potentially extend the
> message to make it a deprecation warning and/or provide details about
> how to change the behavior of '..' to either be an error or behave
> like triple dots or just not warn.
> 
> 
> Elijah

I was originally planning on doing something like this (by warning to
stderr, but your idea actually gets to the user ;) ). The only thing I'm
worried about for a change like this is that it'll be very controversial
since, as we could see anecdotally, a lot of people have trained
themselves to use the .. form.

In terms of backwards compatibility, I think that there's the
possibility of breaking some scripts by doing this change but we could
mitigate this by detecting if we're outputting to a terminal and only
print the message in that case.

Thanks for the suggestion!

Denton