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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 5, 2026, 16:29 UTC
Message-ID: <xmqqik4j64qo.fsf@gitster.g>
In-Reply-To: <20260904124435.12865-1-f@lex.la>

Aleksei Sviridkin <f@lex.la> writes:

Show 23 quoted lines

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