Git Reference ยท Hooks
The sendemail-validate hook
Reference for the Git sendemail-validate hook: when git send-email calls it, the files it receives, how a non-zero exit stops the send, and how to test it.
git send-email mails patches to a mailing list. Before it contacts the mail server, it can run the sendemail-validate hook on every message it is about to send. If the hook exits with a non-zero status for any message, git send-email stops and sends nothing at all, so a series never goes out half-checked.
Projects that review by mail use this hook to run checkpatch-style tools, reject patches with a missing Signed-off-by line, refuse subjects that do not follow the project's convention, or make sure a cover letter exists.
.git/hooks/sendemail-validate <message-file> <headers-file>
Try it
The sandbox cannot send mail, so these examples build real patch files with git format-patch and run the hook by hand with git hook run, which starts it exactly as Git would, with the arguments you give after --.
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
| Argument | Description |
|---|---|
$1 |
Path of the file that holds the message that is about to be sent, including its headers, as git send-email has prepared it. |
$2 |
Path of a file that holds only the SMTP headers of the message (recent Git versions). |
Environment variables set by git send-email:
| Variable | Description |
|---|---|
GIT_SENDEMAIL_FILE_COUNTER |
The position of the current message in the series, starting at 1. |
GIT_SENDEMAIL_FILE_TOTAL |
The number of messages in the series. |
Exit status: 0 accepts the message. Non-zero stops git send-email before anything is sent.
Usage notes
- Validation happens before the first message goes out, for every message in the run. A rejection in message 5 of 5 still sends nothing, which is the point.
- Turn it off for one run with
git send-email --no-validate. Thesendemail.validatesetting istrueby default and can be set tofalse. --dry-runalso validates, so you can test a hook without a mail server.- The hook runs in the repository's root directory. The files it receives are temporary: read them, do not edit them.
- Messages are checked in the form they will be mailed, not from your commits, so the hook sees the final
Subject:with its[PATCH n/m]prefix and anyTo:/Cc:lines. - To get at the parts of a message,
git mailinfo <msg> <patch>splits an e-mail into its text and its diff, which is handy for running content checks. - Errors printed on stderr are shown to the user. Say which message and which rule failed.
- Like most client-side hooks, it is advisory. The mailing list is the real gatekeeper.
- You can test any version of the hook the way the examples do, with
git hook run sendemail-validate -- <file>.