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

[Junio C Hamano <gitster@pobox.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.

>> (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.