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

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 2339 bytes --]

On Thu, May 09, 2024 at 09:47:49PM -0700, Junio C Hamano wrote:
> 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.

I'll leave these for a future iteration for now given that there is more
work that needs to be done in this context.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]