commitlint

Appearance

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 (currently pre-commit hook is not supported)

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.

NOTE

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

WARNING

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.

sh
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
# Windows users should use ` to escape dollar signs
echo "npx --no commitlint --edit `$1" > .husky/commit-msg

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

sh
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.

WARNING

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

Test ​

Test simple usage ​

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

bash
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.

bash
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: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

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)

bash
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.