range-diff: slight usability problem with mistyped ref

["Kristoffer Haugsbakk" <code@khaugsbakk.name>]

I was using `git range-diff`:[1]

    $ git range-diff main feature-v2 HEAD

And got an error message:

    fatal: need two commit ranges

I intended to give three arguments to the command. I started to wonder
if I maybe had just typed `main feature-v2` (forgot the third
argument). No, it was three arguments.

The problem was that I had mistyped one argument; it was `feature-v3`,
not `feature-v2`.

I thought that this error message was a little misleading or too
generic. I looked at the history of the file (`builtin/range-diff.c`)
and saw this commit: b75747829f (range-diff: optionally accept
pathspecs, 2022-08-26).

Maybe it works better with a `pathspec` marker (`--`)?

    $ git range-diff HEAD main feature-v2 --
    fatal: not a revision: 'feature-v2'

    usage: git range-diff [<options>] <old-base>..<old-tip> <new-base>..<new-tip>
       or: git range-diff [<options>] <old-tip>...<new-tip>
       or: git range-diff [<options>] <base> <old-tip> <new-tip>

Yes it does: `not a revision: 'feature-v2'`.

So I tried to contrast the behavior on the current release with the
behavior on the release before the aforementioned commit.

    $ git checkout v2.40.0
    $ make clean
    $ NO_CURL=true make -j 4
    $ # Misspelled ref `seen` as `seent`
    $ ./bin-wrappers/git range-diff master next seent
    fatal: need two commit ranges

    usage: git range-diff [<options>] <old-base>..<old-tip> <new-base>..<new-tip>
       or: git range-diff [<options>] <old-tip>...<new-tip>
       or: git range-diff [<options>] <base> <old-tip> <new-tip>
    […]

Expected behavior: tell me that `seent` is not a revision.

Actual behavior: generic error message.

But I get a nice error message if I append `--`:

    $ ./bin-wrappers/git range-diff master next seent --
    fatal: not a revision: 'seent'

    usage: git range-diff [<options>] <old-base>..<old-tip> <new-base>..<new-tip>
       or: git range-diff [<options>] <old-tip>...<new-tip>
       or: git range-diff [<options>] <base> <old-tip> <new-tip>

Contrast the behavior on `v2.37.2`, which is one of the tags before
rev. b75747829f (range-diff: optionally accept pathspecs,
2022-08-26).

    $ git checkout v2.37.2
    $ make clean
    $ NO_CURL=true make -j 4
    $ ./bin-wrappers/git range-diff master next seent
    fatal: not a revision: 'seent'

    usage: git range-diff [<options>] <old-base>..<old-tip> <new-base>..<new-tip>
       or: git range-diff [<options>] <old-tip>...<new-tip>
       or: git range-diff [<options>] <base> <old-tip> <new-tip>
    […]

    $ # Tag before rev. b75747829f (range-diff: optionally
    $ # accept pathspecs, 2022-08-26)
    $ git checkout v2.37.2
    $ ./bin-wrappers/git range-diff HEAD master seent
    fatal: ambiguous argument 'HEAD..seent': unknown revision or path not in the working tree.
    Use '--' to separate paths from revisions, like this:
    'git <command> [<revision>...] -- [<file>...]'
    error: could not parse log for 'HEAD..seent'

This error message is exactly what I expect to see when I mistype a ref
(my git(1) conditioning).

But the `v2.40.0` error message with `--` is better: `fatal: not a
revision: 'seent'`.

So what if I give a `--`:

    $ # Still on v2.37.2
    $ ./bin-wrappers/git range-diff master next seent --
    fatal: ambiguous argument 'master..seent': unknown revision or path not in the working tree.
    Use '--' to separate paths from revisions, like this:
    'git <command> [<revision>...] -- [<file>...]'
    error: could not parse log for 'master..seent'

It’s the same. Oh, right—I guess rev. b75747829f taught `range-diff` 
about `--`.

In conclusion: IMO and assuming that my cross-version testing is
correct, `range-diff` has a slight usability regression for when you
mistype the ref. It would be nice if the error message without a
pathspec separator (`--`/`dash_dash`) was as nice as the one without it.

[1]: Original thread: https://groups.google.com/g/git-users/c/O5uB-E68S_0

-- 
Kristoffer Haugsbakk