Commitizen

Git Tools•

•Python

Interactive commit message creator for Conventional Commits.

Official Website

Features

Interactive CommitConventional CommitsChangelog GenerationVersion Bumping

Installation

Homebrew

brew install commitizen

npm

npm install -g commitizen

pip

pip install commitizen

Why Use Commitizen?

Commitizen is a tool that creates commit messages through an interactive interface. Easily create consistent commit messages following the Conventional Commits convention, and leverage automatic CHANGELOG generation and semantic versioning.

Interactive Input

Enter commit type, scope, and description step by step through an interactive interface. No need to memorize commit message format.

Conventional Commits

Use standard commit types like feat, fix, docs. Maintain consistent commit history across the entire team.

Automatic CHANGELOG Generation

Automatically generate CHANGELOG from convention-compliant commits. Create release notes easily.

Team Standardization

Customizable per project. Enforce commit message formats that match team rules.

Conventional Commits Convention

Commit Message Format

=.repeat(50)

<body>

=.repeat(50)

Example:

feat(auth): add login with OAuth

Add Google and GitHub OAuth providers

for user authentication.

Closes #123

Type	Description	Example
`feat`	Add new feature	feat: add user registration
`fix`	Bug fix	fix: resolve login error
`docs`	Documentation only changes	docs: update README
`style`	Changes that do not affect code meaning	style: format code
`refactor`	Code refactoring	refactor: simplify logic
`perf`	Performance improvement	perf: optimize query
`test`	Add or modify tests	test: add unit tests
`build`	Build system changes	build: update webpack
`ci`	CI configuration changes	ci: add GitHub Actions
`chore`	Other changes	chore: update deps

Installation

Node.js Version (Recommended)

Node.js Installation

# Global installation
npm install -g commitizen cz-conventional-changelog

# Install in project
npm install --save-dev commitizen cz-conventional-changelog

# Add configuration to package.json
npx commitizen init cz-conventional-changelog --save-dev --save-exact

# Or manually add to package.json
{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }
}

Python Version (cz-cli)

Python Installation

# Install with pip
pip install commitizen

# Or global install with pipx
pipx install commitizen

# Check version
cz version

Basic Usage

Creating Commits

Execute Commit

# Node.js version: commit using commitizen
git cz
# or
npx cz

# Python version: commit using commitizen
cz commit
# or
cz c

Interactive Flow

? Select the type of change that you are committing:

> feat: A new feature

fix: A bug fix

docs: Documentation only changes

style: Changes that do not affect the meaning

refactor: A code change that neither fixes a bug

...

? What is the scope of this change (e.g. component or file name)?

auth

? Write a short, imperative tense description of the change:

add login with OAuth

? Provide a longer description of the change (optional):

Add Google and GitHub OAuth providers...

? Are there any breaking changes?

? Does this change affect any open issues?

Closes #123

Settings and Customization

Node.js Version Configuration

package.json / .czrc

// package.json
{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  },
  "scripts": {
    "commit": "cz"
  }
}

// or .czrc file
{
  "path": "cz-conventional-changelog"
}

Python Version Configuration

pyproject.toml

# pyproject.toml
[tool.commitizen]
name = "cz_conventional_commits"
version = "1.0.0"
tag_format = "v$version"
version_files = [
    "pyproject.toml:version",
    "src/__init__.py:__version__"
]

# Custom commit types
[tool.commitizen.customize]
message_template = "{{change_type}}{% if scope %}({{scope}}){% endif %}: {{message}}"
example = "feat(auth): add login feature"
schema = """
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
"""

[[tool.commitizen.customize.questions]]
type = "list"
name = "change_type"
choices = [
    {value = "feat", name = "feat: A new feature"},
    {value = "fix", name = "fix: A bug fix"},
    {value = "docs", name = "docs: Documentation changes"},
    {value = "style", name = "style: Code style changes"},
    {value = "refactor", name = "refactor: Code refactoring"},
    {value = "perf", name = "perf: Performance improvements"},
    {value = "test", name = "test: Adding tests"},
    {value = "build", name = "build: Build system changes"},
    {value = "ci", name = "ci: CI configuration changes"},
    {value = "chore", name = "chore: Other changes"}
]
message = "Select the type of change you are committing"

Custom Adapter (Node.js)

cz-config.js

// cz-config.js (for cz-customizable)
module.exports = {
  types: [
    { value: 'feat', name: 'feat:     New feature' },
    { value: 'fix', name: 'fix:      Bug fix' },
    { value: 'docs', name: 'docs:     Documentation' },
    { value: 'style', name: 'style:    Style' },
    { value: 'refactor', name: 'refactor: Refactoring' },
    { value: 'perf', name: 'perf:     Performance' },
    { value: 'test', name: 'test:     Tests' },
    { value: 'chore', name: 'chore:    Other' },
  ],
  scopes: [
    { name: 'auth' },
    { name: 'api' },
    { name: 'ui' },
    { name: 'config' },
  ],
  messages: {
    type: 'Select the type of commit:',
    scope: 'Select a scope (optional):',
    subject: 'Write a short description of the change:',
    body: 'Provide a longer description (optional):',
    breaking: 'Are there any breaking changes?:',
    footer: 'Enter related issue number (optional):',
    confirmCommit: 'Is this commit OK?',
  },
  allowBreakingChanges: ['feat', 'fix'],
  subjectLimit: 72,
};

Automatic CHANGELOG Generation

Python Version (commitizen)

CHANGELOG Generation

# Generate CHANGELOG.md
cz changelog

# Generate CHANGELOG for specific version range
cz changelog --start-rev v1.0.0

# Dry run (does not actually generate)
cz changelog --dry-run

Node.js Version (conventional-changelog)

conventional-changelog

# Install conventional-changelog
npm install -g conventional-changelog-cli

# Generate CHANGELOG.md (append to existing file)
conventional-changelog -p angular -i CHANGELOG.md -s

# Generate from scratch
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

# Add script to package.json
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

Example Generated CHANGELOG

CHANGELOG.md

# Changelog

## [1.2.0](https://github.com/user/repo/compare/v1.1.0...v1.2.0) (2024-01-15)

### Features

* **auth:** add login with OAuth ([abc1234](https://github.com/user/repo/commit/abc1234))
* **api:** add new endpoint for user profile ([def5678](https://github.com/user/repo/commit/def5678))

### Bug Fixes

* **ui:** fix button alignment on mobile ([ghi9012](https://github.com/user/repo/commit/ghi9012))

### BREAKING CHANGES

* **api:** removed deprecated /v1/users endpoint

Version Management

Version Bump

# Python version: bump version (auto-determined based on commit types)
cz bump

# Major version bump
cz bump --increment MAJOR

# Minor version bump
cz bump --increment MINOR

# Patch version bump
cz bump --increment PATCH

# Dry run
cz bump --dry-run

# Also update CHANGELOG
cz bump --changelog

# Skip tag creation
cz bump --no-tag

Version is automatically determined based on commit types:feat → MINOR、fix → PATCH、BREAKING CHANGE → MAJOR

Git Hooks Integration

Husky + commitlint

# Install husky and commitlint
npm install --save-dev husky @commitlint/cli @commitlint/config-conventional

# Initialize husky
npx husky install

# Add commit-msg hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

# Create commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']
    ],
    'subject-case': [2, 'never', ['start-case', 'pascal-case', 'upper-case']],
  }
};

pre-commit (Python Version)

.pre-commit-config.yaml

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/commitizen-tools/commitizen
    rev: v3.13.0
    hooks:
      - id: commitizen
        stages: [commit-msg]

Tips

*Recommended to write commit messages in English. Maintain consistency if using other languages
*scope is optional but recommended for large projects
*Breaking changes (BREAKING CHANGE) should be documented in footer or with ! after type (e.g., feat!:)
*Combining with commitlint prevents non-conforming commits
*Setting npm run commit or git cz as aliases is convenient
*VSCode extension "Conventional Commits" allows input from editor

Official Resources

Commitizen (Node.js): https://github.com/commitizen/cz-cli
Commitizen (Python): https://commitizen-tools.github.io/commitizen/
Conventional Commits: https://www.conventionalcommits.org/
commitlint: https://commitlint.js.org/

pre-commit - Git Hook Framework

Framework for managing multi-language pre-commit hooks

tools8 min read

git commit Command Guide

Record changes to the repository

git6 min read

Explore More

Browse Git Tools

See all tools in this category

All CLI Tools

Explore all tool categories

Features

Installation

Why Use Commitizen?

Interactive Input

Conventional Commits

Automatic CHANGELOG Generation

Team Standardization

Conventional Commits Convention

Installation

Node.js Version (Recommended)

Python Version (cz-cli)

Basic Usage

Creating Commits

Interactive Flow

Settings and Customization

Node.js Version Configuration

Python Version Configuration

Custom Adapter (Node.js)

Automatic CHANGELOG Generation

Python Version (commitizen)

Node.js Version (conventional-changelog)

Example Generated CHANGELOG

Version Management

Git Hooks Integration

Husky + commitlint

pre-commit (Python Version)

Tips

Official Resources

Related Articles

pre-commit - Git Hook Framework

git commit Command Guide

Explore More