Cleaner Git Experience with Git Hooks

# Contents

• Background
• What are Git Hooks?
• How to Validate Branch Names?
• How to Validate Commit Messages?
• Automate For Everyone
• Wrap Up

# Background

One recurring thing I’ve noticed throughout my years as a Software Engineer is that discussions about Git standards — specifically around branch naming and commit message conventions — often arise when someone deviates from the norm.

When this happens, the team usually gets a verbal reminder to follow specific conventions or is pointed to an ancient Confluence document outlining the team’s guidelines.

Recently, I discovered a way to enforce and automate these conventions using Git Hooks, and I want to share this approach with you.

# What are Git Hooks?

Git Hooks are scripts that Git executes before or after events such as commit, push, rebase etc. They’re very flexible — you can configure Git to run a script at almost any point in its lifecycle.

In every Git repository on your local, you’ll find a hidden .git/hooks directory containing sample scripts for each type of hook. These scripts are disabled by default, but you can enable them simply by removing the .sample extension.

In this blog post, I’ll focus on two Git Hooks: pre-commit and commit-msg — and show how they can enforce branch naming and commit message conventions.

# How to Validate Branch Names?

To enforce branch naming conventions, we can use the pre-commit hook.
This hook runs before a commit is created, allowing you to validate the branch name.

Steps:

1. Create a file named 'pre-commit' under the .git/hooks directory

2. Make the file executable by running the command:
chmod +x .git/hooks/pre-commit

3. Inside the file, copy and paste the script below

Script:

#!/bin/sh

# Validate - Branch name
BRANCH_NAME=$(git symbolic-ref --short HEAD)
BRANCH_PATTERN="^(feature|bugfix|hotfix|release)/JIRA-[0-9]+.*$"
if [[ ! $BRANCH_NAME =~ $BRANCH_PATTERN ]]; then
  echo "❌ Branch name does not follow the required format!"
  echo "✅ Allowed format: '[feature|bugfix|hotfix|release]/JIRA-<number>*'"
  exit 1
fi

exit 0

Note: Adjust the BRANCH_PATTERN regex to match your team’s branch naming conventions.

# How to Validate Commit Messages?

To enforce commit message conventions, we can use the commit-msg hook.
This hook runs after a commit message is entered, allowing you to validate the commit message.

Steps:

1. Create a file named 'commit-msg' under the .git/hooks directory

2. Make the file executable by running the command:
chmod +x .git/hooks/commit-msg

3. Inside the file, copy and paste the script below

Script:

#!/bin/sh

# Validate - Commit message
COMMIT_MSG_FILE="$1"
COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
COMMIT_MSG_PATTERN="^JIRA-[0-9]+ - .+"
if ! echo "$COMMIT_MSG" | grep -qE "$COMMIT_MSG_PATTERN"; then
  echo "❌ Commit message does not follow the required format!"
  echo "✅ Allowed format: 'JIRA-<number> - *'"
  exit 1
fi

exit 0

Note: Adjust the COMMIT_MSG_PATTERN regex to match your team’s commit message conventions.

# Automate For Everyone

Unfortunately, Git Hooks are not shared across repositories by default because file changes in the .git directory are not tracked by Git 😢

To automate the setup of Git Hooks for everyone who clones the repository, it’s recommended to store the hook scripts in a /scripts directory at the root of the repository (so the scripts can be committed). Then, use a third-party library to install the hooks automatically.

The specific library you choose will depend on the type of codebase you’re working with. Here are some good options to consider:

• Node.js: Husky
• Python: Pre-commit

For Java, there are no widely used libraries available. Instead, you should add custom build steps to copy the hook scripts into the .git/hooks directory with your preferred build tool (e.g. Maven, Gradle).

# Wrap Up

Git Hooks are a simple yet powerful way to enforce branch naming and commit message conventions — using code instead of verbal reminders. Setting them up in any project makes life easier for everyone on the team.

Give it a shot, and happy coding!

Thanks for reading! 🚀

Ben Diep

Software Engineer