Skip to content

Bump Options

annotated_tag

When set to true, cz bump is equivalent to cz bump --annotated-tag.

pyproject.toml
[tool.commitizen]
annotated_tag = true

bump_message

Template used to specify the commit message generated when bumping.

Defaults to: bump: version $current_version → $new_version

Variable Description
$current_version the version existing before bumping
$new_version version generated after bumping
pyproject.toml
[tool.commitizen]
bump_message = "release $current_version → $new_version [skip-ci]"

gpg_sign

When set to true, cz bump is equivalent to cz bump --gpg-sign. See --gpg-sign.

pyproject.toml
[tool.commitizen]
gpg_sign = true

ignored_tag_formats

  • Type: list
  • Default: []

Tags matching those formats will be totally ignored and won't raise a warning. Each entry uses the syntax as tag_format with the addition of * that will match everything (non-greedy).

major_version_zero

When set to true, cz bump is equivalent to cz bump --major-version-zero. See --major-version-zero.

pyproject.toml
[tool.commitizen]
major_version_zero = true

legacy_tag_formats

  • Type: list
  • Default: []

Legacy git tag formats, useful for old projects that changed tag format. Tags matching those formats will be recognized as version tags and be included in the changelog. Each entry uses the syntax as tag_format.

pre_bump_hooks

A list of optional commands that will run right after updating version_files and before actual committing and tagging the release.

Useful when you need to generate documentation based on the new version. During execution of the script, some environment variables are available:

Variable Description
CZ_PRE_IS_INITIAL True when this is the initial release, False otherwise
CZ_PRE_CURRENT_VERSION Current version, before the bump
CZ_PRE_CURRENT_TAG_VERSION Current version tag, before the bump
CZ_PRE_NEW_VERSION New version, after the bump
CZ_PRE_NEW_TAG_VERSION New version tag, after the bump
CZ_PRE_MESSAGE Commit message of the bump
CZ_PRE_INCREMENT Whether this is a MAJOR, MINOR or PATCH release
CZ_PRE_CHANGELOG_FILE_NAME Path to the changelog file, if available
pyproject.toml
[tool.commitizen]
pre_bump_hooks = [
  "scripts/generate_documentation.sh"
]

post_bump_hooks

A list of optional commands that will run right after committing and tagging the release.

Useful when you need to send notifications about a release, or further automate deploying the release. During execution of the script, some environment variables are available:

Variable Description
CZ_POST_WAS_INITIAL True when this was the initial release, False otherwise
CZ_POST_PREVIOUS_VERSION Previous version, before the bump
CZ_POST_PREVIOUS_TAG_VERSION Previous version tag, before the bump
CZ_POST_CURRENT_VERSION Current version, after the bump
CZ_POST_CURRENT_TAG_VERSION Current version tag, after the bump
CZ_POST_MESSAGE Commit message of the bump
CZ_POST_INCREMENT Whether this was a MAJOR, MINOR or PATCH release
CZ_POST_CHANGELOG_FILE_NAME Path to the changelog file, if available
pyproject.toml
[tool.commitizen]
post_bump_hooks = [
  "scripts/slack_notification.sh"
]

prerelease_offset

Offset with which to start counting prereleases.

If not specified, defaults to 0.

pyproject.toml
[tool.commitizen]
prerelease_offset = 1

Note

Under some circumstances, a prerelease cannot start with 0-for example, in embedded projects where individual characters are encoded as bytes. You can specify an offset from which to start counting.

tag_format

See --tag-format.

update_changelog_on_bump

When set to true, cz bump is equivalent to cz bump --changelog.

pyproject.toml
[tool.commitizen]
update_changelog_on_bump = true

version_files

Identify the files or glob patterns which should be updated with the new version.

Commitizen will update its configuration file automatically when bumping, regardless of whether the file is present or not in version_files.

You may specify the version_files in your configuration file.

pyproject.toml
[tool.commitizen]
version_files = [
    "src/__version__.py",
]

It is also possible to provide a pattern for each file, separated by a colon (e.g. file:pattern). See the below example for more details.

pyproject.toml
[tool.commitizen]
version_files = [
    "packages/*/pyproject.toml:version",
    "setup.json:version",
]

Example scenario

We have a project with the following configuration file pyproject.toml:

pyproject.toml
[tool.commitizen]
version_files = [
    "src/__version__.py",
    "packages/*/pyproject.toml:version",
    "setup.json:version",
]

For the reference "setup.json:version", it means that it will look for a file setup.json and will only change the lines that contain the substring "version".

For example, if the content of setup.json is:

setup.json
{
    "name": "magictool",
    "version": "1.2.3",
    "dependencies": {
        "lodash": "1.2.3"
    }
}

After running cz bump 2.0.0, its content will be updated to:

setup.json
{
    "name": "magictool",
-   "version": "1.2.3",
+   "version": "2.0.0",
    "dependencies": {
        "lodash": "1.2.3"
    }
}

Note

Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.

Historical note

This option was renamed from files to version_files.

version_provider

Mechanism by which Commitizen reads and writes version information in your project.

For a detailed explanation, check the version provider section. Which includes, how to create your own version provider.

Available options

  • commitizen: default version provider and stores the version in the active commitizen config (pyproject.toml or .cz.toml) under the key version
  • scm: git tags provide the real version to commitizen (read only)
  • pep621: (python) manages version in pyproject.toml under the project.version field, following PEP 621 standards
  • poetry: takes the version from poetry v1, use pep621 with poetry v2 or later
  • uv: same as pep621 except that it also updates the uv.lock
  • cargo: manages version in both Cargo.toml (package.version) and Cargo.lock
  • npm: manages version in package.json and the lock
  • composer: for PHP's Composer package manager

Example

[tool.commitizen]
version_provider = "pep621"

version_scheme

Format used for the version.

For a detail explanation, check --version-scheme.

Available options

Example

[tool.commitizen]
version_scheme = "semver2"