From: Patrick Steinhardt Date: Thu, 11 Jun 2026 13:05:56 GMT Subject: Re: [PATCH v2] update-ref: add --rename option Message-ID: In-Reply-To: <20260610212800.2892146-1-gitster@pobox.com> 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 > > It renames together with its reflog to > (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 after verifying that it > still contains . > > +With `--rename`, it renames together with its reflog to > +. The command fails if does not exist, or > +if 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