[PATCH 2/2] doc: cherry-pick: note --no-commit skips CHERRY_PICK_HEAD

From: Aleksei Sviridkin <f@lex.la>
Date: Sep 3, 2026, 12:55 UTC
Message-ID: <20260903125524.67889-2-f@lex.la>
In-Reply-To: <20260903125524.67889-1-f@lex.la>

The list of what happens when a change is hard to apply states without qualification that CHERRY_PICK_HEAD is set. Under --no-commit it is not: d7e5c0cbfb (Introduce CHERRY_PICK_HEAD, 2011-02-19) skips the ref on purpose there, expecting the user to pick further commits and edit the result before committing.

The option's own description says nothing about the ref or about authorship. "git commit" reads the author of a cherry-pick from CHERRY_PICK_HEAD, so a commit made after "cherry-pick --no-commit" records your own identity as the author. Picking a single commit this way still leaves its log message in MERGE_MSG, so the result reads like a faithful pick apart from the author.

Assisted-by: LLM
Signed-off-by: Aleksei Sviridkin <f@lex.la>
---

Notes:
    The trap is sharpest in the use this option's own description
    recommends.  Picking several commits in a row leaves one commit that
    carries the last picked commit's message over the combined effect of
    all of them, under the committer's authorship, with nothing on screen
    to say so.  The added text scopes the "git commit -c" remedy to the
    single-commit case, since after several picks there is no one original
    author to restore.
    
    One more thing worth knowing when following that advice: if the picks
    were made with -x, the "(cherry picked from commit ...)" line lives in
    MERGE_MSG, and "git commit -c <commit>" replaces the message with the
    original commit's and drops the annotation.
    
    I left git-revert.adoc alone on purpose.  "revert --no-commit" does
    write REVERT_HEAD (t3507), so the two commands are asymmetric here, but
    a revert's authorship belongs to the reverter either way, so there is
    no equivalent consequence to document there.  Documentation/revisions.adoc
    describes CHERRY_PICK_HEAD without the --no-commit qualification as
    well; I can send that as a follow-up if it is wanted.

 Documentation/git-cherry-pick.adoc | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
index 42b41923d5..d352e7e956 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.
++
+Because `CHERRY_PICK_HEAD` is not recorded, the commit you make
+afterwards records you as its author.  When a single commit is picked
+this way, `git commit -c <commit>` keeps the original authorship and
+log message.
 
 -s::
 --signoff::

-- 
2.55.0