The case of `git update-ref MERGE_HEAD`

The case of `git update-ref MERGE_HEAD`

[Johannes Sixt]

When I commit a merge, the commit message shows this advice:

# It looks like you may be committing a merge.
# If this is not correct, please run
#       git update-ref -d MERGE_HEAD
# and try again.

However, when I follow the advice, I get this error:

$ git update-ref -d MERGE_HEAD
error: refusing to update pseudoref 'MERGE_HEAD'

Also, I found a use case to set MERGE_HEAD to a particular commit, but I
can't do that, either:

$ git update-ref MERGE_HEAD e9c115e666fd6a3faaf187f5d145b32861a45cc8
fatal: update_ref failed for ref 'MERGE_HEAD': refusing to update pseudoref 'MERGE_HEAD'

I know I can do

$ echo e9c115e666fd6a3faaf187f5d145b32861a45cc8 > .git/MERGE_HEAD

in the primary worktree. But I needed to do this in a secondary
worktree, where this is more like

$ echo e9c115e666fd6a3faaf187f5d145b32861a45cc8 \
     > "$(git rev-parse --git-dir)"/MERGE_HEAD

which is a bit unwieldy...

8e4f5c2dc26e ("refs: refuse to write pseudorefs", 2024-05-15) removed
the ability to wrangle pseudo-refs with `git update-ref`. Much earlier,
b6d2558c9ea3 ("builtin/commit: suggest update-ref for pseudoref
removal", 2020-08-21) changed the commit message template with the
justification:

> [S]uggest a "update-ref -d" command, which will work regardless of
> ref storage backend.

Looks like we couldn't uphold the promise. Any suggestions?

-- Hannes

Re: The case of `git update-ref MERGE_HEAD`

[Patrick Steinhardt]

On Fri, Sep 12, 2025 at 06:19:52PM +0200, Johannes Sixt wrote:
> When I commit a merge, the commit message shows this advice:
> 
> # It looks like you may be committing a merge.
> # If this is not correct, please run
> #       git update-ref -d MERGE_HEAD
> # and try again.
> 
> However, when I follow the advice, I get this error:
> 
> $ git update-ref -d MERGE_HEAD
> error: refusing to update pseudoref 'MERGE_HEAD'
> 
> Also, I found a use case to set MERGE_HEAD to a particular commit, but I
> can't do that, either:
> 
> $ git update-ref MERGE_HEAD e9c115e666fd6a3faaf187f5d145b32861a45cc8
> fatal: update_ref failed for ref 'MERGE_HEAD': refusing to update pseudoref 'MERGE_HEAD'
> 
> I know I can do
> 
> $ echo e9c115e666fd6a3faaf187f5d145b32861a45cc8 > .git/MERGE_HEAD
> 
> in the primary worktree. But I needed to do this in a secondary
> worktree, where this is more like
> 
> $ echo e9c115e666fd6a3faaf187f5d145b32861a45cc8 \
>      > "$(git rev-parse --git-dir)"/MERGE_HEAD
> 
> which is a bit unwieldy...
> 
> 8e4f5c2dc26e ("refs: refuse to write pseudorefs", 2024-05-15) removed
> the ability to wrangle pseudo-refs with `git update-ref`. Much earlier,
> b6d2558c9ea3 ("builtin/commit: suggest update-ref for pseudoref
> removal", 2020-08-21) changed the commit message template with the
> justification:
> 
> > [S]uggest a "update-ref -d" command, which will work regardless of
> > ref storage backend.
> 
> Looks like we couldn't uphold the promise. Any suggestions?

The best we can do is to special-case pseudorefs in relevant code paths.
But we have to be very careful with how exactly we do that. Pseudorefs
aren't real refs, so we for example do not want to add logic to update
them in the same transaction as normal references.

But for something like git-update-ref(1) we may specifically carve out a
way to delete and update a single pseudoref and then handle this outside
of the normal ref transaction logic.

Patrick