bumper

Automatically increment the project's version number.

Heavily inspired by bump2version and bumpversion. While bump-my-version is an excellent modern fork this functionality, I'd like a pared down version of the offered feature set for my personal projects.

Supported Versioning Schemes

• Semantic Versioning (SemVer)
  • Assumes <MAJOR>.<MINOR>.<PATCH>
• Calendar Versioning (CalVer)
  • Assumes <YYYY>.<MM>.<MICRO>

Installation

Install from PyPi with your favorite pip invocation, e.g.:

$ pip install sco1-bumper

You can confirm proper installation via the bumper CLI:

$ bumper --help
Usage: bumper [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  bump  Bump the requested version component.
  init  Generate a default bumper configuration file.

Configuration

bumper searches for its configuration options first in a .bumper.toml file, then in pyproject.toml; preference is given to whichever configuration is located first.

Required Fields

tool.bumper

• current_version - The current software version. This is automatically incremented when bumping.
• versioning_type - Versioning type to be used, accepted values are "semver" and "calver"

tool.bumper.files

• file - Path to target file relative to the repository root
• search - Replacement string to search for in the target file. Must contain a {current_version} tag if you want something to happen.

Example Configuration

The basic configuration looks something like the following:

SemVer

[tool.bumper]
current_version = "0.1.0"
versioning_type = "semver"

[[tool.bumper.files]]
file = "./pyproject.toml"
search = 'version = "{current_version}"'

CalVer

[tool.bumper]
current_version = "2025.1.0"
versioning_type = "calver"

[[tool.bumper.files]]
file = "./pyproject.toml"
search = 'version = "{current_version}"'

Multiple replacements within the same file can also be specified:

[tool.bumper]
current_version = "0.1.0"
versioning_type = "semver"

[[tool.bumper.files]]
file = "./pyproject.toml"
search = 'version = "{current_version}"'

[[tool.bumper.files]]
file = "./README.md"
search = "sco1-bumper/{current_version}"

[[tool.bumper.files]]
file = "./README.md"
search = "rev: v{current_version}"

CLI

bumper bump

Bump your project's version number using your defined configuration.

NOTE: The check_lock option will be skipped if pyproject.toml and/or uv.lock are not defined.

$ bumper bump --help
Usage: bumper bump [OPTIONS] BUMP_BY:{major|minor|patch|date}

  Bump the requested version component.

  Allowable `BUMP_BY` values differ based on the project's specified
  versioning type: SemVer - (major, minor, patch), CalVer - (date)

  When using CalVer, if the user's current UTC month is the same as the
  current project version, then the Micro component is incremented. Otherwise,
  the date components are bumped to the user's current UTC month and Micro
  reset to `0`.

  If `dry_run` is `True`, the requested diff will be displayed in the terminal
  & no file modifications will take place.

  If `check_lock` is `True`, a helper message is displayed if there is a
  mismatch between the bumped version and the version locked by `uv.lock`.

Arguments:
  BUMP_BY:{major|minor|patch|date}
                                  [required]

Options:
  --dry-run / --no-dry-run        Preview the requested diff.  [default: no-
                                  dry-run]
  --check-lock / --no-check-lock  Check that locked version matches the bumped
                                  ver.  [default: check-lock]
  --help                          Show this message and exit.

bumper init

A small helper to initialize a starter .bumper.toml file that bumps the version field of your project's pyproject.toml file.

NOTE: Be sure to update the sample version with your current version number before bumping with bumper.

$ bumper init --help
Usage: bumper init [OPTIONS]

  Generate a default bumper configuration file.

  If the `--ignore_existing` flag is set, any existing `.bumper.toml` file
  will be overwritten; this action is not reversible. Otherwise, the existing
  configuration will be preserved.

Options:
  --versioning-type [semver|calver]
                                  [default: semver]
  --ignore-existing / --no-ignore-existing
                                  [default: no-ignore-existing]
  --help                          Show this message and exit.