Skip to content

faq.md

Latest commit

 

History

History
135 lines (93 loc) · 3.92 KB

faq.md

File metadata and controls

135 lines (93 loc) · 3.92 KB

FAQ

This page contains frequently asked how to questions.

Support for PEP621

PEP621 establishes a [project] definition inside pyproject.toml

[project]
name = "spam"
version = "2.5.1"

Commitizen provides a PEP621 version provider to get and set version from this field.

You just need to set the proper version_provider setting:

[project]
name = "spam"
version = "2.5.1"

[tool.commitizen]
version_provider = "pep621"

How to revert a bump?

If for any reason, the created tag and changelog were to be undone, this is the snippet:

git tag --delete <created_tag>
git reset HEAD~
git reset --hard HEAD

This will remove the last tag created, plus the commit containing the update to .cz.toml and the changelog generated for the version.

In case the commit was pushed to the server, you can remove it by running:

git push --delete origin <created_tag>

How to handle revert commits?

git revert --no-commit <SHA>
git commit -m "revert: foo bar"

I got Exception [WinError 995] The I/O operation ... error

This error was caused by a Python bug on Windows. It's been fixed by cpython #22017, and according to Python's changelog, 3.8.6rc1 and 3.9.0rc2 should be the accurate versions first contain this fix. In conclusion, upgrade your Python version might solve this issue.

More discussion can be found in issue #318.

How to change the tag format ?

You can use the legacy_tag_formats to list old tag formats. New bumped tags will be in the new format but old ones will still work for:

  • changelog generation (full, incremental and version range)
  • bump new version computation (automatically guessed or increment given)

So given if you change from myproject-$version to ${version} and then v${version}, your Commitizen configuration will look like this:

tag_format = "v${version}"
legacy_tag_formats = [
    "${version}",
    "myproject-$version",
]

A dependency has the same version as my project — how do I prevent it from being bumped?

When using version_files to track your project version, Commitizen searches for the current version string and replaces it with the new one. If a dependency in the same file happens to share the exact same version number, it will also be updated, which is usually undesirable.

There are two ways to avoid this:

Option 1 — Anchor the pattern with ^

Prefix the file entry with ^ to match only lines that start with version:

[tool.commitizen]
version_files = ["pyproject.toml:^version"]

This ensures only lines like version = "1.2.3" are matched, not dependency specifications that happen to contain the same version string.

Option 2 (recommended) — Use a version_provider

Instead of version_files, use the appropriate version_provider for your project type. Commitizen will then update exactly the right field without any regex-based text replacement.

For example, if you use pyproject.toml with a [project] table (PEP 621):

[tool.commitizen]
version_provider = "pep621"

Or for Poetry users:

[tool.commitizen]
version_provider = "poetry"

See the version providers reference for all available options.

How to avoid warnings for expected non-version tags?

You can explicitly ignore them with ignored_tag_formats.

tag_format = "v${version}"
ignored_tag_formats = [
    "stable",
    "component-*",
    "env/*",
    "v${major}.${minor}",
]