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

From: Chris Torek <chris.torek@gmail.com>
Date: Jul 13, 2020, 22:04 UTC
Message-ID: <CAPx1Gve7Sy5BUdRztVoVNVZgdqm14dvD=36eYzLPed5YMQeMEQ@mail.gmail.com>
In-Reply-To: <280943ef56a2a777ab0162b8ec4ba0166cc2095c.1594666410.git.martin.agren@gmail.com>

On Mon, Jul 13, 2020 at 12:10 PM Martin Ågren <martin.agren@gmail.com> wrote:

Show 5 quoted lines

> 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".)

> 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?  I anticipate
objections because it's not possible to omit `HEAD` without using
the two-dot form.

Chris