A flexible Commitizen setup for your team
Commitizen is a tool to help format commit messages against standards such as Conventional Commits.
With a variety of different configurations, I figured it's worth documenting a setup I've found works well.
NOTE
If you're interested in introducing Commitizen to a project then it's worth bringing up with teammates first to gauge interest.
A team is more likely to adhere to a standard they all agreed to rather than one pushed on them.
The key requirements this setup solves are;
- Conventional Commits style formatted commit messages
- The ability for committers to commit without going through the Commitizen CLI if they don't want to
- The option for committers to either use their own global Commitizen or the locally installed one
- Commit message linting to ensure the commit follows the correct format no matter how it's entered
Given those requirements, here's how to get your repository set up.
First install the Commitizen CLI tool globally:
npm install -g commitizen
Next, use Commitizen to initialise the cz-conventional-changelog
adapter in your project:
commitizen init cz-conventional-changelog --save-dev --save-exact
You can then add a local command to allow teammates to run Commitizen without having to set it up globally if they don't want to.
Add the following script to your package.json under the scripts
object:
"cz": "cz"
That's it, that's all you need to tick off the first three requirements.
✅ Conventional Commits style formatted commit messages
The cz-conventional-changelog
adapter handles this.
✅ The ability for committers to commit without going through the Commitizen CLI if they don't want to.
git cz
, npm run cz
or git commit
will all allow you to commit, with the latter bypassing the Commitizen CLI prompts if preferred.
It's worth documenting this in the project readme to ensure users know they have options when it comes to committing. I've used the following before:
Conventional Commits
This repo follows the Conventional Commits specification.
It uses Commitizen to help write commits in the correct format.
You can run either
npm run cz
or set up commitizen globally and rungit cz
.If you'd prefer to write your commit message manually you can. We use Commitlint which will pick up any formatting issues before finalising your commit.
✅ The option for committers to either use their own global Commitizen or the locally installed one
git cz
will work for users who have Commitizen set up globally and npm run cz
will work for those that don't.
That's everything required to write commits.
Let's add commit message linting to ensure commits always conform to the standards set.
Start by installing commitlint
:
npm install --save-dev @commitlint/{config-conventional,cli}
Then add a commitlint
config object to your package.json
:
"commitlint": {
"extends": [
"@commitlint/config-conventional"
]
}
Next, if you're not already using it, you'll need to install husky
to run linting on commit:
npm install husky --save-dev
Finally, add a husky config object to your package.json
with a commit-msg
hook:
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
Linting will now take place upon each commit. This linting can be especially useful for committers who want to write their commit message manually.
This tackles our last requirement:
✅ Commit message linting to ensure the commit follows the correct format no matter how it's entered
There we go, that's everything needed to help keep commit messages consistent.
I've found this setup to be prescriptive whilst not being too limiting on the workflows people may already have.
Of course, your mileage may vary so any tweaks, suggestions or improvements are more than welcome.