Re: [RFC PATCH] docs: document upcoming breaking changes

From: Junio C Hamano <gitster@pobox.com>
Date: May 10, 2024, 04:47 UTC
Message-ID: <xmqq1q6aqnm2.fsf@gitster.g>
In-Reply-To: <obsrinbe2uvemiq7q22zrbcln2lmfaukn6lqn7nagrassoicb4@ihwb6ifpjomc>

Justin Tobler <jltobler@gmail.com> writes:

> I would like to see the double dot and triple dot syntax (".." and "...")
> removed from `git-diff(1)` as I think they get easily confused with
> revision ranges.

I tend to agree that the double-dot notation does not need to exist as it can be done with a pair of bog-standard revs. But triple-dot notation needs a replacement syntax that is just as easy to access the feature as the current syntax. After updating a tip of a topic branch,

    $ git diff topic@{1}...topic

is extremely useful (in addition to "git log -p" and the like, of course, with the same range). Also during a conflicted merge

    $ git diff ...MERGE_BASE

and its reverse are very handy. Having to say "--merge-base" is probably a usability regression.

If somebody wants to pursue this further, my recommendation is to treat the two separately.

 * Deprecate and eventually remove double-dot notation.

   - First, notice the use of double-dot notation.
     builtin/diff.c:symdiff_prepare() is the place to do so.  Issue
     a warning about deprecation and possibility of an eventual
     removal, and tell the users to use "diff A B" instead of "diff
     A..B".

   - Gain consensus that the removal is a good idea.  Finish these
     steps long before Git 3.0.

   - Remove the support for A..B.

 * Deprecate and eventually remove triple-dot notation.

   - Introduce a new syntax to allow an access to the "symmetric
     diff" feature just as easily as the current syntax.  Wait for
     a handful releases to gauge its acceptance by the end users.

   - Then notice the use of triple-dot notation.  The place to do
     sois the same builtin/diff.c:symdiff_prepare().  Give a warning
     about deprecation and possibility of an eventual removal, and
     tell the users to use that new syntax we introduced.

   - Gain consensus that the removal is a good idea.  Finish these
     steps long before Git 3.0.

   - Remove the support for A...B.