On Sun, Mar 17 2019, Denton Liu wrote: > 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. I think we're better off just consistently recommending "A..B" instead of "A B" and "fixing" any occurrence of the latter to the former. I.e. not taking this patch & going in the other direction. As noted in the thread you linked we'll always need ".." when one side is "HEAD" implicitly, and that's a really common case. So as confusing as the whole ".." v.s. "..." is in diff v.s. log I think we're worse off with "A B", since we'll *still* need to document the likes of "A.." and how that differs from log "A.." or "A...". So sometimes using the whitespace form for two revs and then the ".." when we just have one side makes things more confusing, not less. The reader will be left having to juggle more complexity in their head, not less.
