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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Sun, Mar 17 2019, Duy Nguyen wrote:

> On Sun, Mar 17, 2019 at 8:41 PM Ævar Arnfjörð Bjarmason
> <avarab@gmail.com> 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@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.
>>
>> 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.