bumpversion

Warnings

• breaking Version 0.5.0 introduced significant breaking changes. The `--bump` argument was removed, making the version part (e.g., `major`, `minor`, `patch`) a required positional argument. For example, `bumpversion --bump minor` became `bumpversion minor`.
  Fix: Update your CLI commands to use the version part as a positional argument: `bumpversion <part>` (e.g., `bumpversion patch`).
• breaking Version 0.5.0 deprecated the `files = ` configuration option in `.bumpversion.cfg`. It was replaced by a new, more granular file-specific configuration using `[bumpversion:file:...]` sections.
  Fix: Migrate your configuration from `files = file1 file2` to individual sections like `[bumpversion:file:file1]` and `[bumpversion:file:file2]`.
• gotcha By default, `bumpversion` will abort if your Git working directory is 'dirty' (contains uncommitted changes) to prevent accidental releases or loss of unsaved work. This can be a common point of friction during development.
  Fix: Always commit your changes before running `bumpversion`. If you intentionally want to bypass this check, use the `--allow-dirty` command-line option, but exercise caution.
• gotcha Without explicit `search` and `replace` patterns in your configuration, `bumpversion` uses regex-based matching that might inadvertently update unintended strings that happen to match the version pattern (e.g., a version dependency in `pyproject.toml`).
  Fix: For critical files, always use specific `search = "version = {current_version}"` and `replace = "version = {new_version}"` patterns in your `[bumpversion:file:...]` sections to precisely target the version string.
• gotcha The `current_version` must either be explicitly defined in your `.bumpversion.cfg` or easily detectable from a file. If `bumpversion` cannot determine the current version, it will fail and may require the `--current-version` CLI argument.
  Fix: Ensure your `.bumpversion.cfg` (or `setup.cfg`/`pyproject.toml`) has `current_version = X.Y.Z` defined, or that your version files are consistently formatted for automatic detection.
• deprecated The original `bumpversion` project is no longer actively maintained and explicitly recommends using actively maintained forks like `bump2version` or `bump-my-version` for new projects and ongoing development, as these forks offer continued support, new features (like `pyproject.toml` support), and bug fixes.
  Fix: Consider installing and migrating to `bump2version` (`pip install bump2version`) or `bump-my-version` (`pip install bump-my-version`) for better long-term support.

Install

• pip install bumpversion Install latest version

Quickstart

This quickstart demonstrates how to set up `bumpversion` for a simple project, initialize a version file and a configuration file, and then perform a version bump. It includes Git commands as `bumpversion` integrates closely with Git for committing and tagging. The `current_version` in `.bumpversion.cfg` must match the version string found in your files.

# 1. Create a project directory and navigate into it
mkdir my_project && cd my_project

# 2. Initialize a Git repository (optional, but recommended for bumpversion)
git init

# 3. Create an initial version file (e.g., 'VERSION' or 'my_package/__init__.py')
echo "0.1.0" > VERSION

# 4. Create a .bumpversion.cfg file
cat <<EOF > .bumpversion.cfg
[bumpversion]
current_version = 0.1.0
commit = True
tag = True

[bumpversion:file:VERSION]
EOF

# 5. Make an initial commit
git add .bumpversion.cfg VERSION
git commit -m "Initial project setup"

# 6. Bump the patch version
bumpversion patch

# Verify the change
cat VERSION
git log --oneline -2