commit-msg hook for message validation in Git - Commands & Configuration

Introduction

Sometimes commit messages are unclear or inconsistent, which makes it hard to understand changes later. A commit-msg hook helps by automatically checking commit messages before they are saved, ensuring they follow rules you set.

When you want all commit messages to start with a ticket number like ABC-123

When you want to enforce a minimum length for commit messages to keep them descriptive

When you want to prevent commits with empty or meaningless messages

When you want to keep a consistent style for commit messages across your team

When you want to catch mistakes in commit messages before they get pushed

Config File - commit-msg

commit-msg

#!/bin/sh
# This hook checks that commit messages start with a ticket ID like ABC-123

commit_msg_file="$1"

commit_msg=$(head -n1 "$commit_msg_file")

pattern='^[A-Z]{3}-[0-9]{3} .+'

if ! echo "$commit_msg" | grep -qE "$pattern"; then
  echo "Error: Commit message must start with a ticket ID like ABC-123 followed by a space and message."
  exit 1
fi

exit 0

This is a shell script used as a commit-msg hook in Git.

commit_msg_file is the file containing the commit message.

It reads the first line of the commit message and checks if it matches the pattern: three uppercase letters, a dash, three digits, a space, then some text.

If the message does not match, it prints an error and stops the commit.

If it matches, the commit proceeds.

Commands

Make the commit-msg hook script executable so Git can run it automatically when committing.

Terminal

chmod +x .git/hooks/commit-msg

Expected Output

No output (command runs silently)

Create a commit with a message that follows the required pattern, so the hook allows it.

Terminal

git commit -m "ABC-123 Fix typo in README"

Expected Output

[main abcdef1] ABC-123 Fix typo in README

 1 file changed, 1 insertion(+), 1 deletion(-)

Try to commit with a message that does not start with a ticket ID, so the hook rejects it.

Terminal

git commit -m "Fix typo in README"

Expected Output

Error: Commit message must start with a ticket ID like ABC-123 followed by a space and message.

error: could not commit due to commit-msg hook failure.

Key Concept

If you remember nothing else from this pattern, remember: commit-msg hooks automatically check commit messages and stop commits that don't follow your rules.

Common Mistakes

Not making the commit-msg hook script executable

Git will not run the hook if it is not executable, so no validation happens.

Run 'chmod +x .git/hooks/commit-msg' to make the script executable.

Writing a commit message that does not match the required pattern

The hook will reject the commit and show an error, stopping the commit process.

Write commit messages that follow the pattern, for example 'ABC-123 Fix bug'.

Editing the commit-msg hook script with syntax errors

The hook script will fail to run properly, possibly blocking all commits or allowing invalid messages.

Test the script carefully and keep it simple; use shell syntax correctly.

Summary

Create a commit-msg hook script that checks commit message format.

Make the hook script executable with chmod +x.

Try committing with valid and invalid messages to see the hook in action.