Git Reference ยท Hooks
commit-msg hook
Reference for the commit-msg hook: the message file argument, validating subject length and format, editing the message, exit codes, --no-verify and which commands run it.
The commit-msg hook runs after the message has been written (typed in the editor, passed with -m, or read with -F) and before the commit object is created. Git passes one argument: the path of the file that holds the message. If the hook exits non-zero, the commit is aborted; if it edits the file, the edited text becomes the message.
This is the place to enforce conventions such as a subject length, a prefix like fix: or feat:, a required ticket id, or a Signed-off-by trailer. The staged files stay staged when the hook refuses, so a corrected retry is easy.
#!/bin/sh # .git/hooks/commit-msg subject=$(sed -n '1p' "$1")
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
.git/hooks/commit-msg <message-file>
| Item | Detail |
|---|---|
| Argument | Path of the file with the message, usually .git/COMMIT_EDITMSG. |
| Standard input | Not used. |
| Exit status | 0 accepts; non-zero aborts the commit. |
| Skipped by | git commit --no-verify (-n). git merge --no-verify skips it for merge commits as well. |
| Edits | Allowed. Whatever the file contains when the hook exits is used. |
What the file contains: the message as written, including the # comment lines that were shown in the editor. Git removes them (and surrounding whitespace) later according to commit.cleanup, so a validating hook should skip lines that start with #. With -m, there are no comment lines.
Usage notes
- Validate what you will store. Strip comments before checking length or emptiness, and decide how to treat trailers (
Co-authored-by:lines) when counting the subject length. Only the first line is the subject. - Keep the error specific and actionable: say which rule failed, show the offending value and what is allowed. The author sees this at the end of a long editing session.
- Use
git interpret-trailersto add or normalize trailers such asSigned-off-by,Change-IdorReviewed-byinstead of writing them by hand withecho. It understands the layout and avoids duplicates. - It runs for amends, merges and
-F/-m, not for commits created by plumbing such asgit commit-tree. - Client-only. Anyone can bypass it with
--no-verify, so server-side enforcement belongs inpre-receiveor in the hosting service's push rules, which can look at each incoming commit message. - Merge commits created by
git mergereceive Git's automatic message; a strict format rule can block them. Skip messages beginning withMerge. - Common conventions such as Conventional Commits are easy to check with a regular expression on the subject, as in
casepatterns. Fast shell checks beat starting a language runtime for each commit. - Test with
git hook run commit-msg -- <file>after writing a sample message file.