bumpversion

Bumping

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

Bumping#

Selecting a component#

There are three equivalent ways to bump, and one way to bypass component selection entirely:

bumpversion patch # shorthand for the standard components
bumpversion bump patch # explicit; works for any component
bumpversion bump pre_label # a component you defined in `parse`
bumpversion --new-version 2.0.0-rc.1 # set the version directly

major, minor, and patch exist as their own commands because they are what most projects use. Any other component — anything with a named capture group in your parse pattern — goes through bump <component>.

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.

Introduction

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

Introduction#

bumpversion answers one question: this project is at version X — make it version Y, everywhere.

“Everywhere” is the hard part. A version number is duplicated across a package manifest, an install line in the README, a constant in the source, a heading in the docs, and the config file that records the current version. Bumping by hand means finding all of them, and a release where one was missed is a release with a wrong number in it.

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:

Inspecting

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

Inspecting#

Two commands report without changing anything. Both skip the dirty-tree check, so they work in a repository with uncommitted work.

`show-bump`#

Computes the next version for a component and prints it:

bumpversion show-bump patch

$ bumpversion show-bump patch
 
old_version=1.4.2
new_version=1.4.3
 
$ bumpversion show-bump minor
 
old_version=1.4.2
new_version=1.5.0
 
$ bumpversion show-bump major
 
old_version=1.4.2
new_version=2.0.0

The output is two name=value lines, which is easy to consume from a shell:

Installation

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

Installation#

bumpversion is a single static binary with no runtime dependencies.

Homebrew#

brew install --cask romnn/tap/bumpversion

From crates.io#

Building from source installs both binaries in the package:

cargo install --locked bumpversion-cli

Prebuilt binaries#

Release archives for Linux, macOS, and Windows are attached to every GitHub release. Download the archive for your platform, extract it, and put bumpversion on your PATH.

In CI#

With mise, pin it alongside the rest of your toolchain:

[tools]
"github:romnn/bumpversion" = { version = "latest", matching = "bumpversion" }

The matching filter is needed because each release ships both the bumpversion and cargo-bumpversion archives.

CLI reference

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

CLI reference#

$ bumpversion --help
 
bump git version
 
Usage: bumpversion [OPTIONS] [ARGS]... [COMMAND]
 
Commands:
 major
 minor
 patch
 show
 show-bump
 bump
 help Print this message or the help of the given subcommand(s)
 
Arguments:
 [ARGS]...
 
Options:
 --dir <DIR>
 repository directory to run bumpversion in [env: BUMPVERSION_DIR=]
 --config-file <CONFIG_FILE>
 config file to read most of the variables from [env: BUMPVERSION_CONFIG_FILE=]
 --color <COLOR_CHOICE>
 enable or disable color [env: BUMPVERSION_COLOR=]
 -v, --verbose...
 Increase logging verbosity
 -q, --quiet...
 Decrease logging verbosity
 --log <LOG_LEVEL>
 Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten. [env: BUMPVERSION_LOG_LEVEL=]
 --allow-dirty
 don't abort if working directory is dirty [env: BUMPVERSION_ALLOW_DIRTY=]
 --no-allow-dirty
 explicitly abort if dirty [env: BUMPVERSION_NO_ALLOW_DIRTY=]
 --current-version <CURRENT_VERSION>
 version that needs to be updated [env: BUMPVERSION_CURRENT_VERSION=]
 --new-version <NEW_VERSION>
 new version that should be in the files [env: BUMPVERSION_NEW_VERSION=]
 --parse <PARSE_VERSION_PATTERN>
 regex parsing the version string [env: BUMPVERSION_PARSE=]
 --serialize <SERIALIZE_VERSION_PATTERNS>
 how to format what is parsed back to a version [env: BUMPVERSION_SERIALIZE=]
 --search <SEARCH>
 template for complete string to search [env: BUMPVERSION_SEARCH=]
 --replace <REPLACE>
 template for complete string to replace [env: BUMPVERSION_REPLACE=]
 --regex
 treat the search parameter as a regular expression [env: BUMPVERSION_REGEX=]
 --no-regex
 explicitly do not treat the search parameter as a regular expression [env: BUMPVERSION_NO_REGEX=]
 --no-configured-files
 only replace the version in files specified on the command line, ignoring the files from the configuration file [env: BUMPVERSION_NO_CONFIGURED_FILES=]
 --ignore-missing-files
 ignore any missing files when searching and replacing in files [env: BUMPVERSION_IGNORE_MISSING_FILES=]
 --no-ignore-missing-files
 do not allow missing files when searching and replacing in files [env: BUMPVERSION_NO_IGNORE_MISSING_FILES=]
 --ignore-missing-version
 ignore any missing versions when searching and replacing in files [env: BUMPVERSION_IGNORE_MISSING_VERSION=]
 --no-ignore-missing-version
 do not allow missing versions when searching and replacing in files [env: BUMPVERSION_NO_IGNORE_MISSING_VERSION=]
 -n, --dry-run
 don't write any files, just pretend. [env: BUMPVERSION_DRY_RUN=]
 --commit
 commit to version control [env: BUMPVERSION_COMMIT=]
 --no-commit
 do not commit to version control [env: BUMPVERSION_NO_COMMIT=]
 --tag
 create a tag in version control [env: BUMPVERSION_TAG=]
 --no-tag
 do not create a tag in version control [env: BUMPVERSION_NO_TAG=]
 --sign-tags
 sign tags if created [env: BUMPVERSION_SIGN_TAGS=]
 --no-sign-tags
 do not sign tags if created [env: BUMPVERSION_NO_SIGN_TAGS=]
 --tag-name <TAG_NAME>
 tag name (only works with --tag) [env: BUMPVERSION_TAG_NAME=]
 --tag-message <TAG_MESSAGE>
 tag message [env: BUMPVERSION_TAG_MESSAGE=]
 -m, --message <COMMIT_MESSAGE>
 commit message [env: BUMPVERSION_MESSAGE=]
 --commit-args <COMMIT_ARGS>
 extra arguments to commit command [env: BUMPVERSION_COMMIT_ARGS=]
 -h, --help
 Print help
 -V, --version
 Print version

Every flag below is global: accepted at the top level and on every subcommand alike. Each also has an environment variable, named BUMPVERSION_ plus the flag in upper snake case.

Quick start

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

Quick start#

This walks through a first config file and a first bump. It assumes bumpversion is installed and that you are in a Git repository.

1. Write a config file#

Create .bumpversion.toml at the repository root. It needs the current version and the list of files that mention it:

.bumpversion.toml

[tool.bumpversion]
current_version = "1.4.2"
commit = true
tag = true

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

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

That is the whole configuration for a project whose version appears in Cargo.toml and in the README:

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:

Continuous integration

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

Continuous integration#

Running the bump in CI makes the release commit and tag reproducible, and keeps release rights in the repository rather than on someone’s laptop.

Manual release workflow#

A workflow_dispatch job that takes the component to bump, does the bump, and pushes the commit and tag:

name: release
on:
 workflow_dispatch:
 inputs:
 component:
 description: "version component to bump"
 type: choice
 options: [patch, minor, major]
 default: patch

permissions:
 contents: write

jobs:
 release:
 runs-on: ubuntu-24.04
 steps:
 - uses: actions/checkout@v7
 with:
 # bumpversion reads tag state, and the release commit is pushed back.
 fetch-depth: 0
 - uses: jdx/mise-action@v4
 - name: Configure git author
 run: |
 git config user.name "github-actions[bot]"
 git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 - name: Preview
 run: bumpversion --dry-run --verbose ${{ inputs.component }}
 - name: Bump
 run: bumpversion ${{ inputs.component }}
 - name: Push
 run: git push --follow-tags

Two details matter:

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.

bumpversion

Bumping

Bumping#

Selecting a component#

Config file formats

Config file formats#

Discovery order#

Introduction

Introduction#

Files to rewrite

Files to rewrite#

What gets replaced#

Inspecting

Inspecting#

show-bump#

Installation

Installation#

Homebrew#

From crates.io#

Prebuilt binaries#

In CI#

CLI reference

CLI reference#

Quick start

Quick start#

1. Write a config file#

Version scheme

Version scheme#

Commits and tags

Commits and tags#

The dirty-tree check#

Hooks

Hooks#

Continuous integration

Continuous integration#

Manual release workflow#

Key reference

Key reference#

Global keys#

Version#

Search and replace#

Paths#

`show-bump`#