Git Reference ยท Hooks
The pre-receive hook
Reference for the Git pre-receive hook: runs once per push on the server, reads old/new/ref lines on stdin, rejects the whole push, and sees quarantined objects.
pre-receive runs on the server (the repository you push to) once for each push, after the objects have been received but before any ref is updated. It reads one line per ref from standard input. If it exits with a non-zero status, the entire push is rejected: no ref changes, even those the hook would have accepted.
Because it runs on the server, pre-receive is real enforcement. A user cannot skip it with --no-verify. It is the right place for rules such as "no force pushes to main", "every commit message references a ticket", or "no files larger than 10 MB".
# $GIT_DIR/hooks/pre-receive (no arguments) # stdin, one line per ref being updated: # <old-object-name> <new-object-name> <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
The hook is an executable file named pre-receive in the hooks directory of the receiving repository. It takes no arguments.
| Input | Description |
|---|---|
| stdin | One line per ref the client asked to update: <old-object-name> <new-object-name> <ref-name>. A new ref has an all-zero old name; a deleted ref has an all-zero new name. |
GIT_DIR |
Points at the repository (usually ., because hooks run inside it). |
GIT_PUSH_OPTION_COUNT, GIT_PUSH_OPTION_<n> |
Set when the client used git push -o and the server has receive.advertisePushOptions enabled. |
Exit status: 0 accepts the push so far; non-zero rejects every ref in the push. Anything the hook writes to stdout or stderr is sent to the client, where Git prefixes each line with remote:.
Usage notes
- Quarantine. Since Git 2.11 the received objects are stored in a temporary quarantine area while the hook runs, and
GIT_QUARANTINE_PATHis set. Plaingitcommands in the hook see them, sogit rev-list,git logandgit cat-filework on the incoming commits. If the hook rejects the push, the quarantine is deleted and nothing is left behind. git rev-list "$new" --not --alllists the commits that the push adds: those reachable from the new tip and from no existing ref. It is the usual way to find "the new commits", including for a brand-new branch whereoldis all zeros.- Do not use
"$old..$new"blindly: for a new brancholdis not a valid object, and for a forced update the range may hide dropped commits. - All-or-nothing: with
pre-receive, one bad ref spoils the entire push. If you want to accept some refs and reject others, use update, which runs once per ref. - Writing to stderr is the way to explain a rejection. Keep messages actionable: name the commit and the rule.
- The hook runs even if the push is a deletion, so check for the all-zero new name before inspecting
$new. - Large pushes make the hook run long. Keep checks cheap, or the client may time out.
- Hosting services (GitHub, GitLab) implement the same idea with protected branches and their own server hooks; you only write this file yourself on a server you control.
Related
- update, post-receive, pre-push
- git push, git rev-list
- Tutorials: Server-side hooks, Pushing and pulling