Git Reference ยท Branches and Tags
git update-ref command
Reference for git update-ref: point a branch or tag at a commit, guard against races with old values, delete refs, use transactions and write reflog messages.
git update-ref is the low-level command that changes what a ref points to. Every higher-level command that moves a branch (commit, reset, merge, rebase) ends with the same operation: write a new object id into a ref file and record the change in the reflog. update-ref exposes that step directly.
Its value is safety. You can say "set refs/heads/main to this commit, but only if it still points at that one", which turns a read-modify-write into an atomic compare-and-swap. In a script or a server-side hook this prevents lost updates. Several refs can also be changed in one all-or-nothing transaction.
git update-ref refs/heads/topic <commit> git update-ref refs/heads/topic <new> <old> # only if it currently equals <old> git update-ref -d refs/heads/topic # delete
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git update-ref [-m <reason>] [--no-deref] [--create-reflog] (-d <ref> [<old-oid>] | <ref> <new-oid> [<old-oid>]) git update-ref [-z] --stdin [--batch-updates]
| Name | Description |
|---|---|
<ref> |
The full ref name, such as refs/heads/main. HEAD is allowed and updates the branch it points to. |
<new-oid> |
The object id (or any revision expression) to store. The all-zero id deletes the ref. |
<old-oid> |
Optional. The update only happens if the ref currently has this value. The all-zero id means the ref must not exist. |
-d |
Delete the ref, optionally checking <old-oid>. |
-m <reason> |
Reflog message for the change. |
--no-deref |
Overwrite a symbolic ref itself instead of the ref it points to. |
--create-reflog |
Create a reflog for the ref even if core.logAllRefUpdates would not. |
--stdin |
Read commands from standard input and apply them as a transaction. |
-z |
With --stdin, separate fields with NUL characters so names with odd bytes are safe. |
Stdin commands: update <ref> <new> [<old>], create <ref> <new>, delete <ref> [<old>], verify <ref> [<old>], symref-update, symref-create, symref-delete, symref-verify, and the transaction words start, prepare, commit, abort. Without start and commit, the whole input is one transaction.
Errors: a failed old-value check, a missing object, or a name that is not a valid ref prints a fatal: message and changes nothing; the exit status is non-zero.
Usage notes
- Prefer
update-refover writing files under.git/refs. It takes the lock files, writes the reflog, and works with packed refs and reftable storage. - Check the old value in scripts. Without
<old-oid>the update always wins, so two scripts racing on the same branch silently overwrite each other. - It does not check ancestry. Pointing a branch at an unrelated commit is allowed. Commands like
git pushapply fast-forward rules;update-refdoes not. - No working tree changes. Moving the checked-out branch this way leaves the index and files behind, which then show up as pending changes.
git reset --softis the friendly equivalent. - Annotated tags need a tag object.
update-ref refs/tags/x <commit>makes a lightweight tag; create the object withgit mktagorgit tag -afirst for an annotated one. - Namespaces. Only names under
refs/(plusHEAD) are accepted. Custom namespaces such asrefs/backup/are fine and are ignored by branch and tag listings. - Objects must exist. Git refuses to store an id that is not in the object database, so garbage ids cannot create dangling refs.
- Transactions and
--batch-updates(newer Git) let some updates in a batch succeed while others are rejected, instead of aborting everything.