git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Patrick Steinhardt <ps@pks.im>
Date
Jun 11, 2026, 13:05 UTC
Message-ID
<aiqytJD-rcEirhgE@pks.im>
In-Reply-To
<20260610212800.2892146-1-gitster@pobox.com>
On Wed, Jun 10, 2026 at 02:28:00PM -0700, Junio C Hamano wrote:
Show 10 quoted lines
> 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.

Show 6 quoted lines
> 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.

Show 5 quoted lines
>  * 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?

Show 15 quoted lines
> 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.
Show 13 quoted lines
> 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".
Show 9 quoted lines
> @@ -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.
Show 11 quoted lines
> +		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
Previous: Junio C HamanoNext: Junio C Hamano
Message 3 of 12 in “update-ref: add --rename option”
  1. update-ref: add --rename optionJunio C Hamano, Jun 9, 2026
  2. update-ref: add --rename optionJunio C Hamano, Jun 10, 2026
  3. Patrick SteinhardtJun 11, 2026
  4. Junio C HamanoJun 11, 2026
  5. Patrick SteinhardtJun 12, 2026
  6. Junio C HamanoJun 12, 2026
  7. update-ref: add --rename optionJunio C Hamano, Jun 11, 2026
  8. Patrick SteinhardtJun 12, 2026
  9. Junio C HamanoJun 12, 2026
  10. Patrick SteinhardtJun 15, 2026
  11. Junio C HamanoJun 15, 2026
  12. Patrick SteinhardtJun 16, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.