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@xxxxxxxxx> --- 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
