Documentation on bumpversion

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.

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.

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:

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: