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.
.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
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
| 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 -dandgit tag -fdo 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, withgit show-ref --verifyorgit rev-parse --verify, as the second example does; inpreparedthe 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 reportAUTO_MERGE. Filter by prefix (refs/heads/,refs/tags/) as the first example does. - Seeing
aborteddoes not mean the command failed. The branch rename in the first example printspreparing,aborted,prepared,committedfor the same ref, because Git drops one transaction and opens another. Judge the outcome by thecommittedcall. - Not every command goes through every state: an ordinary commit only reports
preparedandcommitted. - 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-verifyskips 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
preparingstate was added later.