Skip to content

Guide: Local setup

Get high commit message quality and short feedback cycles by linting commit messages right when they are authored.

This guide demonstrates how to achieve this via git hooks.

Follow the Getting Started for basic installation and configuration instructions.

Add hook

To use commitlint you need to setup commit-msg hook

Using a git hooks manager

To lint commits before they are created you can use Husky's commit-msg hook.

You can find complete setup instructions on the official documentation.


The following instructions are meant to husky@v9 if you are using a different version consult the official documentation of your version.


For Windows users: ensure all husky files are UTF-8 enconded. If any other format is used an error may be thrown at runtime such as cannot execute binary file.

npm install --save-dev husky

npx husky init

# Add commit message linting to commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

As an alternative you can create a script inside package.json

npm pkg set scripts.commitlint="commitlint --edit"
echo "npm run commitlint \${1}" > .husky/commit-msg

Using git hooks

Info about git hooks can be found on Git documentation.


It's necessary that you use commit-msg as the name for hook file.


Test simple usage

For a first simple usage test of commitlint you can do the following:

npx commitlint --from HEAD~1 --to HEAD --verbose

This will check your last commit and return an error if invalid or a positive output if valid.

Test the hook

You can test the hook by simply committing. You should see something like this if everything works.

git commit -m "foo: this will fail"
#  husky > commit-msg
No staged files match any of provided globs.
   input: foo: this will fail
   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

   found 1 problems, 0 warnings
   Get help:

husky - commit-msg script failed (code 1)

Since v8.0.0 commitlint won't output anything if there are no problems with your commit.
(You can use the --verbose flag to get positive output)

git commit -m "chore: lint on commitmsg"
# husky > pre-commit
No staged files match any of provided globs.
# husky > commit-msg

?> Local linting is fine for fast feedback but can easily be tinkered with. To ensure all commits are linted you'll want to check commits on an automated CI Server too. Learn how to in the CI Setup guide.