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

[Elijah Newren <newren@gmail.com>]

Hi Denton,

Thanks for working on this.  Some thoughts...

On Sun, Mar 17, 2019 at 4:09 AM Denton Liu <liu.denton@gmail.com> 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.

Yes, there were multiple people who commented that they liked to
copy-paste the "A..B" output from fetch/pull in combination with diff
and log (even though one suggested that this gave the wrong output and
what they really wanted was "diff A...B").

However, "removal of functionality" isn't the only form of
deprecation/warning.  Updating the manpage is another one which you
implemented, but I'd like to suggest yet another: Prefix the diff with
a warning message, e.g.

"WARNING: You ran 'git diff A..B' (which means the same thing as 'git
diff A B').  Many users confuse 'git diff A..B' and 'git diff A...B'.
Please see 'git diff --help' for more details."

Having extra text (e.g. commit message or warning) at the beginning of
the diff does not prevent tools like patch(1) or git-apply(1) from
successfully applying it, it still makes sense to humans (and who as
an added bonus happen to be really good at filtering out common
messages if they do encounter them more than a few times), and gives
us a chance in the future to figure out how to potentially extend the
message to make it a deprecation warning and/or provide details about
how to change the behavior of '..' to either be an error or behave
like triple dots or just not warn.


Elijah