Documentation: https://commitizen-tools.github.io/commitizen/

Commitizen is a powerful release management tool that helps teams maintain consistent and meaningful commit messages while automating version management.

By enforcing standardized commit conventions (defaulting to Conventional Commits), Commitizen helps teams:

• Write clear, structured commit messages
• Automatically manage version numbers using semantic versioning
• Generate and maintain changelogs
• Streamline the release process

With just a simple cz bump command, Commitizen handles:

1. Version Management: Automatically bumps version numbers and updates version files based on your commit history
2. Changelog Generation: Creates and updates changelogs following the Keep a changelog format
3. Commit Standardization: Enforces consistent commit message formats across your team

This standardization makes your commit history more readable and meaningful, while the automation reduces manual work and potential errors in the release process.

• Command-line utility to create commits with your rules. Defaults: Conventional commits
• Bump version automatically using semantic versioning based on the commits. Read More
• Generate a changelog using Keep a changelog
• Update your project's version files automatically
• Display information about your commit rules (commands: schema, example, info)
• Create your own set of rules and publish them to pip. Read more on Customization

Before installing Commitizen, ensure you have:

• Python 3.9+
• Git 1.8.5.2+

The recommended way to install Commitizen is using pipx, which ensures a clean, isolated installation:

# Install pipx if you haven't already
pipx ensurepath

# Install Commitizen
pipx install commitizen

# Keep it updated
pipx upgrade commitizen

If you're on macOS, you can also install Commitizen using Homebrew:

brew install commitizen

You can add Commitizen to your Python project using any of these package managers:

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

To get started, you'll need to set up your configuration. You have two options:

1. Use the interactive setup:

cz init

2. Manually create a configuration file (.cz.toml or cz.toml):

[tool.commitizen]
version = "0.1.0"
update_changelog_on_bump = true

Create standardized commits using:

cz commit
# or use the shortcut
cz c

To sign off your commits:

cz commit -- --signoff
# or use the shortcut
cz commit -- -s

For more commit options, run cz commit --help.

The most common command you'll use is:

cz bump

This command:

• Bumps your project's version
• Creates a git tag
• Updates the changelog (if update_changelog_on_bump is enabled)
• Updates version files

You can customize:

• Version files
• Version scheme
• Version provider

For all available options, see the bump command documentation.

To get your project's version (instead of Commitizen's version):

cz version -p

This is particularly useful for automation. For example, to preview changelog changes for Slack:

cz changelog --dry-run "$(cz version -p)"

Commitizen can automatically validate your commit messages using pre-commit hooks.

1. Add to your .pre-commit-config.yaml:

---
repos:
  - repo: https://github.com/commitizen-tools/commitizen
    rev: master  # Replace with latest tag
    hooks:
      - id: commitizen
      - id: commitizen-branch
        stages: [pre-push]

2. Install the hooks:

pre-commit install --hook-type commit-msg --hook-type pre-push

Note: Replace master with the latest tag to avoid warnings. You can automatically update this with:

pre-commit autoupdate

For more details about commit validation, see the check command documentation.

$ cz --help
usage: cz [-h] [--config CONFIG] [--debug] [-n NAME] [-nr NO_RAISE] {init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version} ...

Commitizen is a cli tool to generate conventional commits.
For more information about the topic go to https://conventionalcommits.org/

options:
  -h, --help            show this help message and exit
  --config CONFIG       the path of configuration file
  --debug               use debug mode
  -n, --name NAME       use the given commitizen (default: cz_conventional_commits)
  -nr, --no-raise NO_RAISE
                        comma separated error codes that won't rise error, e.g: cz -nr 1,2,3 bump. See codes at https://commitizen-tools.github.io/commitizen/exit_codes/

commands:
  {init,commit,c,ls,example,info,schema,bump,changelog,ch,check,version}
    init                init commitizen configuration
    commit (c)          create new commit
    ls                  show available commitizens
    example             show commit example
    info                show information about the cz
    schema              show commit schema
    bump                bump semantic version based on the git log
    changelog (ch)      generate changelog (note that it will overwrite existing file)
    check               validates that a commit message matches the commitizen schema
    version             get the version of the installed commitizen or the current project (default: installed commitizen)

When using bash as your shell (limited support for zsh, fish, and tcsh is available), Commitizen can use argcomplete for auto-completion. For this, argcomplete needs to be enabled.

argcomplete is installed when you install Commitizen since it's a dependency.

If Commitizen is installed globally, global activation can be executed:

sudo activate-global-python-argcomplete

For permanent (but not global) Commitizen activation, use:

register-python-argcomplete cz >> ~/.bashrc

For one-time activation of argcomplete for Commitizen only, use:

eval "$(register-python-argcomplete cz)"

For further information on activation, please visit the argcomplete website.

These are our cool sponsors!