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

From: Denton Liu <[email-masked]>
Date: Mon, 18 Mar 2019 18:12:17 -0700

On Mon, Mar 18, 2019 at 03:45:25PM +0900, Junio C Hamano wrote:
> Duy Nguyen <[email-masked]> writes:
> 
> >> -       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.
> >
> > This is fine as-is. But another option to reduce even more exposure of
> > these forms (both <commit>..[<commit>] and <commit>...[<commit>]) is
> > to delete these forms in "DESCRIPTION" section and add maybe "EXOTIC
> > SYNTAX" (or something) section after "OPTIONS" for just them.
> 
> There is no other way to express A...B (well, short of spelling it
> out as "$(git merge-base A B) B"), so while it makes quite a lot of
> sense to discourage A..B (simply because .. is unnecessary and can
> be replace with a string with one fewer letter in it, namely " "),
> I am not sure if it is wise to throw the three-dot form into the
> same basket.
> 

Perhaps we could add an option to use the base as a comparison,
something like "git diff --compare-base A B" which would mean 
"git diff $(git merge-base A B) B".

If we do this, we could keep feature-parity while deprecating the
confusing "range-notation" for diff. Then, we could possibly move .. and
... into a "RANGE-BASED SYNTAX" section and call it a day.

I now personally don't think that deprecating it in the code (or even
adding a warning) would be worth the effort since the syntax is so
ingrained in common usage. However, I believe that we should encourage
new users to avoid the range-syntax if possible.