Enforce Commit Standards with Commitlint and Husky commit-msg Hook

Your team's Git history tells a story. But is it a coherent one?

Look at these real commit messages from a typical project:

"fixed bug"
"Updated stuff"
"asdfasdf"
"PLEASE WORK THIS TIME"
"Fixed the fix that fixed the original fix"

Now imagine trying to:

Generate a changelog from these messages
Understand what changed between releases
Find when a specific feature was added
Track down which commit introduced a bug

Impossible.

This is where Conventional Commits and commitlint save your team. In this guide, you'll learn how to automatically enforce consistent, meaningful commit messages using commitlint with Husky's commit-msg hook.

The Team Collaboration Problem

When multiple developers work on the same repository without commit standards:

❌ Meaningless commit messages - "fix", "update", "wip"
❌ Inconsistent formatting - Everyone writes commits differently
❌ Hard to track changes - Can't tell what changed without reading code
❌ No automated changelogs - Can't generate release notes automatically
❌ Difficult debugging - Can't find which commit introduced issues
❌ Poor documentation - Git history doesn't tell the project story

The Solution: Conventional Commits + commitlint

We'll set up a system that:

✅ Enforces consistent format - Same structure for every commit
✅ Runs automatically - Validates on every commit attempt
✅ Provides clear feedback - Tells developers exactly what's wrong
✅ Enables automation - Changelogs, versioning, releases
✅ Improves collaboration - Everyone understands the history

The setup uses Conventional Commits (a specification), commitlint (validation tool), and Husky (Git hooks) to create a commit-msg hook that validates every commit message before it's created.

Prerequisites

This guide assumes you already have:

A project with Husky installed (see our pre-commit hooks guide)
Git initialized in your repository

If you don't have Husky yet, install it first:

npm install --save-dev husky
npx husky init

What are Conventional Commits?

Conventional Commits is a specification for commit messages with this structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples:

feat: add user authentication
fix: resolve login button styling issue
docs: update README with setup instructions
refactor(api): simplify error handling logic
feat(auth)!: change password requirements

Common Types

feat - A new feature
fix - A bug fix
docs - Documentation changes
style - Code style changes (formatting, semicolons, etc.)
refactor - Code refactoring (neither fixes bug nor adds feature)
perf - Performance improvements
test - Adding or updating tests
chore - Maintenance tasks (dependencies, config, etc.)
ci - CI/CD changes
build - Build system changes

Why This Matters for Teams

For Developers:

Clear structure reduces decision fatigue
Easy to write once you know the pattern
Better context when reviewing old commits

For Code Reviewers:

Quickly understand commit purpose from message alone
Easier to trace features and fixes
Better pull request organization

For Project Managers:

Automated changelog generation
Track feature delivery
Better release planning

For Everyone:

Searchable commit history (git log --grep="feat:")
Automated semantic versioning
Professional, maintainable codebase

Learn more about Conventional Commits

Step 1: Install commitlint

Install commitlint and the conventional config:

npm install --save-dev @commitlint/cli @commitlint/config-conventional

What these packages do:

@commitlint/cli - The commitlint command-line tool
@commitlint/config-conventional - Conventional Commits ruleset

Step 2: Configure commitlint

Create a commitlint.config.js file in your project root:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'ci',
        'build',
        'revert'
      ]
    ],
    'subject-case': [2, 'never', ['upper-case', 'pascal-case', 'start-case']],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'type-empty': [2, 'never'],
  }
};

Team benefit: This configuration becomes your team's commit message standard. Everyone follows the same rules, enforced automatically.

Alternative (JSON format):

Create .commitlintrc.json:

{
  "extends": ["@commitlint/config-conventional"]
}

The JavaScript version allows more customization, but the JSON version works fine for most teams.

Learn more about commitlint configuration

Step 3: Add Husky commit-msg Hook

Create the commit-msg hook:

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

This creates a .husky/commit-msg file with:

npx --no -- commitlint --edit $1

What this does:

Husky intercepts every commit attempt
Runs commitlint on the commit message
$1 is the file containing the commit message
If validation fails, the commit is rejected

Team benefit: Once this hook is committed to the repository, every team member automatically gets commit message validation after running npm install. No manual setup required.

Step 4: Commit Your Setup

Save your commitlint configuration:

git add .
git commit -m "chore: add commitlint with conventional commits"

Team milestone: Push this to your repository. From now on, every team member must follow Conventional Commits. No exceptions.

Step 5: Test Your commit-msg Hook

Let's test both valid and invalid commit messages.

❌ Test Invalid Commit

Try committing with a bad message:

git add .
git commit -m "fixed bug"

Result: Commit is rejected with an error:

⧗   input: fixed bug
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

✅ Test Valid Commit

Now try with a proper format:

git add .
git commit -m "fix: resolve login button bug"

Result: Commit succeeds! ✅

More Examples

Invalid commits (will be rejected):

git commit -m "Fixed the bug"              # No type
git commit -m "FEAT: add feature"          # Subject can't start with uppercase
git commit -m "feat:"                      # Empty subject
git commit -m "feat: Add new feature."     # No period at end
git commit -m "update: changed stuff"      # 'update' is not a valid type

Valid commits (will succeed):

git commit -m "feat: add user dashboard"
git commit -m "fix: resolve memory leak in data fetching"
git commit -m "docs: update API documentation"
git commit -m "refactor: simplify authentication logic"
git commit -m "test: add unit tests for user service"
git commit -m "chore: update dependencies"
git commit -m "feat(auth): add two-factor authentication"
git commit -m "fix(api)!: change response format"

How It Works

Here's the workflow that happens for every commit:

Developer writes code and stages changes
Developer runs git commit -m "message"
Husky intercepts the commit
The commit-msg hook triggers
commitlint validates the message format
If valid → commit succeeds
If invalid → commit is blocked with clear error message

Result: Only well-formatted commit messages make it into your repository.

The Team Workflow in Action

New Developer Joins

Clone the repository
Run npm install
Husky hooks automatically installed
First commit attempt teaches them the format
They quickly learn Conventional Commits

Developer Makes a Commit

Write code and stage changes
Try to commit: git commit -m "fixed bug"
Commit rejected with helpful error
Fix format: git commit -m "fix: resolve authentication bug"
Commit succeeds

Automated Benefits

Your team now gets:

Automated changelogs using tools like standard-version or semantic-release
Semantic versioning based on commit types (feat = minor, fix = patch)
Better git log that's actually readable and searchable
Clear project history anyone can understand

Advanced: Commit Message Templates

Help your team by providing a commit message template.

Create .gitmessage in your project root:

# <type>(<scope>): <subject>
# │      │         │
# │      │         └─⫸ Summary in present tense. Not capitalized. No period.
# │      │
# │      └─⫸ Commit Scope: api|ui|auth|db|etc
# │
# └─⫸ Commit Type: feat|fix|docs|style|refactor|perf|test|chore|ci|build
#
# Examples:
# feat: add email notifications
# fix: resolve navigation bug
# docs: update README
# feat(api): add user search endpoint
# fix(ui)!: change button styling (breaking change)

Configure git to use this template:

git config commit.template .gitmessage

Team benefit: When developers run git commit (without -m), they see this helpful template in their editor.

Customizing Rules for Your Team

You can customize commitlint rules in commitlint.config.js:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // Customize maximum subject length
    'subject-max-length': [2, 'always', 72],
    
    // Add custom types
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'ci',
        'build',
        'revert',
        'wip' // Custom type for work in progress
      ]
    ],
    
    // Require scope for certain types
    'scope-empty': [2, 'never'],
    
    // Custom scope values
    'scope-enum': [
      2,
      'always',
      ['api', 'ui', 'auth', 'db', 'config']
    ]
  }
};

Team consideration: Discuss and agree on customizations as a team. Don't make rules too strict or developers will find them frustrating.

Combining with Pre-commit Hooks

You now have two hooks working together:

Pre-commit hook (from previous guide):

Formats code with Prettier
Lints code with ESLint
Runs on staged files

Commit-msg hook (this guide):

Validates commit message format
Enforces Conventional Commits
Runs on commit message

Together, they ensure:

✅ Code is properly formatted
✅ Code passes linting
✅ Commit message follows standards

Your team now has a complete quality gate for every commit!

Documentation for Your Team

Add this to your README.md:

## Commit Message Guidelines

This project follows [Conventional Commits](https://www.conventionalcommits.org/).

### Format


### Types
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Code style changes
- **refactor**: Code refactoring
- **test**: Adding or updating tests
- **chore**: Maintenance tasks

### Examples

feat: add user authentication fix: resolve login button styling docs: update README with setup instructions


Commits are automatically validated. Invalid formats will be rejected.

What's Next?

This guide covered commit-msg hooks for enforcing commit standards. But there's more you can automate:

Pre-push hooks - Run tests before pushing to prevent broken code on remote
Branch naming validation - Enforce consistent branch names like feature/user-auth
Automated changelog generation - Use standard-version or semantic-release
Semantic versioning - Automatically bump versions based on commit types

Stay tuned for upcoming guides on these team collaboration topics!

Summary

You've successfully set up commit message validation:

✅ commitlint - Validates commit message format
✅ Conventional Commits - Consistent commit structure
✅ Husky commit-msg hook - Automatic enforcement
✅ Team standards - Everyone follows the same rules

Your team's Git history is now clean, searchable, and professional.

Key Team Benefits

Before commitlint:

"fixed bug"
"update"
"asdfasdf"
"PLEASE WORK"

After commitlint:

feat: add user authentication
fix: resolve memory leak in data fetching
docs: update API documentation
refactor: simplify error handling

The difference?

✅ Clear, professional commit history
✅ Automated changelog generation
✅ Easy to search and understand
✅ Better team collaboration
✅ Semantic versioning support

References

Conventional Commits Specification
commitlint Documentation
Husky Documentation
standard-version - Automated changelog and versioning
semantic-release - Fully automated release workflow

Building a professional development team? Share this guide! Got questions about commit standards? Drop a comment below. 🚀