Re: [PATCH 4/4] doc: git-pull: clarify how to exit a conflicted merge

From: Julia Evans <julia@jvns.ca>
Date: Sep 24, 2025, 17:21 UTC
Message-ID: <1928a79e-c0e1-4510-8717-89053b54ff48@app.fastmail.com>
In-Reply-To: <c7f09c2bd32baf9e1dda355656bba811484e90a0.1758656702.git.gitgitgadget@gmail.com>

On Tue, Sep 23, 2025, at 3:45 PM, Julia Evans via GitGitGadget wrote:

Show 36 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> From user feedback:
>
> - One user is confused about why `git reset --merge`
>   (why not just `git reset`?). Handle this by mentioning
>   `git merge --abort` and `git reset --abort` instead, which have a
>   more obvious meaning.
> - 2 users want to know what "In older versions of Git" means exactly
>   (in versions older than 1.7.0). Handle this by removing the warning
>   since it was added 15 years ago (in 3f8fc184c0e2c)
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-pull.adoc | 12 +++---------
>  1 file changed, 3 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc
> index 91903b0a94..eec05ab6c7 100644
> --- a/Documentation/git-pull.adoc
> +++ b/Documentation/git-pull.adoc
> @@ -30,15 +30,9 @@ branch. There are 4 main options for integrating the 
> remote branch:
>  You can also set the configuration options `pull.rebase`, 
> `pull.squash`,
>  or `pull.ff` with your preferred behaviour.
> 
> -In Git 1.7.0 or later, to cancel a conflicting merge, use
> -`git reset --merge`.  *Warning*: In older versions of Git, running 'git pull'
> -with uncommitted changes is discouraged: while possible, it leaves you
> -in a state that may be hard to back out of in the case of a conflict.
> -
> -If any of the remote changes overlap with local uncommitted changes,
> -the merge will be automatically canceled and the work tree untouched.
> -It is generally best to get any local changes in working order before
> -pulling or stash them away with linkgit:git-stash[1].

After sending this I thought to read the `git merge` man page, which has this warning:

> WARNING: Running `git merge` with non-trivial uncommitted changes is

discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict.

I think I was probably too hasty in removing the warning entirely, since I mainly use `git pull --rebase` and I hadn't fully thought through how `git merge` has a different approach to uncommitted changes than `git rebase`.

I think a warning similar to that one would make sense, since any warning that applies to `git merge` should also apply to `git pull`.

> +If there's a merge conflict during the merge or rebase that you don't
> +want to handle, you can safely abort it with `git merge --abort` or `git
> +--rebase abort`.

Also I noticed a typo in `git --rebase abort` :)