Re: What's cooking in git.git (Nov 2021, #07; Mon, 29)

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 6, 2021, 17:50 UTC
Message-ID: <xmqqlf0xhbcc.fsf@gitster.g>
In-Reply-To: <CABPp-BGk9fYqtuYTACmzdXakpV7TP635eqHtHxkoHRT3aa4qFQ@mail.gmail.com>

Elijah Newren <newren@gmail.com> writes:

> When I first read the documentation, it sounded to me like it was
> implying an abort.  I find 'die' very unnatural as a way to explain
> this behavior; it's too strong of a word.

The way we currently document "git am", we have no word "die" used anywhere in the page. The existing mention of the behaviour are found in these places:

    --continue::
    -r::
    --resolved::
            After a patch failure (e.g. attempting to apply
            conflicting patch), the user has applied it by hand and
            the index file stores the result of the application.
            Make a commit using the authorship and commit log
            extracted from the e-mail message and the current index
            file, and continue.

This uses "failure", and "the user has applied" implies that the user somehow got control back. We give "error:" messages to state that the patch does not apply from apply.c::apply_all_patches() and the caller silently exits, without calling die.

    --show-current-patch[=(diff|raw)]::
            Show the message at which `git am` has stopped due to
            conflicts.  If `raw` is specified, show the raw contents of
            the e-mail message; if `diff`, show the diff portion only.
            Defaults to `raw`.

This uses "has stopped" to describe the same situation.

Show 5 quoted lines

>> (on the other hand, I find 'ask' highly
>> unnatural since we do not ask anything---we just throw the control
>> back the user).
>
> Okay, but what about my previous suggestions of 'stop' or 'interrupt'?

I agree that "stop" would be a good word that is already used to describe "the command cannot make further progress without assistance by the user, so it stops and gives control back".

After that, the user can say "am --skip", "am --abort", or edit plus "am --continue".

Thanks.