{"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":"en","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,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}