Repository files navigation

Commitizen Documentation Site

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 toConventional 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 simplecz 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 theKeep 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.

• Interactive CLI for standardized commits with defaultConventional Commits support
• Intelligentversion bumping usingSemantic Versioning
• Automatickeep a changelog generation
• Built-in commit validation with pre-commit hooks
• Customizable commit rules and templates
• Multi-format version file support
• Custom rules and plugins via pip

Before installing Commitizen, ensure you have:

• Python3.9+
• Git1.8.5.2+

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

# Install Commitizenpipx install commitizen# Keep it updatedpipx upgrade commitizen

Using uv:

# Install commitizenuv tool install commitizen# Keep it updateduv tool upgrade commitizen

(For macOS users) 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.0poetry add commitizen --group dev# For Poetry < 1.2.0poetry add commitizen --dev

Using uv:

uv add commitizen

Using pdm:

pdm add -d commitizen

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 orcz.toml):

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

Create standardized commits using:

cz commit# or use the shortcutcz c

To sign off your commits:

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

For more commit options, runcz 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 (ifupdate_changelog_on_bump is enabled)
• Updates version files

You can customize:

• Version files
• Version scheme
• Version provider

For all available options, see thebump command documentation.

# Get your project's version (instead of Commitizen's version)cz version -p# Preview changelog changescz changelog --dry-run"$(cz version -p)"

This command is particularly useful for automation scripts and CI/CD pipelines.

For example, you can use the output of the commandcz changelog --dry-run "$(cz version -p)" to notify your team about a new release in Slack.

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/commitizenrev:master# Replace with latest taghooks:      -id:commitizen      -id:commitizen-branchstages:[pre-push]

2. Install the hooks:

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

Note: Replacemaster with thelatest tag to avoid warnings. You can automatically update this with:

pre-commit autoupdate

For more details about commit validation, see thecheck command documentation.

Commitizen provides a comprehensive CLI with various commands. Here's the complete reference:

• Conventional Commits Specification
• Exit Codes Reference
• Configuration Guide
• Command Documentation

For each command, you can get detailed help by adding--help:

cz commit --helpcz bump --helpcz changelog --help

For more details, visit ourdocumentation site.

Commitizen supports command-line completion throughargcomplete, which is automatically installed as a dependency. This feature provides intelligent auto-completion for all Commitizen commands and options.

• Bash: Full support
• Zsh: Limited support
• Fish: Limited support
• Tcsh: Limited support

If you installed Commitizen globally (e.g., usingpipx orbrew), you can enable global completion:

# Enable global completion for all Python applicationssudo activate-global-python-argcomplete

For a user-specific installation that persists across sessions:

# Add to your shell's startup file (e.g., ~/.bashrc, ~/.zshrc)register-python-argcomplete cz>>~/.bashrc

For one-time activation in your current shell session:

# Activate completion for current session onlyeval"$(register-python-argcomplete cz)"

After installation, you can verify the completion is working by:

1. Opening a new terminal session
2. Typingcz followed by a space and pressingTAB twice
3. You should see a list of available commands

For more detailed information about argcomplete configuration and troubleshooting, visit theargcomplete documentation.

These are our cool sponsors!