On Sun, Mar 17, 2019 at 8:41 PM Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> wrote: > > > 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. You could just type " @" instead of "..". And that one is easier to explain. > 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. -- Duy
