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

[Junio C Hamano <gitster@pobox.com>]

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.