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

From: Denton Liu <liu.denton@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Duy Nguyen" <pclouds@gmail.com>,
	"Git Mailing List" <git@vger.kernel.org>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"Andreas Schwab" <schwab@linux-m68k.org>,
	"Elijah Newren" <newren@gmail.com>,
	"Johannes Schindelin" <Johannes.Schindelin@gmx.de>,
	"Johannes Sixt" <j6t@kdbg.org>,
	"Philip Oakley" <philipoakley@iee.org>,
	"Vincent Guittot" <vincent.guittot@linaro.org>,
	"Viresh Kumar" <viresh.kumar@linaro.org>
Subject: Re: [PATCH] git-diff.txt: prefer not using <commit>..<commit>
Date: Mon, 18 Mar 2019 18:12:17 -0700	[thread overview]
Message-ID: <20190319011217.GA20393@dev-l> (raw)
In-Reply-To: <xmqq5zsg3cl6.fsf@gitster-ct.c.googlers.com>

On Mon, Mar 18, 2019 at 03:45:25PM +0900, Junio C Hamano wrote:
> 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.