A flexible Commitizen setup for your team

07 Oct 2020

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 run git 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.