Registry / devops / bumpver

bumpver

JSON →
library2025.1131pypypiunverified

Bumpver is a Python library and command-line tool designed for automatic versioning of project files. It supports various versioning schemes, including Semantic Versioning (SemVer) and Calendar Versioning (CalVer), and works with plain text files, making it suitable for any project. It integrates optionally with Git or Mercurial to manage version tags and commits. The current version is 2025.1131. The project has an active release cadence, with updates often several times a year, addressing bug fixes and adding new features.

pip install bumpver
INSTALL
IMPORT
SIG · BUMPVER
B
bumpver
devopspythonv2025.1131
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

The primary way to use `bumpver` is via its Command Line Interface (CLI). This quickstart demonstrates how to initialize `bumpver` configuration in `pyproject.toml` and then update the project's version across specified files using the `bumpver update` command. The `--dry` flag is useful for previewing changes before applying them.

import os import subprocess def setup_project(): # Simulate project structure os.makedirs('my_project', exist_ok=True) os.chdir('my_project') with open('pyproject.toml', 'w') as f: f.write(""" [tool.bumpver] current_version = "2024.1.0" version_pattern = "YYYY.MINOR.PATCH" [tool.bumpver.file_patterns] "src/__init__.py" = [ '^__version__ = "{version}"$', ] "README.md" = [ 'Current Version: {version}', ] """ ) os.makedirs('src', exist_ok=True) with open('src/__init__.py', 'w') as f: f.write('__version__ = "2024.1.0"\n') with open('README.md', 'w') as f: f.write('My Project\n\nCurrent Version: 2024.1.0\n') # Initialize bumpver config if it doesn't exist (optional, but good practice) try: subprocess.run(["bumpver", "init"], check=True, capture_output=True) print("bumpver init successful.") except subprocess.CalledProcessError as e: print(f"bumpver init failed: {e.stderr.decode()}") def run_bumpver_update(): print("\n--- Running bumpver update --patch --dry ---") try: result = subprocess.run(["bumpver", "update", "--patch", "--dry"], check=True, capture_output=True) print(result.stdout.decode()) except subprocess.CalledProcessError as e: print(f"bumpver update failed: {e.stderr.decode()}") print("\n--- Verifying file contents (dry run means no actual changes) ---") with open('src/__init__.py', 'r') as f: print(f"src/__init__.py: {f.read().strip()}") with open('README.md', 'r') as f: print(f"README.md: {f.read().strip()}") print("\n--- Running actual bumpver update --patch ---") try: result = subprocess.run(["bumpver", "update", "--patch"], check=True, capture_output=True) print(result.stdout.decode()) except subprocess.CalledProcessError as e: print(f"bumpver update failed: {e.stderr.decode()}") print("\n--- Verifying actual file contents ---") with open('src/__init__.py', 'r') as f: print(f"src/__init__.py: {f.read().strip()}") with open('README.md', 'r') as f: print(f"README.md: {f.read().strip()}") if __name__ == '__main__': original_dir = os.getcwd() try: setup_project() run_bumpver_update() finally: os.chdir(original_dir) # Clean up created directory if necessary (omitted for simplicity in quickstart)
bumpver --version
Debug
Known issues
breakingThe project underwent a name change from `PyCalVer` to `BumpVer` in release 2020.1100-beta. This change also introduced a new pattern syntax, although the old syntax is still supported. Users migrating from `PyCalVer` or referencing older documentation should be aware of this.
fix
Update `pip` installations from `pycalver` to `bumpver` and review `version_pattern` configurations, preferably updating to the new syntax described in current documentation.
affects: <2020.1100-beta
gotchaWhen using Calendar Versioning (CalVer) patterns with `bumpver`, auto-incrementing parts like `PATCH` will reset (roll over to zero) if a higher-order date part (e.g., year or month) changes. For example, if you increment `--patch` on `2024.1.5` at the end of January, the next increment in February might become `2024.2.0`, resetting the patch.
fix
Understand the rollover behavior of date-based parts. If you need to avoid rollover for specific auto-incrementing parts within a calendar unit, consider using the `--pin-increments` flag or structuring your `version_pattern` and `file_patterns` carefully.
affects: All
gotchaFor Semantic Versioning (SemVer) patterns, `bumpver` requires explicit flags (`--major`, `--minor`, or `--patch`) to specify which part of the version to increment. Unlike CalVer, simply running `bumpver update` without such flags will result in an error if the date has not changed or if no auto-incrementing parts are defined.
fix
Always include `--major`, `--minor`, or `--patch` flags when performing an `update` operation on a SemVer pattern, unless using other auto-incrementing parts like `BUILD`, `INC0`, or `INC1`.
affects: All
gotchaIncorrectly configuring `file_patterns` in `pyproject.toml` (e.g., wrong regular expression, escaping issues, or inconsistent quoting) can lead to `bumpver` failing to find and update version strings in files. This results in 'Pattern not found' errors.
fix
Utilize `bumpver grep "<PATTERN>" <FILE>` to test and debug your `version_pattern` and `file_patterns` regular expressions before attempting an `update`. Ensure patterns accurately match the version strings in your files.
affects: All
gotchaUsing the `--allow-dirty` flag with `bumpver update` bypasses the check for uncommitted changes. However, `bumpver` will still abort the commit if there are uncommitted changes *to the files containing version strings*. This can lead to unexpected failures even when `--allow-dirty` is used.
fix
Ensure all files with version strings managed by `bumpver` are committed before running `bumpver update`, even if `allow-dirty` is specified for other parts of the repository. Use `git status` to verify.
affects: All
Errors
Common errors & fixes
ERROR - Pattern not found: '{your_pattern}'
The configured 'version_pattern' in your 'bumpver.toml' or 'pyproject.toml' does not precisely match the version string found in the files specified under 'file_patterns'.
fix
Use `bumpver grep '{your_pattern}' {your_file} --verbose` to debug the regular expression 'bumpver' is using. Adjust your 'version_pattern' or 'file_patterns' in the configuration to ensure they correctly capture the version string in your project files.
ERROR - Invalid version '{version}' and/or pattern '{pattern}'
This error occurs when the 'current_version' defined in your configuration does not conform to the 'version_pattern', or when attempting to increment a version without specifying the appropriate part (e.g., not using '--major', '--minor', or '--patch' for SemVer, or attempting to bump a CalVer without a date change or other incrementing parts).
fix
Verify that your 'current_version' in 'bumpver.toml' or 'pyproject.toml' exactly matches the structure defined by your 'version_pattern'. For Semantic Versioning, ensure you always include `--major`, `--minor`, or `--patch` when running `bumpver update`. For Calendar Versioning, make sure the date has advanced, or use flags like `--build` or `--inc0` to increment non-date parts for same-day releases.
WARNING - Version Control System not found, skipping commit.
When running 'bumpver update' with the '--commit' flag or with 'commit = true' in the configuration, 'bumpver' attempts to interact with Git or Mercurial. This warning indicates that it could not detect a valid version control system repository, often because the command was not executed from the project's root directory where the '.git' or '.hg' directory resides.
fix
Ensure you are running the `bumpver` command from the root directory of your Git or Mercurial repository. If your project isn't under version control, initialize one (e.g., `git init`). If you do not wish to commit, remove the `--commit` flag or set `commit = false` in your configuration.
pre_commit_hook = 'some command' This fails immediately - bumpver expects a path to a script, not a command
The 'pre_commit_hook' configuration option in 'bumpver' expects a path to an executable script file (e.g., a '.sh' shell script or a '.py' Python script), not a direct shell command string.
fix
Create a separate executable script file (e.g., named `pre-bump.sh`) containing the commands you wish to execute. Then, in your 'bumpver.toml', set `pre_commit_hook = 'path/to/your/pre-bump.sh'`, ensuring the path is correct and the script has execute permissions.
Upgrade
Version history
2025.1131latest on PyPI · released Jul 2, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
14
Resources
bumpver — pip install bumpver · libregistry