bump-my-version

Bump My Version is designed to work within automated build systems to manage project versioning and metadata. Its core capabilities include:

• Versioning Management: Incrementing and serializing version numbers, parsing existing versions, and supporting various schemes like SemVer and CalVer.
• File Automation: Searching and replacing data within project files to keep version and metadata in sync with increments.
• Source Control Integration: Automating commits, tagging releases, and reading version numbers directly from source control tags.

A version configuration in Bump My Version defines how a version string is parsed and how it is rendered (serialized) back into a string. It consists of two main components:

1. parse: A regular expression containing named capture groups. Each named group corresponds to a version part (e.g., major, minor, patch).
2. serialize: A list of formatting strings used to render the version. Bump My Version iterates through this list and uses the first format where all non-optional values are present.

By providing multiple formats in serialize, you can omit parts that hold their 'first value' (which is considered optional by default).

serialize = [
    "{major}.{minor}.{patch}",
    "{major}.{minor}",
]

Bump My Version resolves configuration settings using a specific order of precedence. If a setting is defined in multiple places, the one with the highest precedence wins:

1. Command line arguments (Highest precedence)
2. Configuration files
3. Environment variables (Lowest precedence)

When a single file needs multiple distinct updates (for example, updating both a __version__ string and a __date__ string), you must define a separate [[tool.bumpversion.files]] block for each update task.

In the example below, the first block handles the regex-based date replacement, and the second block handles the standard version bump for the same file.

# First block: handles the date update via regex
[[tool.bumpversion.files]]
filename = '__init__.py'
search = "__date__ = '\\d{{4}}-\\d{{2}}-\\d{{2}}'"
replace = "__date__ = '{now:%Y-%m-%d}'"
regex = true

# Second block: handles the version bump
[[tool.bumpversion.files]]
filename = '__init__.py'

The formatting context provides a set of dynamic fields that can be used during version serialization, searching and replacing in files, generating commit messages, creating tag names, and creating tag annotations. These fields are accessed using curly brace syntax, such as {field_name}.

Available categories of fields include:

• Escaped characters: For literal # or ;.
• Date and time: For timestamps.
• Source code management: For Git or Mercurial metadata (e.g., commit SHA, branch name).
• Version fields: For accessing current and new version components.
• Environment variables: For accessing system environment variables.

A hook suite is a sequential list of hooks (shell commands or executable scripts) that run at specific stages of the version increment process.

There are three suites, executed in this order:

1. setup_hooks: Run before the version is incremented.
2. pre_commit_hooks: Run after the version is incremented and files are changed, but before the commit/tag operation.
3. post_commit_hooks: Run after the commit and tag operation is complete.

Note: These are distinct from Git's native pre- and post-commit hooks; they are named based on their position relative to the bump-my-version commit/tag step.

1. Run setup hooks
2. Increment version
3. Change files
4. Run pre-commit hooks
5. Commit and tag
6. Run post-commit hooks

Bump My Version is built around four core pillars:

1. Configuration: While many tasks can be done without it, a configuration file is required to specify the version scheme, the files to be changed, and the logic for how to change them.
2. Version handling: The logic for parsing, incrementing, and serializing version strings.
3. File changing: The mechanism for updating version strings within files.
4. Source control management interface: Integration with tools like Git to manage versioning via commits/tags.

Version parts can use two types of incrementing functions:

• Numeric (Default): Uses integers and returns the next integer. Parts start at 0 unless first_value is configured.
• Value: Uses a predefined sequence of values. This is useful for non-numeric labels like release names or development stages.

To use the values function, provide a list of strings in the part's configuration.

[tool.bumpversion.parts.release_name]
values = [
    "witty-warthog", 
    "ridiculous-rat", 
    "marvelous-mantis",
]

Serialization is the process of converting a version (a mapping of components to values) into a string. This is governed by two rules:

1. Optional value rule: A version component spec can define an optional value (e.g., numeric components often have 0 as an optional value). Optional values may be omitted from the string as long as all dependent components are also optional.
2. Required value rule: A component is required in the output string if its value—or the value of any of its dependent components—is not optional.

Optimal Serialization: The serialize method returns the optimal serialization, which is the valid serialization that uses the fewest components. If no valid serialization exists based on the provided formats, it returns the first invalid serialization encountered.

By default, the first value of any version part is considered optional. If a part's current value matches its first value, it can be omitted from the serialized version string based on your serialize configuration.

This is particularly useful for development stages (like alpha or beta) or for omitting a patch number when it is 0.

# Example: If patch is 0, it uses the second format and omits the patch
serialize = [
    "{major}.{minor}.{patch}",
    "{major}.{minor}",
]