Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
.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 --.

Bash Reject patches without a Signed-off-by line

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 Use the series counters

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. The sendemail.validate setting is true by default and can be set to false.
  • --dry-run also 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 any To:/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>.