Skip to content

Configuration

This section describes how to configure comver.

Important

You can configure comver via .comver.toml or under the [tool.comver] section in pyproject.toml.

Example of pyproject.toml configuration:

[tool.comver]
# Only commits to these paths are considered
path_includes = [
  "src/*",
  "pyproject.toml",
]

# Commits done by GitHub Actions bot are discarded
author_name_excludes = [
  "github-actions[bot]",
]

Equivalent .comver.toml configuration (no [tool.comver] section needed):

# Only commits to these paths are considered
path_includes = [
  "src/*",
  "pyproject.toml",
]

# Commits done by GitHub Actions bot are discarded
author_name_excludes = [
  "github-actions[bot]",
]

Options

Warning

All includes and excludes accept regex lists, evaluated using Python's re.match ⧉ (they are interpreted as raw strings, i.e., prefixed with r).

Warning

excludes always take precedence over includes

Warning

Conditions are composed via and (e.g. has to be a specific author and contain specific message)

You can configure the following options:

  • message_includes: List of regex patterns to include commits based on message. Default: all messages are included.
  • message_excludes: List of regex patterns to exclude commits based on message. Default: no messages are excluded.
  • path_includes: Regex list matching changed file paths to include commits. Default: every commit is included, no matter the changed file(s).
  • path_excludes: Regex list matching changed file paths to exclude commits. Default: no file is excluded based on path.
  • author_name_includes: Regex list to include commits based on author name. Default: commits from all authors are included.
  • author_name_excludes: Regex list to exclude commits based on author name. Default: no commits are excluded based on author.
  • author_email_includes: Regex list to include commits based on author email. Default: commits from all emails are included.
  • author_email_excludes: Regex list to exclude commits based on author email. Default: no commits are excluded based on email.
  • major_regexes: List of regex patterns that indicate a MAJOR version bump. Default: fix(...)!:/feat(...)!: or BREAKING CHANGE anywhere in the commit message.
  • minor_regexes: List of regex patterns that indicate a MINOR version bump. Default: commits starting with feat(...):
  • patch_regexes: List of regex patterns that indicate a PATCH version bump. Default: commits starting with fix(...):
  • unrecognized_message: Action to take if the message doesn’t match any major, minor, or patch patterns. Options: "ignore" (default) or "error".

Suggested

This subsection includes example configurations for common use cases.

Important

The list is growing. Feel free to open a pull request ⧉ with yours configuration ideas!

Note

These examples are modular; feel free to mix and match based on your project’s needs.

Python package

For Python packages with a /src/ layout, the following is recommended:

[tool.comver]
path_includes = [
  "src/*",
  "pyproject.toml",
]

Note

Any change to pyproject.toml currently affects versioning. More granular handling is being considered on the ROADMAP.

Exclude bot commits

To ignore commits made by bots (e.g. GitHub Actions or renovatebot ⧉):

[tool.comver]
author_excludes = [
  ".*\[bot\].*",
]

Note

This pattern excludes any author containing [bot], which might unintentionally filter out human contributors.

Github-style commit skips

GitHub allows skipping skipping CI workflows ⧉ with commit annotations like [skip ci].

Similarly, comver supports skipping version bumps via:

[tool.comver]
message_excludes = [
  ".*\[no version\].*",
  ".*\[skip version\].*",
  ".*\[version skip\].*",
]