Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash Create, move and guard a ref

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.

Bash Delete refs and run a transaction

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

Terminal
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-ref over 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 push apply fast-forward rules; update-ref does 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 --soft is the friendly equivalent.
  • Annotated tags need a tag object. update-ref refs/tags/x <commit> makes a lightweight tag; create the object with git mktag or git tag -a first for an annotated one.
  • Namespaces. Only names under refs/ (plus HEAD) are accepted. Custom namespaces such as refs/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.