Re: [PATCH v4 2/5] doc: git rebase: dedup merge conflict discussion

[Patrick Steinhardt <ps@pks.im>]

On Sat, Aug 09, 2025 at 01:14:14AM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
> index 449f01fba560..e30b9535fff1 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -39,6 +39,27 @@ shortcut for `git checkout topic && git rebase master`.
>      D---E---F---G master
>  ------------
>  
> +If there is a merge conflict during this process, `git rebase` will stop at the
> +first problematic commit and leave conflict markers. If this happens, you can do
> +one of these things:
> +
> +1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)
> +   and make edits to resolve the conflict. For each file you edit, you need to
> +   tell Git that the conflict has been resolved. You can mark the conflict as
> +   resolved with  `git add <filename>`. After resolving all of the conflicts,
> +   you can continue the rebasing process with
> +
> +   git rebase --continue
> +
> +2. Stop the `git rebase` and return your branch to its original state with
> +
> +   git rebase --abort
> +
> +3. Skip the commit that caused the merge conflict with
> +
> +   git rebase --skip
> +
> +
>  If `<branch>` is specified, `git rebase` will perform an automatic
>  `git switch <branch>` before doing anything else.  Otherwise
>  it remains on the current branch.

Yup, this reads a lot nicer.

> @@ -74,13 +95,6 @@ any commits in `HEAD` which introduce the same textual changes as a commit
>  in `HEAD..<upstream>` are omitted (i.e., a patch already accepted upstream
>  with a different commit message or timestamp will be skipped).
>  
> -It is possible that a merge failure will prevent this process from being
> -completely automatic.  You will have to resolve any such merge failure
> -and run `git rebase --continue`.  Another option is to bypass the commit
> -that caused the merge failure with `git rebase --skip`.  To check out the
> -original `<branch>` and remove the `.git/rebase-apply` working files, use
> -the command `git rebase --abort` instead.
> -
>  If the upstream branch already contains a change you have made (e.g.,
>  because you mailed a patch which was applied upstream), then that commit
>  will be skipped and warnings will be issued (if the 'merge' backend is

We lose the bit about `.git/rebase-apply`, but I don't think that's a
bad thing. The user shouldn't have to care how exactly a rebase looks on
disk. All they should need to know is that `git rebase --abort` gets
them out of the state.

Patrick