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

[Denton Liu <liu.denton@gmail.com>]

The documentation used to consider

	git diff <commit> <commit>

and

	git diff <commit>..<commit>

to be equal counterparts. However, rev-list-ish commands also use the
<commit>..<commit> notation, but in a logically conflicting manner which
was confusing for some users (including me!).

Deprecating the notation entirely is not really an option because it
would be an arduous process without much end-value. In addition, there
are some valid use-cases that we don't want to break.

Document the preference of the first form so that future confusion can
be minimised.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---

Thanks all on your feedback on the discussion thread[1]! I opted for
just the documentation-only route so we don't break any valid use-cases.

[1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/

 Documentation/git-diff.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 72179d993c..10c7a2220c 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.
 
 'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
 
-	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.
 
-- 
2.21.0.512.g57bf1b23e1