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

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

[Martin Ågren]

Going through the doc-diff between v2.27.0 and v2.28.0-rc0, I only
noticed some small things related to b7e10b2ca2 ("Documentation: usage
for diff combined commits", 2020-06-12). The first issue might not be
something a lot of people would stumble on, but the second one could
probably trip someone up.

All feedback welcome.

Martin

Martin Ågren (2):
  git-diff.txt: don't mark required argument as optional
  git-diff.txt: reorder possible usages

 Documentation/git-diff.txt | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

-- 
2.28.0.rc0

[PATCH 1/2] git-diff.txt: don't mark required argument as optional

[Martin Ågren]

Commit b7e10b2ca2 ("Documentation: usage for diff combined commits",
2020-06-12) modified the synopsis by adding an optional "[<commit>...]"
to

  'git diff' [<options>] <commit> <commit> [--] [<path>...]

to effectively add

  'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]

as another valid invocation. Which makes sense.

Further down, in the description, it left the existing entry for

  'git diff' [<options>] <commit> <commit> [--] [<path>...]

intact and added a new entry on

  'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]

where it says that "[t]his form is to view the results of a merge
commit" and details how "the first listed commit must be the merge
itself". But one possible instantiation of this form is `git diff
<commit> <commit>` for which the added text doesn't really apply.

Remove the brackets so that we lose this overlap between the two
descriptions. We can still use the more compact representation in the
synopsis.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-diff.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 1018110ddc..c613e71ca4 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -69,7 +69,7 @@ files on disk.
 	one side is omitted, it will have the same effect as
 	using HEAD instead.
 
-'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
+'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::
 
 	This form is to view the results of a merge commit.  The first
 	listed <commit> must be the merge itself; the remaining two or
-- 
2.28.0.rc0

Re: [PATCH 1/2] git-diff.txt: don't mark required argument as optional

[Junio C Hamano]

Martin Ågren <martin.agren@gmail.com> writes:

> Commit b7e10b2ca2 ("Documentation: usage for diff combined commits",
> 2020-06-12) modified the synopsis by adding an optional "[<commit>...]"
> to
>
>   'git diff' [<options>] <commit> <commit> [--] [<path>...]
>
> to effectively add
>
>   'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]
>
> as another valid invocation. Which makes sense.
>
> Further down, in the description, it left the existing entry for
>
>   'git diff' [<options>] <commit> <commit> [--] [<path>...]
>
> intact and added a new entry on
>
>   'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
>
> where it says that "[t]his form is to view the results of a merge
> commit" and details how "the first listed commit must be the merge
> itself". But one possible instantiation of this form is `git diff
> <commit> <commit>` for which the added text doesn't really apply.
>
> Remove the brackets so that we lose this overlap between the two
> descriptions. We can still use the more compact representation in the
> synopsis.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/git-diff.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 1018110ddc..c613e71ca4 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -69,7 +69,7 @@ files on disk.
>  	one side is omitted, it will have the same effect as
>  	using HEAD instead.
>  
> -'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
> +'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::

Thanks.

>  
>  	This form is to view the results of a merge commit.  The first
>  	listed <commit> must be the merge itself; the remaining two or

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

[Martin Ågren]

The description of `git diff` goes through several different invocations
(numbering added by me):

  1. git diff [<options>] [--] [<path>...]
  2. git diff [<options>] --no-index [--] <path> <path>
  3. git diff [<options>] --cached [<commit>] [--] [<path>...]
  4. git diff [<options>] <commit> [--] [<path>...]
  5. git diff [<options>] <commit> <commit> [--] [<path>...]
  6. git diff [<options>] <commit>..<commit> [--] [<path>...]
  7. git diff [<options>] <commit> <commit>... <commit> [--] [<path>...]
  8. git diff [<options>] <commit>...<commit> [--] [<path>...]

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.

As a further complication, after b7e10b2ca2 we also have some potential
confusion around "the '..' notation". The "..[.]" in items 6 and 8 are
part of the rev notation, whereas the "..." in item 7 is manpage
language for "one or more".

Move item 6 down, i.e., to between 7 and 8, to restore the ordering.
Because 6 refers to 5 ("synonymous to the previous form") we need to
tweak the language a bit.

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.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-diff.txt | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index c613e71ca4..727f24d16e 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -63,12 +63,6 @@ files on disk.
 	This is to view the changes between two arbitrary
 	<commit>.
 
-'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
-
-	This is synonymous to the previous form.  If <commit> on
-	one side is omitted, it will have the same effect as
-	using HEAD instead.
-
 'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::
 
 	This form is to view the results of a merge commit.  The first
@@ -78,6 +72,13 @@ files on disk.
 	For instance, if `master` names a merge commit, `git diff master
 	master^@` gives the same combined diff as `git show master`.
 
+'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
+
+	This is synonymous to the earlier form (without the "..") for
+	viewing the changes between two arbitrary <commit>.  If <commit> on
+	one side is omitted, it will have the same effect as
+	using HEAD instead.
+
 'git diff' [<options>] <commit>\...<commit> [--] [<path>...]::
 
 	This form is to view the changes on the branch containing
-- 
2.28.0.rc0

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

[Chris Torek]

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

> 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

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

[Martin Ågren]

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

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

[Junio C Hamano]

Chris Torek <chris.torek@gmail.com> writes:

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

Yes, the proposed patch is an improvement, but I agree that "find
the last two that use dots" was indeed what I meant when I wrote
0c783f66 (Documentation/git-diff: A..B and A...B cannot take
tree-ishes, 2007-08-28).

But upon reading it again now, I am not sure it makes sense in the
first place.

    git diff seen^^{tree}..seen^{tree}

uses <tree> (not commit) in the form that uses '..' notation, and it
just works fine.  What does require commit because it depends on
having a history to compute merge base between two objects given
from the command line is the form that uses '...' notation.

    git diff seen^1...seen^2

would be "what did the side branch merged at the tip of seen do
since it forked?" and should look similar to "git diff seen^ seen",
but it cannot use tree objects for obvious reasons

    git diff seen^1^{tree}...seen^2^{tree}

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

I am not sure why it is so important to be able to omit HEAD in the
first place.  I do not think using two-dot form is an offence severe
enough to deserve an extra warning or deprecation notice, but using
the "range" notation when you meant two endpoints is a notation that
confuses uninitiated needlessly and showing it to new people is a
disservice.  "This notation does not make logical sense, but we keep
using it as users, and we keep accepting it as tool makers, purely
for convenience" has been and will be the attitude I'd take towards
the "git diff A..B" syntax---it was a mistake we made when we were
still young ;-)

cf. https://bit.ly/3eBcyZa