Managing tag formats¶

Tag format and version scheme¶

For most projects, the tag format is simply the version number which is set like this:

[tool.commitizen]tag_format:$versionversion_scheme:pep440

As this is the default value, you don't have to specify it.

This setting means that:

• The tag generated on bump will have this format:1.0.0 :
  • the version is generated following PEP440 scheme
  • the tag is exactly the generated version
• All tags having this format will be recognized as version tag when:
  • searching the last while bumping a release
  • searching previous versions while:
    • generating incremental changelog
    • generating a changelog for a version range
• The changelog versions (section titles) will have this format
• Thescm version provider will identify the current version using this tag format

The version format will change depending on your configured version scheme.For most, it will only impact pre-releases anddevelopmental releases formats (i.e.1.0.0-rc.1 vs.1.0.0.rc1)

But you may need a different tagging convention, let's say usingsemver and prefixed with av.In this case you will define your settings like this:

[tool.commitizen]tag_format:v${version}version_scheme:semver

As a result, the tag generated on bump will have this format:v1.0.0 and the version will be generated followingsemver scheme.

Seetag_format andversion_scheme settings for more details.

Changing convention¶

Now, let's say you need to change the tag format for some reason (company convention,migration to a monorepo...).You will obviously want to keep all those features working as expected.

Commitizen can deal with it as long as you provide the legacy tag format in the configuration.

Using the previous example, let's say you want to move fromv${version} tocomponent-${version}.Thencomponent-${version} will be the new tag format andv${version} the legacy one.

[tool.commitizen]tag_format:component-${version}legacy_tag_formats:-v${version}

This way, you won't lose your version history, you'll still be able to generate your changelog properly,and on the next version bump, your last version in the formv${version} will be properly recognized if you use thescm version provider.Your new tag will be in the formcomponent-${version}.

Known tags to ignore¶

Now let's say you have some known tags you want to ignore, either because they are not versions, or because they are not versions of the component you are dealing with.As a consequence, you don't want them to trigger a warning because Commitizen detected an unknown tag format.

Then you can tell Commitizen about it using theignored_tag_formats setting:

[tool.commitizen]ignored_tag_formats:-prod-other-component-${version}-prefix-*

This will ignore:

• Theprod tag
• Any version tag prefixed withother-component-
• Any tag prefixed withprefix-

[tool.commitizen]ignored_tag_formats = ["*"]