Re: [PATCH 2/2] docs: demonstrate difference between 'am' and 'apply'

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 23, 2020, 03:57 UTC
Message-ID: <xmqqtuulk30v.fsf@gitster.c.googlers.com>
In-Reply-To: <20201022231311.GE2774782@google.com>

Emily Shaffer <emilyshaffer@google.com> writes:

Show 8 quoted lines

>> As "git apply" is primarily meant to work on "git diff" output, and
>> it does not necessarily work on an arbitrary mbox (think: MIME), I
>> do not think "if you do not want to make commit, use apply" is a
>> good suggestion to begin with.  They serve completely different
>> purposes and take different form of inputs.
>
> Okay. I think I use 'git am' to apply individual mails, which also can
> be applied with 'git apply';

Yes for 'am', sometimes for 'apply' (think: MIME).

> "This command applies patches from email (e.g. the output of 'git
> format-patch', or an mbox), preserving metadata and creating commits.

Yeah, something like that.

    This command takes a mbox, each message in which is a piece of
    e-mailed patch, which typically is output of `git format-patch`.
    For each message, the patch text is applied to the current
    branch and recorded as a commit, with the authorship information
    and log message taken from the e-mailed message.

> Use <git-apply> to apply patches (e.g. the output of 'git format-patch'
> or 'git diff') to the worktree without creating commits."

Calling 'git format-patch' output 'patches' the same way as 'git diff' output is inviting confusion. The plural 'patches' makes the confusion worse.

    Use `git apply` when you have diff (e.g. `git diff` output) to
    use to modify the working tree files and optionally the index.

Thanks.