Initialize commitizen

If it's your first time, you'll need to create a commitizen configuration file.

The assistant utility will help you set up everything

Alternatively, create a file .cz.toml in your project's directory.

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

Usage

Bump version

This command will bump your project's version, and it will create a tag.

Because of the setting update_changelog_on_bump, bump will also create the changelog. You can also update files. You can configure the version type and version provider.

There are many more options available, please read the docs for the bump command.

Committing

Run in your terminal

or the shortcut

Sign off the commit

Run in the terminal

or the shortcut

Get project version

Running cz version will return the version of commitizen, but if you want your project's version you can run:

This can be useful in many situations, where otherwise, you would require a way to parse the version of your project. Maybe it's simple if you use a VERSION file, but once you start working with many different projects, it becomes tricky.

A common example is, when you need to send to slack, the changes for the version that you just created:

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

Integration with Pre-commit

Commitizen can lint your commit message for you with cz check.

You can integrate this in your pre-commit config with:

---
repos:
  - repo: https://github.com/commitizen-tools/commitizen
    rev: master
    hooks:
      - id: commitizen
      - id: commitizen-branch
        stages: [push]

After the configuration is added, you'll need to run:

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

If you aren't using both hooks, you needn't install both stages.

Note that pre-commit discourages using master as a revision, and the above command will print a warning. You should replace the master revision with the latest tag. This can be done automatically with:

Read more about the check command here.