About¶

cz bump is a powerful command thatautomatically determines and increases your project's version number based on your commit history.

It analyzes your commits to determine the appropriate version increment according to semantic versioning principles.

Key Features¶

• Automatic Version Detection: Analyzes commit history to determine the appropriate version bump
• Manual Version Control: Supports manual version specification when needed
• Pre-release Support: Handles alpha, beta, and release candidate versions
• Multiple Version Schemes: Supports bothPEP 440 andsemantic versioning formats

Version Increment Rules¶

The version follows theMAJOR.MINOR.PATCH format, with increments determined by your commit types:

--version-scheme¶

By default, Commitizen usesPEP 440 for version formatting. You can switch to semantic versioning using either:

1. Command line:

   czbump--version-schemesemver

2. Configuration file:

   pyproject.toml

   [tool.commitizen]version_scheme="semver"

Available options are:

• pep440:PEP 440 (default and recommended for Python projects)
• semver:Semantic Versioning (recommended for non-Python projects)

You can also set this in the configuration file withversion_scheme = "semver".

PEP440 Version Examples¶

Commitizen supports thePEP 440 version format, which includes several version types. Here are examples of each:

Standard Releases¶

0.9.0    # Initial development release0.9.1    # Patch release0.9.2    # Another patch release0.9.10   # Tenth patch release0.9.11   # Eleventh patch release1.0.0    # First stable release1.0.1    # Patch release after stable1.1.0    # Minor feature release2.0.0    # Major version release

Pre-releases¶

1.0.0a0  # Alpha release 01.0.0a1  # Alpha release 11.0.0b0  # Beta release 01.0.0rc0 # Release candidate 01.0.0rc1 # Release candidate 1

Development Releases¶

1.0.0.dev0  # Development release 01.0.0.dev1  # Development release 1

Combined Pre-release and Development¶

1.0.0a1.dev0  # Development release 0 of alpha 11.0.0b2.dev1  # Development release 1 of beta 2

Note:post releases (e.g.,1.0.0.post1) are not currently supported.

Command line options¶

--files-only¶

Bumps the version in the files defined inversion_files without creating a commit and tag on the git repository.

czbump--files-only

--changelog¶

Generate achangelog along with the new version and tag when bumping. Seechangelog for more details.

czbump--changelog

--prerelease¶

The bump is a pre-release bump, meaning that in addition to a possible version bump the new version receives apre-release segment compatible with the bump's version scheme, where the segment consists of aphase and anon-negative number. Supported options for--prerelease are the following phase namesalpha,beta, orrc (release candidate). For more details, refer to thePython Packaging User Guide.

Note that as persemantic versioning spec

Pre-release versions have a lower precedence than the associated normal version. A pre-release versionindicates that the version is unstable and might not satisfy the intended compatibility requirementsas denoted by its associated normal version.

For example, the following versions (using thePEP 440 scheme) are orderedby their precedence and showcase how a release might flow through a development cycle:

• 1.0.0 is the currently published version
• 1.0.1a0 after committing afix: for pre-release
• 1.1.0a1 after committing an additionalfeat: for pre-release
• 1.1.0b0 after bumping a beta release
• 1.1.0rc0 after bumping the release candidate
• 1.1.0 next feature release

--increment-mode¶

--increment-mode=linear (default)¶

Ensures that bumping pre-releasesmaintains linearity.

Bumping a pre-release with lower precedence than the current pre-release phase maintains the current phase of higher precedence.For example, if the current version is1.0.0b1 then bumping with--prerelease alpha will continue to bump thebeta phase.

--increment-mode=exact¶

Applies the exact changes that have been specified with--increment or determined from the commit log.For example,--prerelease beta will always result in ab tag, and--increment PATCH will always increase the patch component.

Examples¶

The following table illustrates the difference in behavior between the two modes:

--check-consistency¶

Check whether the versions defined inversion_files and the version in Commitizen configuration are consistent before bumping version.

czbump--check-consistency

For example, if we have the following configuration filepyproject.toml:

[tool.commitizen]version="1.21.0"version_files=["src/__version__.py","setup.py",]

and the following version filessrc/__version__.py andsetup.py:

__version__="1.21.0"

fromsetuptoolsimportsetupsetup(...,version="1.0.5",...)

When you runcz bump --check-consistency, Commitizen will verify that the current version inpyproject.toml (1.21.0) exists in all files listed inversion_files.In this example, it will detect thatsetup.py contains1.0.5 instead of1.21.0, causing the bump to fail.

--local-version¶

Bump the local portion of the version.

For example, if we have the following configuration filepyproject.toml:

[tool.commitizen]version="5.3.5+0.1.0"

When you runcz bump --local-version, it will bump only the local version0.1.0 and keep the public version5.3.5 intact, bumping to the version5.3.5+0.2.0.

--annotated-tag¶

Create annotated tags.

It is also available via configuration files.

For example, inpyproject.toml:

[tool.commitizen]annotated_tag=true

--annotated-tag-message¶

Create annotated tags with the given message.

It is also available via configuration files.

For example, inpyproject.toml:

[tool.commitizen]annotated_tag_message="Annotated tag message"

--changelog-to-stdout¶

Send the incremental changelog generated bycz bump tostdout.Any other messages generated bycz bump will be sent tostderr.

When this flag is used,--changelog is implied.However, it is recommended to set--changelog (or the settingupdate_changelog_on_bump) explicitly when the option--changelog-to-stdout is used.

czbump--changelog--changelog-to-stdout>body.md

--git-output-to-stderr¶

Redirects git commands output tostderr.

Useful when used with--changelog-to-stdout and piping the output to a file.

For example,git commit output may pollutestdout, so it is recommended to use this flag when piping the output to a file.

--retry¶

If you use tools likepre-commit, you can add this flag.It will retry the commit if it fails the first time.

Useful to combine with code formatters, likePrettier.

--major-version-zero¶

Breaking changes do not bump the major version number.

Say you have a project with the version0.1.x and you commit a breaking change like this:

fix(magic)!: fully deprecate whatever

and you run

czbump--major-version-zero

Then the version of your project will be bumped to0.2.0 instead of1.0.0.

# This failsczbump0.1.0--major-version-zero

--gpg-sign¶

Creates gpg signed tags.

czbump--gpg-sign

--template¶

Provides your own changelog jinja template.Seethe template customization section

--extra¶

Provides your own changelog extra variables by using theextras settings or the--extra/-e parameter.

czbump--changelog--extrakey=value-eshort="quoted value"

Seethe template customization section.

--build-metadata¶

Specifies additional metadata in the version string.

# creates a version like `1.1.2+yourmetadata`.czbump--build-metadatayourmetadata

--get-next¶

Similar to--dry-run but only outputs the next version.

# outputs 1.0.1 if the current version is 1.0.0 and the increment is PATCHczbump--get-next

Useful for determining the next version based on CI for non-production environments/builds.

bump: version 3.28.0 → 3.29.0tag to create: v3.29.0increment detected: MINOR

3.29.0

--allow-no-commit¶

Allow the project version to be bumped even when there's no eligible version.

Example usage:

# Force to bump a minor versionczbump--incrementMINOR--allow-no-commit# bump version to 2.0.0 even when there's no breaking changes or even no commitsczbump--allow-no-commit2.0.0

# will bump to `1.0.1` if the current version is `1.0.0`.czbump--allow-no-commit# bump version to 2.0.0 even when there's no breaking changes or even no commitsczbump--allow-no-commit2.0.0

--tag-format¶

tag_format and [version_scheme][version_scheme] are combined to make Git tag names from versions.

These are used in:

• cz bump: Find previous release tag (exact match) and generate new tag.
• Find previous release tags incz changelog.
• If--incremental: Using the latest version found in the changelog, scan existing Git tags with 89\% similarity match.
• --rev-range is converted to Git tag names withtag_format before searching Git history.
• If thescmversion_provider is used, it uses different regexes to find the previous version tags:
• Iftag_format is set to$version (default):VersionProtocol.parser (allowsv prefix)
• Iftag_format is set: Custom regex similar to SemVer (not as lenient as PEP440 e.g. on dev-releases)

Commitizen supports two types of formats, a simple and a more complex.

czbump--tag-format="v$version"

czbump--tag-format="v$minor.$major.$patch$prerelease.$devrelease"

In your configuration file:

[tool.commitizen]tag_format="v$major.$minor.$patch$prerelease"

The variables must be preceded by a$ sign and optionally can be wrapped in{}. The default is$version.

Supported variables: