Re: [PATCH v2] doc: cherry-pick: note --no-commit skips CHERRY_PICK_HEAD

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

Aleksei Sviridkin <f@lex.la> writes:

> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
> index 42b41923d5..24a28d4e65 100644
> --- a/Documentation/git-cherry-pick.adoc
> +++ b/Documentation/git-cherry-pick.adoc
> @@ -25,7 +25,8 @@ happens:
>  1. The current branch and `HEAD` pointer stay at the last commit
>     successfully made.
>  2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
> -   introduced the change that is difficult to apply.
> +   introduced the change that is difficult to apply, unless the
> +   `--no-commit` option was given.
>  3. Paths in which the change applied cleanly are updated both
>     in the index file and in your working tree.
>  4. For conflicting paths, the index file records up to three
> @@ -101,6 +102,11 @@ OPTIONS
>  +
>  This is useful when cherry-picking more than one commits'
>  effect to your index in a row.
> ++
> +This option does not record `CHERRY_PICK_HEAD`, so a plain `git commit`
> +afterwards records you, not the original author, as the author.  When a
> +single commit is picked this way, `git commit -c <commit>` keeps the
> +original authorship and log message.

While the added text does not say anything false, I am not sure if
the last sentence hits the mark.

Maybe we should hint that this is a deliberate design decision
behind the '--no-commit' option, perhaps in the description of that
option?

The reason 'cherry-pick --no-commit <commit>' does not record
<commit> in CHERRY_PICK_HEAD is that the command is meant to work as
a better version [*] of 'git show <commit> | git apply'.  The point
of the operation is that you can continue to futz with the resulting
modified working tree to build your own work, and in that context,
you do not want the original authorship information.

So "When a single commit is ...", while not false, misses the point.
After continuing to futz with the resulting modified working tree to
build your own work, which may include picking (with the same
'--no-commit' option) many more commits or writing your own code, you
may still want to borrow a large part of the commit message from a
commit, and 'git commit -c <borrowed-commit>' would be the natural
thing to use.

But that advice belongs in the 'git commit' documentation, not the
'git cherry-pick' documentation.

Other than that, looking good.

Thanks.


[Footnote]
 * "better" because unlike patch application, it can use 3-way merge
   machinery to take the full file contents to wiggle the changes
   from a different context into the code that is currently checked
   out.