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

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Mar 28, 2023, 11:37 UTC
Message-ID: <818b3ad0-df43-3484-8c19-d95026f6b2b1@gmx.de>
In-Reply-To: <b93934a2-91e7-4645-9a24-4f2354172f31@app.fastmail.com>

Hi Kristoffer,

On Sat, 25 Mar 2023, Kristoffer Haugsbakk wrote:

Show 19 quoted lines

>     $ # 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