Mastering Conventional Commit Messages with Commitizen, Commitlint, and Husky

What Standard Should You Use?

The most popular solution today is the Conventional Commits specification, inspired by the Angular commit guidelines. It offers a lightweight, version‑control‑friendly convention that aligns with SemVer, making it easy to generate clear commit histories and automate tooling.

Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer]

Quick Start

1. Install Commitizen & cz-conventional-changelog globally

Commitizen helps you write proper commit messages instead of using raw git commit. The cz-conventional-changelog adapter implements the Conventional Commits standard.

npm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

After installation you can run git cz to replace git commit.

2. Install commitlint & husky in the project

commitlint

validates the format of commit messages, while husky provides easy-to‑use Git hooks.

# Using npm
npm i -D husky @commitlint/config-conventional @commitlint/cli

# Using yarn
yarn add -D husky @commitlint/config-conventional @commitlint/cli

3. Add configuration

Create commitlint.config.js in the same directory as package.json:

module.exports = {extends: ["@commitlint/config-conventional"]};

Configure husky in package.json:

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -e $GIT_PARAMS"
    }
  }
}

4. Use the workflow

Run git cz to enter an interactive prompt and fill in the fields:

1. Select the type of change (type)
2. Specify the scope (scope)
3. Write a short description (subject)
4. Provide a longer description (body) – optional
5. Indicate breaking changes? (footer) – optional
6. Reference issues? (footer) – optional

The generated commit message follows the format shown above, with type and subject required.

Commit Message Specification Used in rrd‑fe

1. type

Required. Main types are feat (new feature) and fix (bug fix). Additional types include docs, style, build, refactor, and revert. Other types are currently unused.

# Main types
feat:     add new feature
fix:      fix a bug

# Additional types
docs:     documentation changes
style:    formatting changes
build:    build tool or dependency changes
refactor: code refactoring
revert:   revert a previous commit

2. scope

Required. Describes the affected module using the format project/module, e.g., node-pc/common or rrd-h5/activity. If the change applies to the whole project, only the project name is needed.

3. body

Optional but recommended for significant changes. It should explain the previous state and the motivation for the modification.

4. break changes

Indicates whether the change introduces a breaking API change, version bump, or migration.

5. affect issues

Links the commit to issue tracker IDs (e.g., JIRA IDs) when applicable.

Examples

Full commit message example (image)

Corresponding git log (image)