bump2version is a command-line tool designed to simplify software releases by updating version strings across multiple files.

Key features:

• Configurable formats: Versioning patterns are highly customizable.
• VCS Integration: Works with Git and Mercurial to read tags and write commits/tags, but can also function without any Version Control System.
• Language Agnostic: It operates on text files, making it compatible with any programming language.
• Runtime Support: Supports Python 3 and PyPy3. (For Python 2, use pip>=9 or pin bump2version<1).

If your goal is specifically to automate changelog generation, consider these tools:

• towncrier: Assembles a changelog file from multiple snippets found within individual merge commits.
• releases: Helps build a changelog specifically for Sphinx ReStructuredText.
• gitchangelog: Generates a configurable changelog by searching through git commit history.

A version string is composed of parts (e.g., 1.2.3 has major, minor, and patch). By default, these are numeric and incremented as integers.

You can define custom parts (like alpha, beta, or build) using the [bumpversion:part:<name>] section. This is useful for non-numeric versioning schemes.

[bumpversion:part:release_name]
values =
  witty-warthog
  ridiculous-rat
  marvelous-mantis

To avoid specifying options on the command line every time, you can create a .bumpversion.cfg file in your project root. This file should be committed to your Version Control System (VCS).

Precedence Rules:

1. Command line options (highest)
2. Configuration file
3. Environment variables
4. Defaults (lowest)

If .bumpversion.cfg is not found, bump2version will look for setup.cfg.

[bumpversion]
current_version = 0.2.9
commit = True
tag = True

[bumpversion:file:setup.py]

Install or upgrade to the latest version of bump2version using pip. Note that installing bumpversion will also install the latest bump2version.

Warning: bump2version is no longer maintained. It is recommended to switch to bump-my-version.

pip install --upgrade bump2version

You can use bump2version directly from the command line for simple, single-file operations without a configuration file.

Syntax: bump2version [options] part [file]

Arguments:

• part (required): The segment of the version to increment (e.g., major, minor, patch).
• file (optional): The specific file to modify. If omitted, no files are modified unless a configuration file is present.

Note: If you have a configuration file but only want to modify the file passed via the CLI, use the --no-configured-files flag.

# Bumping 0.5.1 to 0.6.0 in a specific file
bump2version --current-version 0.5.1 minor src/VERSION

# Bumping 1.1.9 to 2.0.0 in setup.py
bump2version --current-version 1.1.9 major setup.py

In Go projects, major versions (v2+) require the version number to be part of the module path in go.mod. You can automate this by using the parse and serialize options in your .bumpversion.cfg to extract and re-insert the version number into the module string.

Configuration Example

Add a section for go.mod in your .bumpversion.cfg:

[bumpversion]
current_version = 2.0.0
commit = True

[bumpversion:file:go.mod]
parse = (?P<major>\d+)
serialize = {major}
search = module github.com/myorg/myproject/v{current_version}
replace = module github.com/myorg/myproject/v{new_version}

Usage

If your go.mod contains module github.com/myorg/myproject/v2, running the following command will update it to v3:

bump2version --new-version 3.0.0 major

Global settings are defined in the [bumpversion] section of your configuration file. These settings apply to the entire bumping process.

[bumpversion]
current_version = 0.5.1
new_version = 0.6.1
tag = True
sign_tags = False
tag_name = v{new_version}
tag_message = Bump version: {current_version} → {new_version}
commit = True
message = Bump version: {current_version} → {new_version}
commit_args = -s

When running bumpversion, you can use templates for searching and replacing version strings. These templates support context variables like {current_version}, {new_version}, and individual parts like {major}, {minor}, and {patch}.

Commonly used flags for customization:

• --search: The template for the string to find in files.
• --replace: The template for the string to replace it with.
• --tag-name: The template for the VCS tag name.
• --message: The template for the commit message.

# Example using custom search/replace templates
bumpversion minor --search "Version: {current_version}" --replace "Version: {new_version}"