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