Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
#!/bin/sh
# .git/hooks/commit-msg
subject=$(sed -n '1p' "$1")

Try it

Bash Enforce a subject line format

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 Rewrite the message: add a trailer, and see which commands run the hook

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

Text
.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-trailers to add or normalize trailers such as Signed-off-by, Change-Id or Reviewed-by instead of writing them by hand with echo. It understands the layout and avoids duplicates.
  • It runs for amends, merges and -F/-m, not for commits created by plumbing such as git commit-tree.
  • Client-only. Anyone can bypass it with --no-verify, so server-side enforcement belongs in pre-receive or in the hosting service's push rules, which can look at each incoming commit message.
  • Merge commits created by git merge receive Git's automatic message; a strict format rule can block them. Skip messages beginning with Merge .
  • Common conventions such as Conventional Commits are easy to check with a regular expression on the subject, as in case patterns. 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.