[PATCH] BreakingChanges: say that `git diff X..Y` syntax will be removed in 3.0

From: Martin von Zweigbergk via GitGitGadget <gitgitgadget@gmail.com>
Date: Oct 15, 2025, 22:07 UTC
Message-ID: <pull.1989.git.1760566054455.gitgitgadget@gmail.com>

From: Martin von Zweigbergk <martinvonz@google.com>

The `git diff X..Y` syntax is quite misleading because it looks like it shows the diff of the commits in the X..Y range but it actually shows the diff from X to Y. IMO, if that syntax is supported, it should show a diff from the merge base of X and Y to Y. I hope Git 3.0 is a good time to remove support for the current syntax and semantics. Then we can perhaps add the syntax back later with less surprising semantics.

Signed-off-by: Martin von Zweigbergk <martinvonz@google.com>
---
    BreakingChanges: say that git diff X..Y syntax will be removed in 3.0

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1989%2Fmartinvonz%2Fmz%2Fwtmnpolouvvz-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1989/martinvonz/mz/wtmnpolouvvz-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1989

 Documentation/BreakingChanges.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index 90b53abcea..93fb968840 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -114,6 +114,10 @@ applications and forges.
 +
 There is no plan to deprecate the "sha1" object format at this point in time.
 +
+Support for "git diff X..Y" syntax will be removed. Use "git diff X Y" instead.
+This will open up the syntax for a more consistent interpretation of
+"git diff $(git merge-base X Y) Y".
++
 Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 <20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
 <CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.

base-commit: 143f58ef7535f8f8a80d810768a18bdf3807de26

-- 
gitgitgadget