How We Use Commitizen to Clean Up Commit Messages

Developers all have their own ways of formatting commit messages. One developer might put a short message and another might specify the type of changes made and include a JIRA ticket number.

These inconsistencies make it difficult to sift through the commit history. So we wanted to standardize our commit messages for our CMS app.

In order to have a more meaningful and tidy commit history, we wanted to include the type of commit, the JIRA ticket number, and a short description. We decided on using Commitizen to enforce this new standard.

Commitizen is a command line tool that helps format commit messages with a series of prompts that are used to generate a commit message. This tool can be installed globally with

npm install commitizen -g

Additionally, this should be specified as a dev dependency in package.json

npm install commitizen --save-dev

Now, instead of committing with

git commit

we use

git cz

In order to get Commitizen working, we need to set up configuration by specifying an adapter in package.json. The adapters specify the prompts when committing. There are many adapters to choose from here. For our project we decided on using the cz-conventional-changelog, and we should also save this as a dev dependency.

npm install cz-conventional-changelog --save-dev

Next we set up the adapter in package.json with

commitizen init cz-conventional-changelog --save-dev --save-exact

The format for cz-conventional-changelog is

type(scope): JIRA-Ticket - Short description

The prompts ask for type, scope, short description, long description and breaking changes. “Type” specifies the category of the commit (chore, feat, fix, etc.). “Scope” refers to the group of files changed. “Short description” is the description that goes into the first line of the commit. “Long description” is a multiline description that starts on the second line of the commit. “Breaking changes” follows the long description in the commit message. We left “long description” and “breaking changes” as optional.

The adapter we chose does not have a prompt for the JIRA ticket readily available. So instead we are running validation on the first line of the commit. We set up this validation by using the tools Husky and validate-commit-message.

First, install both as dev dependencies

npm install husky --save-dev
npm install validate-commit-msg --save-dev

Husky is a tool that allows us to easily tie in to git-hooks by specifying a git-hook, whereas validate-commit-message will use a regex to validate the subject. We manually set up the configuration for validate-commit-message in package.json under “config"

"validate-commit-msg": {
  "types": [
    "feat",
    "fix",
    "docs",
    "style",
    "refactor",
    "perf",
    "test",
    "chore",
    "revert"
  ],
  "warnOnFail": false,
  "maxSubjectLength": 100,
  "subjectPattern": "^[A-Z]+-[0-9]+ - .*",
  "subjectPatternErrorMsg": "Subject must be in format 'CMS-123 - Commit message'",
  "helpMessage": ""
}

Here we specify the maxSubjectLength as 100 characters, subjectPattern matching regex and an error message for pattern matching. The subject must start with the JIRA ticket followed by a dash.

Initially, we set up the maxSubjectLength to be 72 characters to prevent truncated commit messages in GitHub. This limit was later increased to 100 because the type, scope and JIRA ticket would not leave much room for the short description.

Finally, we tie the validation with the commit-msg git-hook by setting the following under “scripts" in package.json

"commitmsg": "validate-commit-msg"

Commitizen should now be set up in your project and ready for you to start using it!

Bonus tip: Since we spent so much time making sure the first line of the commit was in a format we preferred, we can use

git log --oneline

to view a condensed version of of the git logs. I set this up as an alias for this in .gitconfig

ls = log --oneline