Commitizen Documentation

Commitizen can be extended with third-party plugins available as PyPI packages. These plugins allow you to customize various aspects of the commit and versioning workflow.

Plugins can provide the following features:

• Commit message convention: Rules to validate and generate commit messages.
• Version scheme: Rules to generate version numbers.
• Version provider: Logic to read and write versions from specific data sources.
• Changelog format: Logic to generate changelogs in customized formats.

To automate commit message preparation, download the provided hooks into your .git/hooks directory and ensure they are executable. Run these commands from the root of your Git repository:

wget -O .git/hooks/prepare-commit-msg https://raw.githubusercontent.com/commitizen-tools/commitizen/master/hooks/prepare-commit-msg.py
chmod +x .git/hooks/prepare-commit-msg
wget -O .git/hooks/post-commit https://raw.githubusercontent.com/commitizen-tools/commitizen/master/hooks/post-commit.py
chmod +x .git/hooks/post-commit

You can use a custom template file located in your project root (the current working directory) using one of the following methods:

1. Filename matching: Name your template CHANGELOG.md.j2 (or the name specified by your custom BaseCommitizen class).
2. Configuration: Set the template key in your Commitizen configuration file to the relative path of your template.
3. CLI Flag: Pass the path to your template using the --template parameter with the bump or changelog commands.

Note: Paths are relative to the current working directory.

By default, Commitizen uses the latest Angular conventional commit types. While revert and chore are included in the cz check pattern to prevent errors, they are not available for selection in the standard interactive prompt.

To use these or any other non-standard types, you must create a customized cz configuration via a configuration file. Refer to the Customization guide for details on how to modify your configuration.

To use conventional commits with gitmojis in Commitizen, install the cz-conventional-gitmoji plugin via pip.

pip install cz-conventional-gitmoji

Install the commitizen-emoji plugin using pip. Note that this plugin is currently unmaintained.

pip install commitizen-emoji

When changing your tagging convention (e.g., moving from v1.0.0 to component-1.0.0), use the legacy_tag_formats setting to prevent losing version history.

By providing the old format in legacy_tag_formats, Commitizen can still recognize previous versions for changelog generation and version bumping via the scm provider. The next version bump will then use the new tag_format.

[tool.commitizen]
tag_format: component-${version}
legacy_tag_formats:
 - v${version}

You can install Commitizen using several methods depending on your environment.

Global Installation (Recommended)

Use pipx or uv to ensure an isolated installation.

Using pipx:

pipx install commitizen
pipx upgrade commitizen

Using uv:

uv tool install commitizen
uv tool upgrade commitizen

Using Homebrew (macOS):

brew install commitizen

Project-Specific Installation

Add Commitizen as a development dependency to your project.

Using pip:

pip install -U commitizen

Using conda:

conda install -c conda-forge commitizen

Using Poetry:

# For Poetry >= 1.2.0
poetry add commitizen --group dev

# For Poetry < 1.2.0
poetry add commitizen --dev

Using uv:

uv add --dev commitizen

Using pdm:

pdm add -d commitizen

Commitizen does not natively support CalVer (Calendar Versioning). It is designed around SemVer (Semantic Versioning).

If your project requires CalVer, you can still use Commitizen to standardize your commits and generate changelogs, but you should use a separate package or tool to handle the actual version increments.

Use the --prerelease flag to perform a pre-release bump. This adds a pre-release segment (phase and number) to the version. Supported phase names are alpha, beta, or rc (release candidate).

To control how pre-releases behave during increments, use --increment-mode:

• --increment-mode=linear (default): Maintains the current phase of higher precedence. For example, if the current version is 1.0.0b1, bumping with --prerelease alpha will continue to bump the beta phase (1.0.0b2).
• --increment-mode=exact: Always results in the specified phase. For example, --prerelease beta will always result in a b tag.

To undo a version bump that created a new tag and updated the changelog, run the following commands to delete the last tag and reset the local repository state (removing the commit that updated .cz.toml and the changelog):

git tag --delete <created_tag>
git reset HEAD~
git reset --hard HEAD

If the tag has already been pushed to a remote server, delete it from the origin using:

git push --delete origin <created_tag>