Configuration

General configuration is grouped in the [tool.bumpversion] section of pyproject.toml.

Simple configuration

[tool.bumpversion]
current_version = "1.2.3"
allowed_branches = [
    "main",
]

[[tool.bumpversion.files]]
filename = "README.md"

commit

[optional]
default: True

Commit version replacement changes to the configured files.

Also available as --commit/--no-commit (e.g. bumpversion 1.2.3 --commit)

tag

[optional]
default: True

Tag the committed changes with the new version.

Also available as --tag/--no-tag (e.g. bumpversion 1.2.3 --tag)

allow_dirty

[optional]
default: False

Don't abort if the current branch contains uncommitted changes

Also available as --allow-dirty (e.g. bumpversion 1.2.3 --allow-dirty)

allow_missing

[optional]
default: False

Don't abort if the local and remote branches are out of sync.

Also available as --allow-missing (e.g. bumpversion 1.2.3 --allow-missing)

version_string

[optional]
default: v{new_version}

Format for the version tag, this will be passed into commit messages.

Example:

[tool.bumpversion]
version_string = "{new_version}"

commit_extra

[optional]
default: None

Additional file(s) to commit even if bumpversion has not modified them itself. Useful if another tool has modified a file in a previous pipeline step.

Example:

[tool.bumpversion]
commit_extra = [
    "CHANGELOG.md",
]

allowed_branches

[optional]
default: None

Prevent version being bumped if the current branch is not in the supplied list. By default all branches are allowed.

Example:

[tool.bumpversion]
allowed_branches = [
  "main",
  "develop",
]

hooks

[optional]
default: None

Run additional hooks when generating a release, this allows regenerating automated documentation during release process, for example.

Example:

[tool.bumpversion]
hooks = [
  "path.to.module:hook_function",
]

custom

[optional]
default: None

Arbitrary configuration that can be used in hooks.

Example:

[tool.bumpversion.custom]
key = "value"
a_list = ["key", "key2"]

Versioning

Versioning configuration is very similar to bump-my-version, but with a few simplifications.

The default configuration will support the typical semver use case of X.Y.Z version strings.

current_version

[optional]
default: None

The minimum required configuration to manage versions is the current version, which can be moved directly from [tool.bumpversion]

[tool.bumpversion]
current_version = "1.2.3"

files

[optional]
default: None

If multiple files have the current version string in them, they can be configured for replacement.

Where the version string can safely be replaced with the default pattern {version}, use:

[[tool.bumpversion.files]]
filename = "README.md"

For files that might contain other version strings that could match and shouldn't be updated, a search/replace pattern can be configured.

[[tool.bumpversion.files]]
filename = "pyproject.toml"
pattern = 'version = "{version}"'