On Sun, Mar 17 2019, Duy Nguyen wrote: > 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. Sure, and if we're going to change our docs to consistently use @ at either side of such ranges instead of the empty string for "HEAD" I think that's worth discussing if the goal is to get rid of ".." for "diff". I'm commenting on the in-between state being more confusing to users, which is as far as this patch gets us. >> 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.
