Mastering Commit Message Standards with Conventional Commits, Commitizen, and Husky
This guide explains why a commit‑message convention is essential for Git workflows, introduces the Conventional Commits specification, and provides a step‑by‑step quick‑start using Commitizen, cz‑conventional‑changelog, Commitlint, and Husky to enforce consistent, high‑quality commit messages across a project.
Git is the most popular version‑control tool, and well‑written commit messages greatly improve code‑maintenance efficiency. However, without constraints, messages are often arbitrary and low‑quality, making them hard to read and maintain. Introducing a commit‑message standard is therefore urgent.
What standard should be used?
The most popular solution today is the Conventional Commits specification, inspired by the Angular commit guidelines. It provides a lightweight, message‑based convention that aligns with SemVer and makes it easier to build automation tools. The message format is:
<type>[optional scope]: <description>
[optional body]
[optional footer]Quick Start
1. Globally install Commitizen & cz‑conventional‑changelog
commitizenis a tool for writing qualified commit messages, replacing the git commit command. The cz‑conventional‑changelog adapter provides the Conventional Commits standard. Different adapters can be used based on needs.
npm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrcAfter installation, you can run git cz instead of git commit.
In global mode, the ~/.czrc file configures Commitizen to use the chosen adapter.
2. Install Commitlint & Husky in the project
commitlintvalidates the format of commit messages, while husky provides easy-to‑use Git hooks.
# Use npm
npm i -D husky @commitlint/config-conventional @commitlint/cli
# Use yarn
yarn add husky @commitlint/config-conventional @commitlint/cli -Dcommitlintonly enforces formatting; content quality must be ensured manually.
3. Add the corresponding configuration
Create commitlint.config.js:
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 interactive mode and fill in the prompts:
1. Select the type of change (<type>)
2. What is the scope of this change (<scope>)?
3. Write a short, imperative description (<subject>)
4. Provide a longer description (<body>)
5. Are there any breaking changes? (y/n) (<footer>)
6. Does this change affect any open issues? (y/n) (<footer>)The generated commit message looks like:
<type>(<scope>): <subject>
<body>
<footer>After completion, Husky triggers Commitlint to validate the message; type and subject are required fields.
All options of git commit can be used with git cz, e.g., git cz -a.
Commit Message Standard in rrd‑fe
Based on team discussion, the following rules were defined for each part of the commit message.
1. type
typeis mandatory and indicates the kind of change. The primary types are feat (new feature) and fix (bug fix). Additional special types include docs, style, build, refactor, and revert. Other types are currently unused.
# Primary types
feat: add new feature
fix: fix a bug
# Special types
docs: documentation only changes
style: code style changes (e.g., whitespace, semicolons)
build: changes to build tools or external dependencies
refactor: code refactoring
revert: revert a previous commit
# Unused types
test: add or modify tests
perf: performance improvements
ci: CI related changes
chore: other changes that do not affect src or testIf a change involves both a primary and a special type, only the primary type is used.
2. scope
scopeis also required and describes the area of impact, formatted as project/module , e.g., node-pc/common or rrd-h5/activity. For packages like we-sdk, the module name is omitted. If a commit touches multiple modules, split it into separate commits.
3. body
bodyprovides a detailed description, covering the situation before the change and the motivation for the modification. Small changes may omit it, but major features or updates must include a body.
4. break changes
break changesindicates whether the commit introduces breaking changes, such as version upgrades, removed or altered APIs, or migrations. This field must be filled for any breaking change.
5. affect issues
affect issueslinks the commit to a specific issue (e.g., a JIRA ID). Integration with JIRA and GitLab is required to enable this feature.
re #JIRA_ID
fix #JIRA_IDSigned-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
21CTO
21CTO (21CTO.com) offers developers community, training, and services, making it your go‑to learning and service platform.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.