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

[Junio C Hamano <gitster@pobox.com>]

Emily Shaffer <emilyshaffer@google.com> writes:

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