Posted inGit

Standardizing Commit Messages with Commitizen: Saying Goodbye to ‘fix bug’, ‘done’, and Automating CHANGELOGs

Git tutorial - IT technology blog
Git tutorial - IT technology blog

The Problem: When Git Log Becomes an Endless Maze

Have you ever opened the git log of an old project and frozen at messages like “fix bug”, “update”, “done”, or even “……”? After 3 months, you won’t even remember what logic you changed without inspecting every line of code. In reality, maintaining a clean commit history is often overlooked due to deadline pressure.

Conventional Commits was created to solve this problem. However, remembering when to use feat, fix, or the type(scope): description structure can be confusing. This is where Commitizen (cz-cli) shines. This tool turns writing commits into a short interview. You just select and answer; the computer handles the rest.

Quick Start: Installation and Usage in 5 Minutes

If your project uses Node.js, the setup is extremely simple. I usually install it directly into the project to ensure every team member follows the same standard.

Step 1: Install Commitizen and Adapter

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

Step 2: Initialize Configuration

Add the following configuration to the end of your package.json file:

"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
}

Step 3: Create an Execution Script

In the scripts section of package.json, add this line:

"scripts": {
  "commit": "cz"
}

Now, instead of typing git commit -m "..." based on a whim, you just need to run:

npm run commit

An interactive interface will appear in the terminal. Simply use the arrow keys to select the type of change (feat, fix, docs…) and fill in the description. The result is a perfectly formatted commit message, down to the last comma.

Why Should You Use Commitizen Instead of Typing Manually?

Many developers think typing manually is faster. However, in a team environment, different styles make the Git log chaotic.

1. Absolute Consistency

Commitizen forces everyone into a common framework. When the commit history is uniform, finding bugs becomes incredibly fast. For example, you can instantly filter commits related to the “Auth” module by searching for the keyword feat(auth).

2. Learn Standards Without Memorization

The cz-conventional-changelog adapter provides intuitive suggestions:

  • feat: Add a new feature.
  • fix: Technical bug fix.
  • docs: Update documentation.
  • style: Code formatting (whitespace, semicolons) without logic changes.
  • refactor: Restructuring code without adding features or fixing bugs.
  • perf: Performance optimization.
  • test: Adding or correcting test files.
  • chore: Minor changes to supporting tools or build processes.

Advanced: Automating CHANGELOGs with standard-version

This feature saves you hours of reporting time for every release. If you already have a standard commit history, creating a professional CHANGELOG.md file takes only seconds.

I once worked on an outsource project that required detailed listing of features and bug fixes for each sprint. Instead of manual copy-pasting, standard-version automated 100% of this process.

Installation and Configuration

npm install --save-dev standard-version

Add the script to package.json:

"scripts": {
  "release": "standard-version"
}

When you need to release a new version, simply run npm run release. The system will automatically perform four tasks:

  1. Scan all commits since the last release.
  2. Automatically bump the version in package.json according to SemVer standards.
  3. Update the CHANGELOG.md file with clearly categorized changes.
  4. Create a new git tag for that version.

Real-world Experience Implementing for a Team

In a team of 8 I once managed, adopting Commitizen helped reduce discussion time in review meetings by 30% because every change was clearly documented. Initially, some members found selecting from a menu annoying. But after a week, the benefits of understanding each other’s code faster convinced everyone.

Quick Tip: Use npx for Minimalism

If you don’t want to add scripts to the project, you can run it quickly with npx cz. However, ensure you’ve configured the adapter in the project so the questions appear as intended.

Combine with Husky to “Maintain Discipline”

To prevent “bypassing the rules” with standard git commit -m, combine it with Husky and commitlint. If a message doesn’t meet the standard, Git will immediately reject the commit. This ensures 100% of the commits in the repo stay clean.

Conclusion

Using Commitizen isn’t just for aesthetics. It’s about a professional product management mindset. A careful commit message is a gift to your future self and your colleagues when maintenance is needed. If your project is growing, install Commitizen today to build a solid DevOps workflow.

Share:
Tags: