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

From: Denton Liu <liu.denton@gmail.com>
Date: Mar 19, 2019, 01:12 UTC
Message-ID: <20190319011217.GA20393@dev-l>
In-Reply-To: <xmqq5zsg3cl6.fsf@gitster-ct.c.googlers.com>

On Mon, Mar 18, 2019 at 03:45:25PM +0900, Junio C Hamano wrote:

Show 23 quoted lines

> Duy Nguyen <pclouds@gmail.com> 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.