Re: [PATCH v2] update-ref: add --rename option

[Patrick Steinhardt <ps@pks.im>]

On Wed, Jun 10, 2026 at 02:28:00PM -0700, Junio C Hamano wrote:
> Add a "--rename" option to "git update-ref" with the syntax:
> 
>  $ git update-ref --rename <old-refname> <new-refname>
> 
> It renames <old-refname> together with its reflog to <new-refname>
> (even when used on a local branch ref, the current value and the
> reflog of the ref are the only things that are renamed).  As the
> command is a low-level plumbing command, attempts to rename branches
> are not warned, but we document it to draw attention of unsuspecting
> users and protect them from burning themselves.

This sentence reads a tiny bit awkward now and is probably an artifact
of the change between v1 and v2.

> Because the "--stdin" mode wants to operate on its refs in a
> reference transaction, and the API function refs_rename_ref() does
> not work well as part of a transaction, it is currently not possible
> to add a corresponding "rename" verb to the "--stdin" mode before
> the underlying API learns to rename refs atomically inside a
> transaction.  It hence is left for a future refactoring.

Fair. I thought at times about extending reference transactions to also
fully support renames, but I never had a good use case where it would
really matter.

>  * The initial draft I sent had a warning when the command is used
>    to rename local branches, but that is unusual for plumbing
>    commands that should do one thing it is designed for consistently
>    well without being chatty.  This version only has words of warning
>    in the documentation.

Good, I just wanted to complain about that warning. I think it's good to
just accept this as-is. I really doubt that folks would go out of their
way to use git-update-ref(1) if all they want was to rename their
branch.

One thing that I'm missing from the commit message: what's the
motivation for this new mode?

> diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc
> index 37a5019a8b..0c27efaa52 100644
> --- a/Documentation/git-update-ref.adoc
> +++ b/Documentation/git-update-ref.adoc
> @@ -39,6 +40,14 @@ the result of following the symbolic pointers.
>  With `-d`, it deletes the named <ref> after verifying that it
>  still contains <old-oid>.
>  
> +With `--rename`, it renames <old-refname> together with its reflog to
> +<new-refname>.  The command fails if <old-refname> does not exist, or
> +if <new-refname> already exists.  Because `git update-ref` does not
> +update active worktree `HEAD` symbolic references or `.git/config`
> +tracking settings when you rename a local branch in the `refs/heads/`
> +hierarchy, think twice before using this command to rename a local
> +branch (use `git branch -m` instead).

I'd rephrase this slightly to first document behaviour and then draw the
conclusion that it shouldn't be used in many cases separately. For
example:

    This command does not update any symbolic references pointing to
    the renamed reference, and neither does it update `.git/config`
    tracking settings. It is thus not recommended to use it for renaming
    local branches. Use `git branch -m` instead.

> diff --git a/builtin/update-ref.c b/builtin/update-ref.c
> index 2d68c40ecb..65ee8af08c 100644
> --- a/builtin/update-ref.c
> +++ b/builtin/update-ref.c
> @@ -787,7 +789,7 @@ int cmd_update_ref(int argc,
>  	}
>  
>  	if (read_stdin) {
> -		if (delete || argc > 0)
> +		if (delete || rename || argc > 0)
>  			usage_with_options(git_update_ref_usage, options);
>  		if (end_null)
>  			line_termination = '\0';

Okay, so here we make it mutually exclusive with "--delete".

> @@ -800,6 +802,32 @@ int cmd_update_ref(int argc,
>  	if (end_null)
>  		usage_with_options(git_update_ref_usage, options);
>  
> +	if (rename) {
> +		const char *oldref, *newref;
> +
> +		if (delete || argc != 2)
> +			usage_with_options(git_update_ref_usage, options);

And here with "-d". Good.

> +		if (!refs_ref_exists(get_main_ref_store(the_repository), oldref))
> +			die("no ref named '%s'", oldref);
> +
> +		if (refs_ref_exists(get_main_ref_store(the_repository), newref))
> +			die("ref '%s' already exists", newref);
> +
> +		if (refs_rename_ref(get_main_ref_store(the_repository),
> +				    oldref, newref, msg))
> +			die("rename failed");
> +		return 0;
> +	}

Hm. I think we're not using "--deref" / "--no-deref" at all, but we
document this flag as accepted in the synopsis.

Thanks!

Patrick