The case of `git update-ref MERGE_HEAD`

Johannes Sixt· Sep 12, 2025, 16:19 UTC · lore

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

Patrick Steinhardt· Sep 15, 2025, 12:16 UTC · re: Johannes Sixt · lore

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

On Fri, Sep 12, 2025 at 06:19:52PM +0200, Johannes Sixt wrote:

Show 40 quoted lines

> 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