{"id":6555,"library":"bumpver","title":"bumpver","description":"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.","status":"active","version":"2025.1131","language":"python","source_language":"en","source_url":"https://github.com/mbarkhau/bumpver","tags":["versioning","CLI tool","semantic versioning","calendar versioning","build tool","automation"],"install":[{"cmd":"pip install bumpver","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[],"quickstart":{"code":"import os\nimport subprocess\n\ndef setup_project():\n    # Simulate project structure\n    os.makedirs('my_project', exist_ok=True)\n    os.chdir('my_project')\n    with open('pyproject.toml', 'w') as f:\n        f.write(\"\"\"\n[tool.bumpver]\ncurrent_version = \"2024.1.0\"\nversion_pattern = \"YYYY.MINOR.PATCH\"\n\n[tool.bumpver.file_patterns]\n\"src/__init__.py\" = [\n    '^__version__ = \"{version}\"$',\n]\n\"README.md\" = [\n    'Current Version: {version}',\n]\n\"\"\"\n        )\n    os.makedirs('src', exist_ok=True)\n    with open('src/__init__.py', 'w') as f:\n        f.write('__version__ = \"2024.1.0\"\\n')\n    with open('README.md', 'w') as f:\n        f.write('My Project\\n\\nCurrent Version: 2024.1.0\\n')\n\n    # Initialize bumpver config if it doesn't exist (optional, but good practice)\n    try:\n        subprocess.run([\"bumpver\", \"init\"], check=True, capture_output=True)\n        print(\"bumpver init successful.\")\n    except subprocess.CalledProcessError as e:\n        print(f\"bumpver init failed: {e.stderr.decode()}\")\n\ndef run_bumpver_update():\n    print(\"\\n--- Running bumpver update --patch --dry ---\")\n    try:\n        result = subprocess.run([\"bumpver\", \"update\", \"--patch\", \"--dry\"], check=True, capture_output=True)\n        print(result.stdout.decode())\n    except subprocess.CalledProcessError as e:\n        print(f\"bumpver update failed: {e.stderr.decode()}\")\n\n    print(\"\\n--- Verifying file contents (dry run means no actual changes) ---\")\n    with open('src/__init__.py', 'r') as f:\n        print(f\"src/__init__.py: {f.read().strip()}\")\n    with open('README.md', 'r') as f:\n        print(f\"README.md: {f.read().strip()}\")\n\n    print(\"\\n--- Running actual bumpver update --patch ---\")\n    try:\n        result = subprocess.run([\"bumpver\", \"update\", \"--patch\"], check=True, capture_output=True)\n        print(result.stdout.decode())\n    except subprocess.CalledProcessError as e:\n        print(f\"bumpver update failed: {e.stderr.decode()}\")\n\n    print(\"\\n--- Verifying actual file contents ---\")\n    with open('src/__init__.py', 'r') as f:\n        print(f\"src/__init__.py: {f.read().strip()}\")\n    with open('README.md', 'r') as f:\n        print(f\"README.md: {f.read().strip()}\")\n\nif __name__ == '__main__':\n    original_dir = os.getcwd()\n    try:\n        setup_project()\n        run_bumpver_update()\n    finally:\n        os.chdir(original_dir)\n        # Clean up created directory if necessary (omitted for simplicity in quickstart)\n\n","lang":"python","description":"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."},"warnings":[{"fix":"Update `pip` installations from `pycalver` to `bumpver` and review `version_pattern` configurations, preferably updating to the new syntax described in current documentation.","message":"The 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.","severity":"breaking","affected_versions":"<2020.1100-beta"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"For 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Incorrectly 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Using 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'2025.1131':61 'activ':66 'ad':80 'address':76 'autom':92 'automat':14 'bug':77 'build':90 'bumpver':1,2 'cadenc':68 'calendar':29,88 'calver':31 'cli':84 'command':9 'command-lin':8 'commit':56 'current':58 'design':12 'featur':82 'file':18,37 'fix':78 'git':48 'includ':24 'integr':45 'librari':6 'line':10 'make':38 'manag':52 'mercuri':50 'new':81 'often':71 'option':46 'plain':35 'project':17,43,63 'python':5 'releas':67 'scheme':23 'semant':25,86 'semver':27 'sever':72 'suitabl':40 'support':20 'tag':54 'text':36 'time':73 'tool':11,85,91 'updat':70 'various':21 'version':15,22,26,30,53,59,83,87,89 'work':33 'year':75","created_at":"2026-04-15T18:32:55.116439+00:00","updated_at":"2026-04-16T01:09:10.993930+00:00","problems":[{"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.","cause":"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'.","error":"ERROR - Pattern not found: '{your_pattern}'"},{"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.","cause":"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).","error":"ERROR - Invalid version '{version}' and/or pattern '{pattern}'"},{"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.","cause":"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.","error":"WARNING - Version Control System not found, skipping commit."},{"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.","cause":"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.","error":"pre_commit_hook = 'some command' This fails immediately - bumpver expects a path to a script, not a command"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"bumpver","cli_version":"bumpver, version 2025.1131","type":"library","homepage":null,"github":"https://github.com/mbarkhau/bumpver","docs":null,"changelog":null,"pypi":"https://pypi.org/project/bumpver/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-15","next_check":"2026-07-14","install_tag":null}}