Commitizen

4.13.9 · active · verified Fri Apr 10

Commitizen is a Python client tool that standardizes commit messages, automates version bumping using Semantic Versioning, and generates changelogs. It helps development teams maintain consistent commit history and streamline release processes. The library is actively maintained with frequent patch releases, and the current version is 4.13.9.

Warnings

breaking Python 3.6 is no longer officially supported as of Commitizen v4.x. Users on older Python versions must upgrade their environment to Python 3.7 or greater (current minimum is 3.10).
Fix: Upgrade your Python environment to 3.10 or newer.
breaking For developers creating custom plugins, the way plugins are exposed changed in v4.x. They are now exposed as `commitizen.plugin` entrypoints.
Fix: Update custom plugins to use the `commitizen.plugin` entrypoint mechanism.
deprecated The `cz bump --files-only` CLI flag was deprecated in version 4.13.0 and has been replaced by `--version-files-only`.
Fix: Replace `--files-only` with `--version-files-only` in your `cz bump` commands.
gotcha When using `cz bump` in CI/CD pipelines, it might fail if there are no conventional commits eligible for a version bump (e.g., only 'chore' commits). This triggers a `NoneIncrementExit` (exit code 21).
Fix: Use the `--no-raise` flag or specifically ignore exit code 21 (`cz --no-raise NO_INCREMENT bump`) to allow the command to succeed without a version bump when no changes qualify.
gotcha If you need to pass Git-specific flags like `-s` (signoff) to `git commit` when using `cz commit`, you must use a double dash (`--`) to separate Commitizen's arguments from Git's. For example, `cz commit -- -s` is correct, while `cz commit -s` is deprecated and will not work as expected.
Fix: Prefix Git-specific arguments with `--`, e.g., `cz commit -- -s`.

Install

pip install commitizen Install with pip
pipx install commitizen Install with pipx (recommended for CLI tools)

Imports

Commitizen CLI
```
cz init
cz commit
cz bump
```
Commitizen is primarily a command-line interface (CLI) tool. Direct programmatic Python imports for end-user commit or bump functionality are not the standard usage pattern. The commands shown are for invoking the CLI.

Quickstart

To get started, initialize Commitizen in your project, which guides you through creating a configuration file (e.g., in `pyproject.toml` or `.cz.toml`). Then, use `cz commit` for an interactive prompt to create conventional commits, and `cz bump` to automatically increment your project's version and update the changelog based on these commits.

# 1. Initialize Commitizen in your Git repository (creates a .cz.toml or modifies pyproject.toml)
cz init

# 2. Use 'cz commit' instead of 'git commit' for guided, conventional commits
cz commit

# 3. Automatically bump version and generate changelog based on conventional commits
cz bump --changelog

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

view raw JSON →