Re: [PATCH 3/5] git-jump: admit to passing merge mode args to ls-files

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 3, 2023, 20:46 UTC
Message-ID: <xmqqjzs3xwm1.fsf@gitster.g>
In-Reply-To: <CAPig+cQHAK2_LEG0-6MTF52t2D8b_SRxzB51B_4N35ujtGeb6Q@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 15 quoted lines

>> There's even an example of such usage in the README.
>>
>> Signed-off-by: Štěpán Němec <stepnem@smrk.net>
>> ---
>> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
>> @@ -9,7 +9,7 @@ The <mode> parameter is one of:
>>
>>  diff: elements are diff hunks. Arguments are given to diff.
>>
>> -merge: elements are merge conflicts. Arguments are ignored.
>> +merge: elements are merge conflicts. Arguments are given to ls-files -u.
>
> Should "ls-files -u" be formatted with backticks?
>
>     Arguments are passed to `git ls-files -u`.

Probably not in this case, as this is end-user visible help message that is not formatted but given to the terminal.

The whole preimage looks like this:

    usage: git jump [--stdout] <mode> [<args>]

    Jump to interesting elements in an editor.
    The <mode> parameter is one of:

    diff: elements are diff hunks. Arguments are given to diff.

    merge: elements are merge conflicts. Arguments are ignored.

    grep: elements are grep hits. Arguments are given to git grep or, if
          configured, to the command in `jump.grepCmd`.

    ws: elements are whitespace errors. Arguments are given to diff --check.

    If the optional argument `--stdout` is given, print the quickfix
    lines to standard output instead of feeding it to the editor.

and it is already a mixture. "given to `git grep`" is not quoted, neither is "given to `diff --check`" or "given to `diff`"

I think rule for help/usage messages should be that

 - anything that the end-user may want to cut&paste should be left
   alone to make it easier to cut,

 - but at the same time the message should make it clear which part
   of a sentence is what,

Clicking on `--stdout` or `jump.grepCmd` does not include the surrounding quotes, at least in my environment, so the use of backquotes in these places satisfy the two goals, it seems.

Unlike `--stdout` and `jump.grepCmd`, all other things that are not quoted, including the one that is added by this patch (i.e., "ls-files -u"), are something the end-user needs to cut and paste in reaction to seeing this error message, so as long as they are understandable in the sentences they appear in, I think they are fine.

If we wanted to standardize, we may start to encourage consistent use of quoting, but I do not think it should be part of this topic.

Thanks for being careful and thoughtful.