Re: [PATCH 5/7] [doc] git-cherry-pick: link to new merge conflicts guide

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 25, 2026, 17:17 UTC
Message-ID: <xmqqpky1uu6t.fsf@gitster.g>
In-Reply-To: <03a6b43b5803e6bd9ebba1a49c34cb42202a7f44.1790261062.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 40 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> Remove the discussion of merge conflicts and replace it with a link to
> the guide.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-cherry-pick.adoc | 23 ++++-------------------
>  1 file changed, 4 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
> index f4cd8b9db7..d93829600b 100644
> --- a/Documentation/git-cherry-pick.adoc
> +++ b/Documentation/git-cherry-pick.adoc
> @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one
>  introduces, recording a new commit for each.  This requires your
>  working tree to be clean (no modifications from the HEAD commit).
>  
> -When it is not obvious how to apply a change, the following
> -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, 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
> -   versions, as described in the "TRUE MERGE" section of
> -   linkgit:git-merge[1].  The working tree files will include
> -   a description of the conflict bracketed by the usual
> -   conflict markers `<<<<<<<` and `>>>>>>>`.
> -5. No other modifications are made.
> -
> -See linkgit:git-merge[1] for some hints on resolving such
> -conflicts.
> +When it is not obvious how to apply a change, there may
> +be a merge conflict. See linkgit:gitmergeconflicts[7]
> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.

The new document may explain how to resolve conflicts, but are the details removed from here that are specific to the 'cherry-pick' operation also covered there?

For example, during a difficult cherry-pick, it is often handy to be able to run 'git show CHERRY_PICK_HEAD', but now users are not told about the pseudo-ref, which seems like a real loss.

The fact that cleanly auto-resolved contents for paths are recorded in the index may be shared with all other merge-like operations, and it need not be part of the "how to resolve a conflicted merge-like operation" recipe, but users need to be assured that this is what happens somewhere in the documentation set. The list removed here served that purpose for this specific command, but it is now gone.

I do not recall offhand whether we explicitly tell our users that all merge-like operations update the index with cleanly auto-resolved results and only leave conflicts to be hand-resolved by the user, but even if we did so elsewhere, I do not see any reference to that in the existing text of the 'cherry-pick' manual, nor does this patch series add such a link. At least item #2 and #3 should be kept in the list, I think. A better alternative might be to add your new reference, and shorten the description given in item #4, and leave everything else as before.

Thanks.

Show 11 quoted lines

>  
>  OPTIONS
>  -------
> @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^  <4>
>  SEE ALSO
>  --------
>  linkgit:git-revert[1]
> +linkgit:gitmergeconflicts[7]
>  
>  GIT
>  ---