Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Hooks

The update hook

Reference for the Git update hook: runs once per pushed ref on the server, receives refname, old and new object names, and rejects only that ref.

The update hook runs on the receiving repository like pre-receive, but with one important difference: it runs once for each ref being updated, and a rejection affects only that ref. If you push three branches and the hook declines one, the other two are still updated (unless the push was made with --atomic).

It receives the details as command-line arguments instead of standard input, which makes per-branch rules short to write: protect one branch, forbid deleting tags, or limit who may push to a path of ref names.

Terminal
# $GIT_DIR/hooks/update <refname> <old-object-name> <new-object-name>

Try it

Bash Reject one ref, accept the others

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 Make tags immutable

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

The file is named update, is executable, and sits in the hooks directory of the receiving repository.

Name Description
$1 The full name of the ref being updated, such as refs/heads/main or refs/tags/v1.
$2 The old object name stored in the ref. All zeros when the ref is being created.
$3 The new object name the ref will have. All zeros when the ref is being deleted.

Exit status: 0 allows this one ref to be updated; non-zero rejects it. The client sees ! [remote rejected] <ref> (hook declined) and any text the hook wrote to stderr, prefixed with remote:.

Usage notes

  • The order on the server is: pre-receive once for the whole push, then update once per ref, then the refs are actually updated, then post-receive once.
  • If pre-receive rejected the push, update never runs. If update rejects a ref, pre-receive has already accepted the push, so the other refs go through.
  • With git push --atomic, one rejected ref makes the whole push fail, as if all were rejected.
  • The hook can run in a loop of commits: git rev-list "$old..$new" for updates, or "$new" --not --all for new refs. Check for the all-zero names first, because old..new with a zero ID is an error.
  • To test a hook without pushing, call it by hand: .git/hooks/update refs/heads/x <old> <new>. The exit status is the verdict.
  • git push --no-verify has no effect on server hooks. Only the people who own the server can bypass them.
  • Remember deletions: a delete arrives with an all-zero $3. Rules like "must have a ticket in the message" should skip that case.
  • The hook runs in a quarantine environment, so the new objects are visible to git commands inside it even though they are not in the repository yet.