Support Python Versions

CI/CD Pipeline:

SonarCloud:

BumpCalver CLI Documentation¶

Overview¶

The BumpCalver CLI is a command-line interface for calendar-based version bumping. It automates the process of updating version strings in your project's files based on the current date and build count. Additionally, it can create Git tags and commit changes automatically. The CLI is highly configurable via a pyproject.toml file and supports various customization options to fit your project's needs.

Table of Contents¶

Documentation Site: BumpCalver CLI
Installation
Getting Started
Command-Line Usage
Options
Error Handling
Support

Installation¶

To install the BumpCalver CLI, you can add it to your project's dependencies. If it's packaged as a Python module, you might install it via:

pip install bumpcalver

Getting Started¶

Configure Your Project: Create or update the pyproject.toml file in your project's root directory to include the [tool.bumpcalver] section with your desired settings.
Run the CLI: Use the bumpcalver command with appropriate options to bump your project's version.

Example:

bumpcalver --build --git-tag --auto-commit

AI Assistant Bootstrap (for app repositories)¶

If you're using Claude, Copilot, or another AI assistant to set up bumpcalver in your project, pull packaged, always-current integration instructions directly from the installed library into your repo's own instruction file — one command, no manual copy-paste of the Configuration section below:

python -m bumpcalver.ai_instructions claude --write     # writes ./CLAUDE.md
python -m bumpcalver.ai_instructions copilot --write    # writes ./.github/copilot-instructions.md
python -m bumpcalver.ai_instructions generic > AI_INSTRUCTIONS.md

Or from Python:

from bumpcalver import get_app_instructions, suggested_instruction_filename

assistant = "copilot"  # or "claude" / "generic"
print(f"Suggested destination: {suggested_instruction_filename(assistant)}")
print(get_app_instructions(assistant))

This avoids an assistant reverse-engineering the [tool.bumpcalver] schema from scratch and keeps the guidance it produces aligned with the version of bumpcalver actually installed — including which file_type to pick for a given file, the three versioning modes, and which config keys have real (git tag/commit) side effects. See AI Assistant Instructions for the full details, including what these instructions do not yet cover.

Configuration¶

The BumpCalver CLI relies on a pyproject.toml configuration file located at the root of your project. This file specifies how versioning should be handled, which files to update, and other settings.

As an alternative, you can use configuration file named bumpcalver.toml. The CLI will look for this file if pyproject.toml is not found.

Configuration Options¶

version_format (string): Format string for the version. Supports {current_date}, {build_count}, and the hybrid placeholders {major}, {minor}, {patch}.
date_format (string): Format string for the date. Supports various combinations of year, month, day, quarter, and week.
timezone (string): Timezone for date calculations (e.g., UTC, America/New_York).
major (integer, optional): Major version component for hybrid versioning. Defaults to 0.
minor (integer, optional): Minor version component for hybrid versioning. Defaults to 0.
patch (integer, optional): Patch version component for hybrid versioning. Defaults to 0.
beta_format (string, optional): Suffix appended when --beta is used. Supports a {beta_count} placeholder for auto-incrementing. Defaults to .beta.
rc_format (string, optional): Suffix appended when --rc is used. Supports a {rc_count} placeholder. Defaults to .rc.
release_format (string, optional): Suffix appended when --release is used. Defaults to .release.
file (list of tables): Specifies which files to update and how to find the version string.
path (string): Path to the file to be updated.
file_type (string): Type of the file (e.g., python, toml, yaml, json, xml, dockerfile, makefile, properties, env, setup.cfg, text, regex).
variable (string, optional): The variable name that holds the version string in the file.
pattern (string, optional): A regex pattern to find the version string.
version_standard (string, optional): The versioning standard to follow (e.g., python for PEP 440).
git_tag (boolean): Whether to create a Git tag with the new version.
auto_commit (boolean): Whether to automatically commit changes when creating a Git tag.

Example Configuration¶

[tool.bumpcalver]
version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
timezone = "America/New_York"
git_tag = true
auto_commit = true

[[tool.bumpcalver.file]]
path = "pyproject.toml"
file_type = "toml"
variable = "project.version"
version_standard = "python"

[[tool.bumpcalver.file]]
path = "examples/makefile"
file_type = "makefile"
variable = "APP_VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "arg.VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "env.APP_VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "examples/p.py"
file_type = "python"
variable = "__version__"
version_standard = "python"

[[tool.bumpcalver.file]]
path = "sonar-project.properties"
file_type = "properties"
variable = "sonar.projectVersion"
version_standard = "default"

[[tool.bumpcalver.file]]
path = ".env"
file_type = "env"
variable = "VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "setup.cfg"
file_type = "setup.cfg"
variable = "metadata.version"
version_standard = "python"

[[tool.bumpcalver.file]]
path = "VERSION"
file_type = "text"

[[tool.bumpcalver.file]]
path = "lib/version.rb"
file_type = "regex"
variable = "VERSION"
pattern = 'VERSION = "(.+?)"'

Date Format Examples¶

The date_format option allows you to customize the date format used in version strings. Here are some examples of how to format dates:

%Y.%m.%d - Full year, month, and day (e.g., 2024.12.25)
%y.%m.%d - Year without century, month, and day (e.g., 24.12.25)
%y.Q%q - Year and quarter (e.g., 24.Q1)
%y.%m - Year and month (e.g., 24.12)
%y.%j - Year and day of the year (e.g., 24.001 for January 1st, 2024)
%Y.%j - Full year and day of the year (e.g., 2024.001 for January 1st, 2024)
%Y.%m - Full year and month (e.g., 2024.12)
%Y.Q%q - Full year and quarter (e.g., 2024.Q1)

Refer to the Python datetime documentation for more format codes.

Supported File Types¶

BumpCalver supports version management for the following file types:

Core File Types¶

python - Python files with version variables (e.g., __version__ = "1.0.0")
toml - TOML configuration files (e.g., pyproject.toml)
yaml - YAML configuration files
json - JSON configuration files (e.g., package.json)
xml - XML configuration files

Infrastructure Files¶

dockerfile - Docker files with ARG or ENV variables
makefile - Makefiles with version variables

Configuration Files¶

properties - Java-style properties files (e.g., sonar-project.properties)
Format: key=value
Example: sonar.projectVersion=2025.02.02
env - Environment variable files (e.g., .env)
Format: KEY=value or KEY="value"
Example: VERSION=2025.02.02
setup.cfg - Python setup configuration files
Supports both dot notation (metadata.version) and simple keys (version)
Example: version = 2025.02.02 in [metadata] section

Generic File Types¶

For formats without a dedicated handler above:

text - A bare version file whose entire content is the version, with no key at all (e.g. a VERSION file used by shell-based release pipelines). variable is not used.
Example file content: 2025.02.02
regex - Any other KEY = value-style language (Ruby, Rust, Go, Java, etc.) via a user-supplied pattern: a regex with exactly one capture group around the version. Everything else on the matched line is left untouched.
Example: pattern = 'VERSION = "(.+?)"' matches Ruby's VERSION = "2025.02.02" and replaces only the quoted text.

Custom File Types via Plugins¶

If none of the above fit and text/regex aren't enough, third-party packages can register their own file_type handlers without forking bumpcalver, via a bumpcalver.handlers entry point. See the "Distributing Your Handler as a Plugin" section of the development guide and the runnable example at examples/bumpcalver-plugin-example/.

Command-Line Usage¶

The CLI provides several options to customize the version bumping process. Run bumpcalver --help for the exact, current list — the same output is also published at CLI Reference, kept byte-for-byte in sync with the code by a test (tests/test_docs.py) rather than hand-copied here.

Version Bump Options¶

--beta: Appends the configured beta_format suffix (default .beta) to the version.
--rc: Appends the configured rc_format suffix (default .rc) to the version.
--release: Appends the configured release_format suffix (default .release) to the version.
--custom TEXT: Adds a custom suffix to the version.
--build: Increments the build count based on the current date.
--bump [major|minor|patch]: Increments the specified semantic component (major, minor, or patch) in config and writes the new value back. Use with hybrid version_format strings that contain {major}, {minor}, or {patch}.
--timezone: Overrides the timezone specified in the configuration.
--git-tag / --no-git-tag: Forces Git tagging on or off, overriding the configuration.
--auto-commit / --no-auto-commit: Forces auto-commit on or off, overriding the configuration.
--dry-run: Prints the version that would be set and which files would change, without writing anything or creating a git tag/commit.
--config-file PATH: Use a specific pyproject.toml/bumpcalver.toml instead of auto-discovering one in the current directory (also settable via the BUMPCALVER_CONFIG environment variable). File paths inside that config resolve relative to the config file's own directory — handy for monorepo tooling or wrapper scripts invoking bumpcalver from elsewhere. Cannot be combined with the undo options below.
--json: Emit a single JSON object with the result to stdout instead of human-readable log lines (those move to stderr). See Machine-Readable Output below. Cannot be combined with the undo options below.

Machine-Readable Output¶

Pass --json for a script-friendly result instead of log lines — useful in CI to capture the computed version, or to check which files actually changed:

bumpcalver --build --json 2>/dev/null
# {"version": "2026.07.25.001", "files_updated": ["src/myapp/__init__.py"], "operation_id": "20260725_120000_000", "git_tag": null, "git_commit_hash": null}

Works the same way with --dry-run ({"dry_run": true, ...}), a no-op bump ({"no_op": true, ...}), or an error ({"error": "..."} with a non-zero exit code) — stdout is always exactly one JSON object, never a mix of log lines and data. See the CLI Reference for the full payload shape of each case.

Undo Options¶

BumpCalver includes powerful undo functionality to revert version changes:

--undo: Undo the most recent version bump operation.
--undo-id TEXT: Undo a specific operation by its unique ID.
--list-history: Show recent version bump operations that can be undone.

Note: Undo options cannot be combined with version bump options (including --dry-run and --config-file).

Examples¶

Basic Version Bump¶

To bump the version using the current date and build count:

bumpcalver --build

Beta Versioning¶

To create a beta version:

bumpcalver --build --beta

Specifying Timezone¶

To use a specific timezone:

bumpcalver --build --timezone Europe/London

Creating a Git Tag with Auto-Commit¶

To bump the version, commit changes, and create a Git tag:

bumpcalver --build --git-tag --auto-commit

Capturing the New Version in CI¶

Use --json plus jq (or any JSON tool) to feed the computed version into later pipeline steps, e.g. a GitHub Actions step output:

VERSION=$(bumpcalver --build --json 2>/dev/null | jq -r '.version')
echo "version=$VERSION" >> "$GITHUB_OUTPUT"

Undo Operations¶

View recent version bump operations:

bumpcalver --list-history

Undo the last version bump:

bumpcalver --undo

Undo a specific operation by ID:

bumpcalver --undo-id 20251012_143015_123

Pre-release Versioning¶

By default --beta, --rc, and --release append .beta, .rc, and .release:

bumpcalver --build --beta     # → 26.05.24.1.beta
bumpcalver --build --rc       # → 26.05.24.1.rc
bumpcalver --build --release  # → 26.05.24.1.release

Configure the suffix format — including an optional counter — in pyproject.toml:

[tool.bumpcalver]
beta_format    = "b{beta_count}"   # PEP 440 style: 26.05.24.1b1, 26.05.24.1b2
rc_format      = "rc{rc_count}"   # PEP 440 style: 26.05.24.1rc1
release_format = ".release"       # literal suffix (no counter)

The {beta_count} placeholder auto-increments when the same base version already has a beta suffix in the file; it resets to 1 when the base version changes.

bumpcalver --beta   # → 26.05.24.1b1  (first beta of this build)
bumpcalver --beta   # → 26.05.24.1b2  (second beta of the same build)
bumpcalver --build --beta  # → 26.05.24.2b1  (new build, counter resets)

Hybrid Semantic + Calendar Versioning¶

Combine a SemVer prefix with a CalVer date to signal both maturity and release timing:

[tool.bumpcalver]
major = 1
minor = 0
patch = 0
version_format = "{major}.{minor}-{current_date}.{build_count}"
date_format = "%Y%m%d"

# Standard build — uses major/minor from config
bumpcalver --build
# → 1.0-20260523.1

# Bump minor and rebuild in one step
bumpcalver --build --bump minor
# → 1.1-20260523.1  (config updated: minor = 1)

# Bump major (resets minor and patch to 0)
bumpcalver --build --bump major
# → 2.0-20260523.1  (config updated: major = 2, minor = 0, patch = 0)

See the Hybrid Versioning Guide for full details.

Safety Net Workflow¶

Use undo functionality as a safety net during development:

# Make experimental version bump
bumpcalver --custom "experimental"

# Test your changes...

# If tests pass, make official version
bumpcalver --undo  # Undo experimental version
bumpcalver --build --git-tag --auto-commit  # Official version

# If tests fail, just undo
bumpcalver --undo  # Back to original state

For complete undo documentation, see Undo Docs.

Documentation¶

For comprehensive information about BumpCalver, check out our documentation:

QuickStart Guide - Get started with BumpCalver quickly
Calendar Versioning Guide - Comprehensive guide to calendar versioning patterns, real-world examples, and best practices
Hybrid Versioning Guide - Combining semantic version prefixes (1.0) with calendar dates for dual-signal versioning
Development Guide - How to contribute to the project, development setup, testing procedures, and PR guidelines
Undo Operations - How to revert version changes
Hybrid Versioning Guide - Combining semantic version prefixes with calendar dates

For the full documentation site, visit: BumpCalver CLI Documentation

Error Handling¶

Unknown Timezone: If an invalid timezone is specified, the default timezone (America/New_York) is used, and a warning is printed.
File Not Found: If a specified file is not found during version update, an error message is printed.
Invalid Build Count: If the existing build count in a file is invalid, it resets to 1, and a warning is printed.
Git Errors: Errors during Git operations are caught, and an error message is displayed.
Malformed Configuration: If the pyproject.toml file is malformed, an error is printed, and the program exits.

Support¶

For issues or questions, please open an issue on the project's repository.