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

[Patrick Steinhardt <ps@pks.im>]

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