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

[Jeff King <peff@peff.net>]

On Fri, Oct 16, 2020 at 01:52:32PM -0700, Emily Shaffer wrote:

> Some users skimmed past the note in 'git help apply' mentioning 'git
> am' and weren't sure how to retain commit details. An example
> illustrating the difference between the two shows this information in
> another way, so users who prefer to be shown rather than told can
> discover the difference too.

Having an example showing the difference seems reasonable. However, I
think it should come lower in the file. Putting such a big chunk between
the DESCRIPTION and OPTIONS sections will makes it much harder to find
the options (and that's what people are usually looking for).

Plus it's customary to have the example section (which is usually
pluralized as EXAMPLES) near the end. See:

  https://man7.org/linux/man-pages/man7/man-pages.7.html

which gives recommended names and order.

> Notes:
>     In this change, I wasn't sure about a few things:
>     
>     - Should the comments on the snippets live outside of the blockquote instead?

I think it is OK as-is, but it might be easier to follow visually with
text like:

   Here's a sample patch that we'll use below.

   -----
   $ cat the-patch, etc
   -----


   We can apply it with `git am`, which will create a new commit:

   -----
   $ git am ...etc...
   -----

Especially in the HTML version, which puts the code blocks into a box
with a different backgrounds, that makes it easy to visually jump to
each box without having to carefully read the contents.

>     - Should 'git reset' be included in the snippets, so that users don't try to
>       paste without thinking?

I don't think they could meaningfully paste this anyway, since they
don't have the base commit that it would apply to (you could make the
patch strict add, but I think it's perhaps desirable that they aren't
real runnable commands).

>     - Should the example go underneath the options list?

Yes. :)

You can say "see the EXAMPLES section below" next to the added text if
you want to point out that the example clarifies it further (though I
don't think it's strictly necessary).

>     Anyway, we got internal feedback that the description in 'git help am' wasn't
>     very noticeable. I'm not sure I agree, but it's true that some folks grok
>     examples more easily than they grok prose, so we figured it probably couldn't
>     hurt to provide both.

I think the example is a reasonable one to show, even aside from the "is
it noticeable" level. Having it present twice feels a little funny, but
cross-referencing ("see the examples section in git-am(1)") gets
awkward.

I do like the added text that back-references "git apply" from the "git
am" manpage.

> +# use 'git am' to create a new commit with details from the patch
> +$ git status
> +On branch main
> +nothing to commit, working tree clean
> +$ git am ~/0001-README-add-more-text.patch
> +Applying: README: add more text
> +$ git status
> +On branch main
> +nothing to commit, working tree clean
> +$ git log --oneline
> +dd6a400 (HEAD -> main) README: add more text
> +90b59fb base commit

I know you're trying to show with "git status" that the working tree is
kept clean. But it does make the example much longer. I kind of think
showing just "git am" and "git log" would be sufficient.

> +# use 'git apply' to apply to the worktree without creating a commit.
> +$ git status
> +On branch main
> +nothing to commit, working tree clean
> +$ git apply ~/0001-README-add-more-text.patch
> +$ git status
> +On branch main
> +Changes not staged for commit:
> +  (use "git add <file>..." to update what will be committed)
> +  (use "git restore <file>..." to discard changes in working directory)
> +	modified:   README
> +
> +no changes added to commit (use "git add" and/or "git commit -a")

Showing status afterwards here makes sense. I'm not sure if you need to
show that it's clean before-hand, though, which could also reduce the
size of the example.

-Peff