[PATCH v3 0/5] builtin/refs: add ability to write references
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Jun 30, 2026, 11:49 UTC
- Message-ID
- <20260630-pks-refs-writing-subcommands-v3-0-deb04de1ecef@pks.im>
- In-Reply-To
- <20260616-pks-refs-writing-subcommands-v1-0-9f5219b6109d@pks.im>
Hi,
Reference-related functionality in Git is currently spread across many different commands: git-update-ref(1), git-for-each-ref(1), git-show-ref(1), git-pack-refs(1) and git-symbolic-ref(1). This makes it hard for users to discover what functionality we have available to work with references.
We have thus started to consolidate this functionality into git-refs(1), which is a toolbox of everything related to references. Until now, the command doesn't handle functionality of git-update-ref(1).
This patch series backfills most of the functionality by introducing three new commands:
- `git refs delete` to delete references. This is the equivalent of
`git update-ref -d`. - `git refs update` to update references. This is the equivalent of
`git update-ref <refname> <oldvalue> <newvalue>`. - `git refs rename` to rename a reference, including its reflog. This
does not have an equivalent in git-update-ref(1), but is inspired by
and supersedes [1].Changes in v3: - Fix confused error message. - Link to v2: https://patch.msgid.link/20260617-pks-refs-writing-subcommands-v2-0-07f3d18336f9@pks.im
Changes in v2:
- Add a new "create" subcommand.
- Consistently quote in error messages.
- Consistently use `<old-value>` in the synopsis.
- Don't return negative exit codes.
- Improve documentation of "update" subcommand to mention that you can
create and delete branches.
- Add tests to verify that we can use "update" to do this, both in
racy and raceless ways.
- Add missing calls to `repo_config()`.
- Drop useless `GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME` variable.
- Link to v1: https://patch.msgid.link/20260616-pks-refs-writing-subcommands-v1-0-9f5219b6109d@pks.imThanks!
Patrick
[1]: <xmqqv7brz9ba.fsf@gitster.g>
---
Patrick Steinhardt (5):
builtin/refs: drop `the_repository`
builtin/refs: add "delete" subcommand
builtin/refs: add "update" subcommand
builtin/refs: add "create" subcommand
builtin/refs: add "rename" subcommandDocumentation/git-refs.adoc | 40 +++++++ builtin/refs.c | 222 ++++++++++++++++++++++++++++++++++-- t/meson.build | 4 + t/t1464-refs-delete.sh | 130 +++++++++++++++++++++ t/t1465-refs-update.sh | 268 ++++++++++++++++++++++++++++++++++++++++++++ t/t1466-refs-create.sh | 151 +++++++++++++++++++++++++ t/t1467-refs-rename.sh | 131 ++++++++++++++++++++++ 7 files changed, 938 insertions(+), 8 deletions(-)
Range-diff versus v2:
1: 2341316537 = 1: 9dd7b70df4 builtin/refs: drop `the_repository`
2: 40efa6887b = 2: 72341f895e builtin/refs: add "delete" subcommand
3: 2f86fb281d = 3: bcca5fe8ee builtin/refs: add "update" subcommand
4: fb75fb72cf ! 4: 6fa75a36bd builtin/refs: add "create" subcommand
@@ builtin/refs.c: static int cmd_refs_optimize(int argc, const char **argv, const
+ if (repo_get_oid_with_flags(repo, argv[1], &newoid, GET_OID_SKIP_AMBIGUITY_CHECK))
+ die(_("invalid object ID: '%s'"), argv[1]);
+ if (is_null_oid(&newoid))
-+ die(_("cannot create reference with null old object ID"));
++ die(_("cannot create reference with null new object ID"));
+
+ ret = refs_update_ref(get_main_ref_store(repo), message, refname,
+ &newoid, null_oid(repo->hash_algo), flags,
@@ t/t1466-refs-create.sh (new)
+ (
+ cd repo &&
+ test_must_fail git refs create refs/heads/foo $ZERO_OID 2>err &&
-+ test_grep "null old object ID" err &&
++ test_grep "null new object ID" err &&
+ test_must_fail git refs exists refs/heads/foo
+ )
+'
5: 134b161ec7 = 5: 8e12fe028e builtin/refs: add "rename" subcommand--- base-commit: 700432b2ba22603a0bcb71475c9c333d17c9b0d1 change-id: 20260616-pks-refs-writing-subcommands-7a77be5bda9b