Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Hooks

The reference-transaction hook

Reference for the Git reference-transaction hook: its states, the old/new/ref lines on stdin, how a non-zero exit vetoes a ref update, and what the values mean.

Almost everything that changes a branch or tag goes through a reference transaction: commits, merges, rebases, git branch, git tag, git fetch, git push on the server, and git update-ref. The reference-transaction hook is called around each of these transactions, so it sees ref updates that no other hook can see, and it works the same way on clients and servers.

The hook is called once per stage of the transaction, and its first argument tells you which stage that is. In the prepared stage the new values are locked in but not yet written, and a non-zero exit aborts the whole transaction. In the committed stage the refs have been written; in the aborted stage the transaction was cancelled. For those two the exit status is ignored.

Terminal
.git/hooks/reference-transaction <state>
# state: preparing, prepared, committed or aborted
# stdin, one line per ref in the transaction:
# <old-value> <new-value> <ref-name>

Try it

Bash Log every ref update

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 Veto a ref update in the prepared state

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

Input Description
$1 The state. preparing (newer Git, before any lock is taken), prepared (refs locked, nothing written), committed (written) or aborted (cancelled).
stdin One line per ref: <old-value> <new-value> <ref-name>. A value is an object name, all zeros for "no ref", or ref:<target> for a symbolic ref.

Exit status: in the preparing and prepared states, non-zero aborts the transaction and the command that started it fails with a message such as in 'prepared' phase, update aborted by the reference-transaction hook. In committed and aborted the status is ignored.

Usage notes

  • The old value is only filled in when the caller supplied one. Commands such as git tag -d and git tag -f do not state what they expect the old value to be, so the hook sees all zeros for it. Do not rely on the old value to detect "the ref existed". Ask Git instead, with git show-ref --verify or git rev-parse --verify, as the second example does; in prepared the ref still has its old value.
  • A transaction can touch several refs at once (an atomic push, a rebase finishing), and the hook sees all of them in one call. A veto cancels all of them.
  • One command may run several transactions, and they include pseudo-refs. A commit also reports HEAD, and merges or cherry-picks may report AUTO_MERGE. Filter by prefix (refs/heads/, refs/tags/) as the first example does.
  • Seeing aborted does not mean the command failed. The branch rename in the first example prints preparing, aborted, prepared, committed for the same ref, because Git drops one transaction and opens another. Judge the outcome by the committed call.
  • Not every command goes through every state: an ordinary commit only reports prepared and committed.
  • Always read stdin, even when you ignore it, so the writer never gets a broken pipe.
  • It fires often, at least once per stage on every commit. Return early for the states you do not need.
  • Bare repositories run it too, so on a server it complements pre-receive and update: those see only what pushers send, while this one sees every change, including those made by server-side tooling.
  • No command-line option such as --no-verify skips it. Only removing the hook file does, so it is a guard against mistakes, not against the owner of the machine.
  • The hook was added in Git 2.28. The preparing state was added later.