Configuration on bumpversion

Config file formats

Mon, 01 Jan 0001 00:00:00 +0000

Config file formats#

bumpversion looks for its configuration in the directory it runs in — the current directory, or the one given by --dir.

Discovery order#

Four filenames are tried, in this order:

#	File	Section
1	`.bumpversion.toml`	`[tool.bumpversion]`
2	`.bumpversion.cfg`	`[bumpversion]`
3	`pyproject.toml`	`[tool.bumpversion]`
4	`setup.cfg`	`[bumpversion]`

The first file that contains a usable section wins, and only that file is used — configuration is never merged across files. A pyproject.toml with no [tool.bumpversion] table (or with an empty one) is skipped as though it were not there, so the search continues to setup.cfg.

Files to rewrite

Mon, 01 Jan 0001 00:00:00 +0000

Files to rewrite#

Each [[tool.bumpversion.files]] entry describes one place the version appears. An entry must name exactly one target — either a filename or a glob:

[[tool.bumpversion.files]]
filename = "Cargo.toml"

[[tool.bumpversion.files]]
glob = "packages/*/package.json"

Naming both, or neither, is a configuration error.

The config file itself is always rewritten and always committed — you never list it.

What gets replaced#

Every entry has a search template and a replace template. They default to:

search = "{current_version}"
replace = "{new_version}"

So by default, every occurrence of the current version string in the file becomes the new one. In README.md that rewrites both the heading and the install line, which is usually what you want:

Version scheme

Mon, 01 Jan 0001 00:00:00 +0000

Version scheme#

Two keys define what a version is:

parse — a regex whose named capture groups become the version components.
serialize — one or more patterns that turn components back into a string.

The defaults describe SemVer:

parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)'
serialize = ["{major}.{minor}.{patch}"]

Because parse defines the components, changing it changes what you can bump. There is no fixed list of component names — bumpversion release works as soon as parse has a group called release.

Commits and tags

Mon, 01 Jan 0001 00:00:00 +0000

Commits and tags#

bumpversion can finish a bump by committing the rewritten files and tagging the commit. Both are off by default — a bare bumpversion patch only edits files.

[tool.bumpversion]
commit = true
tag = true

On the command line, --commit / --no-commit and --tag / --no-tag override the config for one run.

The dirty-tree check#

Before doing anything, bumpversion refuses to run if the working tree has uncommitted changes:

Error:
 0: Working directory is not clean:

This is deliberate: a release commit should contain the version bump and nothing else. Set allow_dirty = true, or pass --allow-dirty, when you genuinely want to bundle other staged work into the release commit.

Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Hooks#

Hooks run shell commands at three points in a bump. Each is a list of command strings:

Key	Runs
`setup_hooks`	Before anything is read or written
`pre_commit_hooks`	After the files are rewritten, before `git add` and the commit
`post_commit_hooks`	After the commit and the tag

Every hook runs through sh -c from the repository root, and a non-zero exit aborts the bump. Hooks do not run under --dry-run — the report shows what would have run:

Key reference

Mon, 01 Jan 0001 00:00:00 +0000

Key reference#

Every configuration key, with its type and default. Key names are written as they appear in a TOML file; the INI spelling is identical, only the section layout differs — see Config file formats.

Global keys#

These live in [tool.bumpversion] (TOML) or [bumpversion] (INI).

Version#

Key	Type	Default
`current_version`	string	— (required in practice)
`parse`	regex	`(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)`
`serialize`	string or list	`["{major}.{minor}.{patch}"]`

Search and replace#

Key	Type	Default
`search`	template	`{current_version}`
`replace`	template	`{new_version}`
`regex`	bool	`false`
`ignore_missing_files`	bool	`false`
`ignore_missing_version`	bool	`false`
`no_configured_files`	bool	`false`

Paths#

Key	Type	Default
`included_paths`	list of paths	—
`excluded_paths`	list of paths	—
`additional_files`	list of paths	—

included_paths is a union, not a filter: it can add a path that no [[files]] entry produced.