Git Commit Templates: Enforcing Consistent Commit Messages in a Team

1. Why inconsistent commit messages get expensive

A commit history is, in the best case, a readable chronicle that explains why a change happened, not just what changed. In practice, the history of many repositories looks different: messages like fix, update, or wip sit next to detailed paragraphs with no recognizable pattern. Anyone later searching with git log or git blame for the reason behind a change often finds nothing usable, even though the information technically exists, just not in a structured form.

The problem gets worse as the team grows, because every developer brings their own style and keeps it unless a convention says otherwise. A reviewer can flag an unclear message in a pull request, but that costs time and rarely changes behavior long term, since the correction always happens after the fact. A commit template addresses this directly by shaping the structure in the editor before the commit is even created, which noticeably raises the odds of a useful message.

2. Basics: commit.template and .gitmessage

Git lets you point to a text file that appears as a starting point in the editor whenever git commit is run without -m. The configuration option is commit.template, pointing to any file, typically .gitmessage in the home directory or inside the repository itself. Anything in that file starting with a hash is treated as a comment and stripped automatically from the final message on save, so the template can freely include hints and examples without polluting the actual message.

For a single repository a local git config setting is enough; for a whole team it makes more sense to version the template as a file inside the repository and document the configuration step in a setup script or the README. That way every new hire sees the same template without having to type it out manually.

# Store the template inside the repository
cat > .gitmessage <<'EOF'
# <type>(<scope>): <short summary, max 50 chars>
#
# More detailed explanation of the why, not just the what.
# Wrap body lines around 72 characters.
#
# Ticket reference, e.g. Refs: JIRA-123
EOF

# Configure it for this repository
git config commit.template .gitmessage

# Configure it globally for a developer across all repositories
git config --global commit.template ~/.gitmessage

3. Structuring a good template file

A proven structure follows the Conventional Commits format, because it is readable for humans and can also be parsed by tooling, for example to generate a changelog automatically. It consists of a type such as feat, fix, docs, or refactor, an optional scope in parentheses, and a short imperative summary, followed by a blank line and a more detailed body.

The template should include concrete examples rather than abstract placeholders alone, because developers under time pressure are more likely to copy and adapt an example than to reconstruct a rule from memory. A note about the maximum length of the first line also helps, since many tools, including GitHub and GitLab, truncate that first line in list views, and an overly long summary becomes unreadable there.

4. Local setup versus team-wide rollout

A purely local template that each developer sets up manually only works as long as nobody forgets to set it up, which happens regularly with new team members or freshly cloned machines. It is more reliable to make the template and its configuration part of an onboarding script that already runs during initial setup, alongside dependency installation or git hooks.

Since commit.template itself cannot be versioned, being a local configuration option, the template stays only a recommendation until it is enforced technically. The next step is therefore always a server side or CI based check that works independently of the local setup.

#!/usr/bin/env bash
# scripts/setup-git.sh, part of the onboarding process
set -euo pipefail

git config commit.template .gitmessage
git config core.hooksPath .githooks

echo "Git commit template and hooks configured."

5. Enforcement with the local commit-msg hook

A commit-msg hook receives the path to the temporary file holding the typed commit message as an argument and can abort the commit with an error code before it is created at all. That makes it possible to check technically whether a message matches the required format, for example with a regular expression against the Conventional Commits schema.

The hook lives in the .git/hooks directory, which is not versioned, so it must either be redirected to a versioned directory via core.hooksPath or installed through a tool such as Husky. Note that the hook only runs locally and can be bypassed by any developer with --no-verify, so on its own it does not provide reliable enforcement, only fast feedback right at commit time.

#!/usr/bin/env bash
# .githooks/commit-msg
MSG_FILE="$1"
PATTERN='^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-z0-9_-]+\))?: .{1,50}'

if ! grep -qE "$PATTERN" "$MSG_FILE"; then
  echo "Commit message does not match the required format." >&2
  echo "Example: feat(checkout): add coupon validation" >&2
  exit 1
fi

6. Binding enforcement with commitlint in CI

Because local hooks can be bypassed, the actual enforcement belongs in the CI pipeline, where it is no longer optional. The tool commitlint checks commit messages against a configurable rule set and is typically run with the preset configuration for Conventional Commits. In the pipeline, one job is enough to check every new commit in a merge request or pull request against the rule set and fail on violation.

This check should run as early as possible in the pipeline, since it is fast and has no dependency on build or test steps. A failed commitlint job also gives the developer a precise error message naming the violated rule, which makes fixing it much easier than a generic rejection in review.

# commitlint.config.js
module.exports = { extends: ["@commitlint/config-conventional"] };

# In the CI pipeline, e.g. GitLab CI or GitHub Actions
npx commitlint --from=origin/main --to=HEAD --verbose

7. Interactive support with Commitizen

Instead of relying on developers to remember the format, an interactive tool such as Commitizen can ask for the message step by step: type, scope, summary, detailed description, and breaking change notes are collected one at a time and assembled into a compliant message at the end. It is invoked with git cz instead of git commit, and practically always produces a valid message without the developer having to keep the format in mind.

The benefit over a plain text template lies in the guided input, which effectively rules out typos in the type field, since the value comes from a list rather than free text. Combined with the commit-msg hook as a fallback for developers who still use git commit directly, this achieves high format consistency without dictating which tool every workflow has to use.

8. Automated changelogs from commit messages

A structured commit format pays off most visibly once a changelog is generated from it automatically. Tools such as conventional-changelog or release-please read the commit history since the last release, group the entries by type, and produce a structured release note without a human having to summarize the changes manually.

This automation only works reliably if the underlying commit messages are actually consistent, which gives teams a very concrete incentive to take enforcement seriously: a single commit with the wrong type either drops out of the changelog entirely or lands in the wrong category, which is noticed quickly and raises the motivation for clean messages in daily work.

9. Rolling it out in an existing repository

In a repository with a long history, it is not worth retroactively rewriting old commit messages, since that would massively rewrite history via git rebase and cause conflicts for everyone who already has a clone. Instead, the new rule is introduced from a fixed point in time, usually the next release tag, and the commitlint job in CI only checks commits created after that point.

A gentle rollout runs the CI check as a warning first, before it becomes a mandatory check after a transition period of a few weeks that actually blocks a failing merge request. That way the team gets used to the new format before it becomes binding, and acceptance ends up considerably higher than with an immediate hard cutover.

10. Summary

11. FAQ: Commit Templates