Re: [PATCH 2/2] git-diff.txt: reorder possible usages

["Martin Ågren" <martin.agren@gmail.com>]

On Tue, 14 Jul 2020 at 00:04, Chris Torek <chris.torek@gmail.com> wrote:
>
> On Mon, Jul 13, 2020 at 12:10 PM Martin Ågren <martin.agren@gmail.com> wrote:
> > It then goes on to say that "all of the <commit> in the above
> > description, except in the last two forms that use '..' notations, can
> > be any <tree>". The "last two" actually refers to 6 and 8. This got out
> > of sync in commit b7e10b2ca2 ("Documentation: usage for diff combined
> > commits", 2020-06-12) which added item 7 to the mix.
>
> Moving this down (as you do in this patch) is the right thing to do,
> but I'll note that formally, the word "that" in "forms that use ..." is
> part of a restrictive clause, so it means "find the last two examples
> that use dots".  (In American English at least, the unrestrictive version
> would be set off with commas, and use "which" instead of "that".)

Thanks, I hadn't read it like that, that makes sense. I'll learn to pay
more attention to the difference between "that" and "which", which(!)
I'm not sure I've fully appreciated before. So if one qualifies the "..
notations" a bit, one might actually achieve something that passes,
language-lawyer-wise, even in light of the two completely different uses
of "..":

 ..., except in the last two forms that use ".." range notations, ...

or, if "the last two forms" doesn't actually add anything,

 ..., except in the forms that use ".." range notations, ...

But I'm not sure that would help users at all, even if we might be able
to say, "well, technically, it's all correct..". ;-) "The last two"
seems more helpful to the reader, although it does carry the risk of
getting outdated.

I'm glad you agree with the move.

> > An added bonus of this commit is that we're trying to steer users away
> > from `git diff <commit>..<commit>` and moving it further down probably
> > doesn't hurt.
>
> Q: Just how hard should we try?  In particular, would it be good to mark
> the two-dot form as deprecated in the documentation?

In [1], Junio seems to be of the opinion that we can't rid ourselves of
it. But yeah, I suppose we could still add something to gently get the
reader to skip that particular paragraph and learn some other diff
syntax or some completely different part of Git instead. The word
"deprecated" seems to mean "old-school" to some and "slated for removal"
to others. Maybe something along the lines of "kept for backwards
compatibility to old habits".

> I anticipate
> objections because it's not possible to omit `HEAD` without using
> the two-dot form.

I always just type "HEAD". With tab-completion, I find it just as easy
to go "<tab>H<tab>" as <tab><bksp>..".

Martin

[1] https://github.blog/2020-04-07-celebrating-15-years-of-git-an-interview-with-git-maintainer-junio-hamano/#if-you-had-a-magic-wand-what-part-of-git-would-you-fix-or-change