Skip to content

Configuration

You can configure semv using the pyproject.toml file via a section [tool.semv]. This page lists all possible configuration options along with their defaults.

invalid_commit_action (warning | error | skip)

Action to take if encountering an invalid commit—typically a commit for which the commit message doesn't have the correct form. Possible values are

  • warning: Prints a warning to stderr when encountering an invalid commit.
  • error: Exit with return code 2 if encountering an invalid commit.
  • skip: Silently skips invalid commits. This is a little dangerous as it may silently give an incorrect version. If you use this, it is recommended to use a commit template like this to ensure correct commit messages.

Example configuration setting the invalid commit action:

[tool.semv]
invalid_commit_action = "warning"

skip_commit_patterns (array of strings)

Setting the invalid_commit_action to error will result in errors for git-autogenerated commits. For example the default message for a merge commit is "Merge branch ..." and doesn't match the type(scope): ... pattern. In order to support these commits, it is possible to define a set of patterns that should be skipped during commit parsing. By default, these are the default git merge and git revert commits, these patterns may not be valid for pull requests merged through some service (they work for GitHub though).

[tool.semv]
skip_commit_patterns = ["^Merge.*", "^Revert.*"]

valid_scopes (array of strings)

If this is set, it is a list of valid scopes. Irrespective of this setting, omitting the scope is still possible. If valid_scopes is set, commits that use an invalid scope will result in the invalid_commit_action (see above).

Example configuration setting valid scopes:

[tool.semv]
valid_scopes = ["parser", "ui", "backend"]

types (table)

This configures which commit "types" semv will accept and how those will trigger a new version. By default, the "feat" type will trigger a minor release and "fix" and "perf" will trigger a patch release. Other valid types are "chore", "test", "docs", "ci", "refactor" and "style".

Example configuration setting the types:

[tool.semv.types]
feat = "minor"
fix = "patch"
perf = "patch"
other = "valid"

checks (table)

This configures additional validation checks that semv should run when determining the version. Checks are configured by providing the class name (e.g. RunPreviousVersionsTestsTox) followed by a table of arguments.

Example configuration setting a check:

[tool.semv.checks]
RunPreviousVersionsTestsTox = {testenv = "unit"}