Re: range-diff: slight usability problem with mistyped ref

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

[-- Attachment #1: Type: text/plain, Size: 2042 bytes --]

Hi Kristoffer,

On Sat, 25 Mar 2023, Kristoffer Haugsbakk wrote:

>     $ # 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.
>
> [...]
>
> 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.

I can see how the error message is confusing. At the same time, the usage
below the error message should provide an indicator what forms are
applicable (even if all of the synopses are missing the `[--] [<path>...]`
part).

Now, it seems to be very, very tricky to address your concern properly.
The reason is that:

	git range-diff a.x b c

could have a typo where the user actually meant to say `a...x`, i.e. the
symmetric range form. Or the user might have meant `a..x` and the full
history of `b` with a file `c`. Or `a.x` was a mistyped ref name and the
three-commit form was intended.

So even making the exact error message depend on the number of arguments
could result in misleading error message.

We _could_ extend the `else` arm in
https://github.com/git/git/blob/v2.40.0/builtin/range-diff.c#L142-L144 to
try to parse up to the first three arguments as commit-ishs and report for
which argument that fails, of course, but even that is subject to
ambiguities: what if the third argument happens to match both a ref and a
file?

Do you have any splendid idea how to phrase the error message (or adapt
it to the concrete invocation)?

Ciao,
Johannes