### CFG Configuration Example

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

An example of global configuration settings in CFG (INI) format. This demonstrates equivalent settings to the TOML example for version parsing, serialization, commit behavior, and tag creation.

```ini
[bumpversion]
allow_dirty = False
commit = False
message = Bump version: {current_version} → {new_version}
commit_args = 
tag = False
sign_tags = False
tag_name = v{new_version}
tag_message = Bump version: {current_version} → {new_version}
current_version = 1.0.0
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)
serialize =
    {major}.{minor}.{patch}
search = {current_version}
replace = {new_version}
```

--------------------------------

### Example __init__.py file content

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/update-a-date.md

This is an example of an __init__.py file containing version and date information that needs to be updated.

```python
__date__ = '2022-12-19'
__version__ = '0.4.0'
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Use this command to install all necessary development dependencies for the project.

```bash
uv sync --all-groups
```

--------------------------------

### Clone Repository and Setup Virtual Environment

Source: https://github.com/callowayproject/bump-my-version/blob/master/CONTRIBUTING.md

Clone the repository, navigate into the directory, and set up an isolated Python development environment using venv. Install the project in editable mode with development and testing dependencies.

```sh
# Clone the repository
git clone https://github.com/callowayproject/bump-my-version.git

# Enter the repository
cd bump-my-version

# Create, then activate a virtual environment
python -m venv env
source env/bin/activate

# Install the project in editable mode with its optional dependencies
python -m pip install -e .[dev,test]
```

--------------------------------

### TOML Configuration Example

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

An example of global configuration settings in TOML format. This includes options for version parsing, serialization, commit behavior, and tag creation.

```toml
[tool.bumpversion]
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
commit_args = ""
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
current_version = "1.0.0"
parse = "(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
serialize = [
    "{major}.{minor}.{patch}"
]
search = "{current_version}"
replace = "{new_version}"
```

--------------------------------

### Install Bump My Version

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/tutorials/getting-started.md

Use uv to install Bump My Version as an independent tool on your system.

```bash
uv tool install bump-my-version
```

--------------------------------

### Setup Development Environment with Nix

Source: https://github.com/callowayproject/bump-my-version/blob/master/CONTRIBUTING.md

If using the Nix package manager and devenv, create and enter an isolated shell environment with all necessary packages pre-installed.

```sh
# Create and enter the devenv shell 
devenv shell
```

--------------------------------

### Show Versioning Path

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Visualize the versioning path for different starting points like a standard version, a dev version, or an rc version. This helps understand how versions will increment.

```console
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
               ├─ minor ─ 0.2.0-dev0
               ├─ patch ─ 0.1.1-dev0
               ├─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
               ╰─ pre_n ─ 0.1.0-final1
```

```console
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
                    ├─ minor ─ 1.1.0-dev0
                    ├─ patch ─ 1.0.1-dev0
                    ├─ pre_l ─ 1.0.0-rc0
                    ╰─ pre_n ─ 1.0.0-dev1
```

```console
$ bump-my-version show-bump 1.0.0-rc0 
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
                   ├─ minor ─ 1.1.0-dev0
                   ├─ patch ─ 1.0.1-dev0
                   ├─ pre_l ─ 1.0.0
                   ╰─ pre_n ─ 1.0.0-rc1
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/callowayproject/bump-my-version/blob/master/CONTRIBUTING.md

Install pre-commit hooks to automatically run checks before each commit. These hooks help maintain code quality and consistency.

```sh
pre-commit install
```

--------------------------------

### Configure Hook Suites with Commands

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/hooks.md

Configure setup, pre-commit, and post-commit hook suites using lists of shell commands. Ensure commands are valid for direct execution or when `allow_shell_hooks` is enabled.

```toml
[tool.bumpversion]
setup_hooks = [
    "git config --global user.email \"bump-my-version@github.actions\"",
    "git config --global user.name \"Testing Git\"",
    "git --version",
    "git config --list",
]
pre_commit_hooks = ["cat CHANGELOG.md"]
post_commit_hooks = ["echo Done"]

```

--------------------------------

### Go Module Declaration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/custom-version-formats-by-file.md

Example of a Go module declaration in a go.mod file, including the major version in the module path.

```go
module github.com/myorg/myproject/v2

go 1.12

require (
    ...
)
```

--------------------------------

### Configure Multiple Replacements for CHANGELOG.md

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/multiple-replacements.md

Use multiple `[[tool.bumpversion.files]]` sections for the same file to perform distinct replacements. This example updates the 'Unreleased' heading and a version comparison link in `CHANGELOG.md`.

```toml
[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
search = "Unreleased"

[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
search = "{current_version}...HEAD"
replace = "{current_version}...{new_version}"
```

--------------------------------

### YAML Release Channels Version

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/custom-version-formats-by-file.md

Example of a version string in a YAML file, used for release channels.

```yaml
stable: "v2.21.4"
```

--------------------------------

### Configure Release Part in INI

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/version-component.md

Example of configuring a 'release' version part using INI format. This snippet demonstrates setting custom string values and an optional value for the version part.

```ini
[bumpversion:part:release]
optional_value = gamma
values =
    alpha
    beta
    gamma

```

--------------------------------

### Configure Serialization for Pre-release Automation

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Automate pre-release numbering by modifying the serialization configuration. This example uses `distance_to_latest_tag` to automatically increment pre-release versions.

```toml
parse = """(?x)
    (?P<major>0|[1-9]\d*)\.
    (?P<minor>0|[1-9]\d*)\.
    (?P<patch>0|[1-9]\d*)
    (?: 
        -                             # dash separator for pre-release section
        (?P<pre_l>[a-zA-Z-]+)         # pre-release label
        (?:0|[1-9]\d*)               # pre-release version number
    )?                                # pre-release section is optional
"""

serialize = [
    "{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}",
    "{major}.{minor}.{patch}",
]
```

--------------------------------

### Configure Release Part in TOML

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/version-component.md

Example of configuring a 'release' version part using TOML format. This snippet shows how to define custom string values for the part, specify an optional value, and set the default behavior.

```toml
[tool.bumpversion.parts.release]
values = [
    "alpha",
    "beta",
    "gamma"
]
optional_value = "gamma"

```

--------------------------------

### Get New Version in Script

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/tutorials/getting-started.md

Retrieve the current or new version information within a script using the 'show' method. Specify the desired version attribute and optionally an increment.

```bash
$ bump-my-version show current_version
1.2.3
$ bump-my-version show --increment minor new_version
1.3.3

```

--------------------------------

### CalVer Format Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/calver_reference.md

Define the version format using CalVer codes in the configuration. This example sets the release format to YYYY.MM.DD.

```toml
[tool.bumpversion.parts.release]
calver_format = "{YYYY}.{MM}.{DD}"
```

--------------------------------

### TOML Version Part Configuration with First Value

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/version-parts.md

Specify a custom starting value for a numeric version part. This changes the initial value when the part is first introduced or reset.

```toml
[tool.bumpversion.parts.pre_n]
first_value = "1"
```

--------------------------------

### CalVer Version Parsing Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/calver_reference.md

Configure how CalVer versions are parsed using regular expressions. This example parses a version string in the YYYY.MM.DD format for the 'release' part.

```toml
[tool.bumpversion]
parse = """(?x)                      # Verbose mode
    (?P<release>
        (?:[1-9][0-9]{3})\.         # YYYY.
        (?:1[0-2]|[1-9])\.          # MM.
        (?:3[0-1]|[1-2][0-9]|[1-9])  # DD
    )
"""
```

--------------------------------

### Show Version in YAML Format

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/show-subcommand.md

Retrieve the current version and format the output as YAML.

```console
$ bump-my-version show --format yaml current_version
current_version: "1.0.1"
```

--------------------------------

### Show Version in JSON Format

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/show-subcommand.md

Retrieve the current version and format the output as JSON.

```console
$ bump-my-version show --format json current_version
{
  "current_version": "1.0.1"
}
```

--------------------------------

### Show Current Version

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/show-subcommand.md

Display the current version of the project. This is the default behavior when no specific configuration key is provided.

```console
$ bump-my-version show current_version
1.0.1
```

--------------------------------

### Generate Default Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/tutorials/getting-started.md

Create a default .bumpversion.toml configuration file using the sample-config command. This configuration uses a simplified semantic versioning scheme.

```bash
$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml
$ cat .bumpversion.toml
[tool.bumpversion]
current_version = "0.1.0"
parse = "(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
commit_args = ""

```

--------------------------------

### Configure Pre-release Versions (Serialize)

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Update the 'serialize' configuration to handle the formatting of pre-release versions. This allows for both pre-release and standard version formats.

```toml
serialize = [
    "{major}.{minor}.{patch}-{pre_l}{pre_n}",
    "{major}.{minor}.{patch}",
]

```

--------------------------------

### Visualize Versioning Path

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Use the show-bump subcommand to visualize potential versioning paths. The default configuration only supports major, minor, or patch bumps.

```console
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0
               ├─ minor ─ 0.2.0
               ╰─ patch ─ 0.1.1
$ bump-my-version show-bump 1.2.3
1.2.3 ── bump ─┬─ major ─ 2.0.0
               ├─ minor ─ 1.3.0
               ╰─ patch ─ 1.2.4

```

--------------------------------

### Visualize Versioning Path

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/tutorials/getting-started.md

Use the show-bump subcommand to visualize potential versioning paths. This helps in debugging versioning logic.

```bash
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0
               ├─ minor ─ 0.2.0
               ╰─ patch ─ 0.1.1

```

```bash
$ bump-my-version show-bump 1.2.3
1.2.3 ── bump ─┬─ major ─ 2.0.0
               ├─ minor ─ 1.3.0
               ╰─ patch ─ 1.2.4

```

--------------------------------

### Configure Hook Suites with Scripts

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/hooks.md

Configure hook suites by providing paths to executable scripts. Ensure scripts have execute permissions and a shebang line if necessary.

```toml
[tool.bumpversion]
setup_hooks = ["path/to/setup.sh"]
pre_commit_hooks = ["path/to/pre-commit.sh"]
post_commit_hooks = ["path/to/post-commit.sh"]

```

--------------------------------

### Show Versioning Path with Pre_n Automation

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Visualize the versioning path after enabling pre_n automation. The `pre_n` path is now missing as it's handled automatically by commit count.

```console
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
               ├─ minor ─ 0.2.0-dev0
               ├─ patch ─ 0.1.1-dev0
               ╰─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
```

```console
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
                    ├─ minor ─ 1.1.0-dev0
                    ├─ patch ─ 1.0.1-dev0
                    ╰─ pre_l ─ 1.0.0-rc0
```

```console
$ bump-my-version show-bump 1.0.0-rc0 
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
                   ├─ minor ─ 1.1.0-dev0
                   ├─ patch ─ 1.0.1-dev0
                   ╰─ pre_l ─ 1.0.0
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Execute all pre-commit hooks defined for the repository on all files to ensure code quality before commits.

```bash
pre-commit run --all-files
```

--------------------------------

### Updated __init__.py file content

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/update-a-date.md

This shows the desired state of the __init__.py file after a version bump, with the date updated to the current date.

```python
__date__ = '2024-02-23'
__version__ = '0.5.0'
```

--------------------------------

### Configure Pre-release Versions (Parse)

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Modify the 'parse' configuration to include support for pre-release versions. This uses an extended regular expression to capture version components.

```toml
parse = """(?x)
    (?P<major>0|[1-9]\d*)\.
    (?P<minor>0|[1-9]\d*)\.
    (?P<patch>0|[1-9]\d*)
    (?: # dash separator for pre-release section
        -                             # dash separator for pre-release section
        (?P<pre_l>[a-zA-Z-]+)         # pre-release label
        (?P<pre_n>0|[1-9]\d*)
    )?                                # pre-release section is optional
"""

```

--------------------------------

### Configure Pre-release Label Values

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

Define the possible values for the pre-release label ('pre_l') and specify an optional default value. This section is added to the configuration.

```toml
[tool.bumpversion.parts.pre_l]
values = ["dev", "rc", "final"]
optional_value = "final"

```

--------------------------------

### Show Incremented Version (Minor)

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/show-subcommand.md

Preview the version after a minor increment without actually bumping. The new version is added to the configuration.

```console
$ bump-my-version --increment minor show
1.1.0
```

--------------------------------

### Lint and Format Code with Ruff

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Apply linting and formatting rules using Ruff to maintain code quality and consistency across the project.

```bash
uv run ruff check bumpversion/
```

```bash
uv run ruff format bumpversion/
```

--------------------------------

### TOML Version Configuration with Optional Pre-release Label

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/version-parts.md

Configure a version with optional pre-release labels and numbers. The 'stable' label and '0' for the pre-release number are optional and omitted from serialization when they are the default.

```toml
[tool.bumpversion]
current_version = "1.0.0"
parse = """(?x)
    (?P<major>[0-9]+)
    \.(?P<minor>[0-9]+)
    \.(?P<patch>[0-9]+)
    (?: 
        -(?P<pre_label>alpha|beta|stable)
        (?:-(?P<pre_n>[0-9]+))?
    )?
"""
serialize = [
	"{major}.{minor}.{patch}-{pre_label}-{pre_n}",
	"{major}.{minor}.{patch}",
]

[tool.bumpversion.parts.pre_label]
optional_value = "stable"
values =[
	"alpha",
	"beta",
	"stable",
]
```

--------------------------------

### Bump My Version Configuration for Date Updates

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/update-a-date.md

Configure Bump My Version to update the date in '__init__.py'. It uses regex to find the date pattern and replaces it with the current date formatted as YYYY-MM-DD.

```toml
[[tool.bumpversion.files]]
filename = '__init__.py'
search = "__date__ = '\d{{4}}-\d{{2}}-\d{{2}}'"
replace = "__date__ = '{now:%Y-%m-%d}'"
regex = true

[[tool.bumpversion.files]]
filename = '__init__.py'
```

--------------------------------

### Bump My Version Configuration for Go and YAML

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/custom-version-formats-by-file.md

Configuration for Bump My Version to manage versions in go.mod and release-channels.yaml files. It specifies custom parsing and serialization for the go.mod file to handle major versioning.

```toml
[tool.bumpversion]
current_version = "2.21.4"

[[tool.bumpversion.files]]
filename = "go.mod"
parse = "(?P<major>\\d+)"
serialize = "{major}"
search = "module github.com/myorg/myproject/v{current_version}"
replace = "module github.com/myorg/myproject/v{new_version}"

[[tool.bumpversion.files]]
filename = "release-channels.yaml"
```

--------------------------------

### Configure File Modification

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/tutorials/getting-started.md

Set up Bump My Version to automatically update a specified file (e.g., VERSION) with the new version number during a bump operation.

```bash
$ echo "0.1.0" >> VERSION

```

```toml
[[tool.bumpversion.files]]
filename = "VERSION"

```

--------------------------------

### Show Incremented Version (Major)

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/show-subcommand.md

Preview the version after a major increment without actually bumping. The new version is added to the configuration.

```console
$ bump-my-version --increment major show
2.0.0
```

--------------------------------

### Configure Specific Replacements in requirements.txt

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/avoid-incorrect-replacements.md

Use custom search and replace patterns to target a specific version string within a file. This is crucial when a file contains multiple version numbers to avoid unintended modifications.

```toml
[tool.bumpversion]
current_version = "1.5.6"

[[tool.bumpversion.files]]
filename = "requirements.txt"
search = "MyProject=={current_version}"
replace = "MyProject=={new_version}"
```

--------------------------------

### Show Incremented Version (Patch)

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/show-subcommand.md

Preview the version after a patch increment without actually bumping. The new version is added to the configuration.

```console
$ bump-my-version --increment patch show
1.0.2
```

--------------------------------

### Configure Multiple File Modifications in INI

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/file.md

Use INI-style configuration to specify files for version bumping. Sections like `[bumpversion:file:<filename>]` or `[bumpversion:glob:<glob pattern>]` are used. To modify a file multiple times, append a unique description in parentheses to the section header.

```ini
[bumpversion:file:coolapp/__init__.py]

[bumpversion:file(version heading):CHANGELOG.md]
search = Unreleased

[bumpversion:file(previous version):CHANGELOG.md]
search = {current_version}...HEAD
replace = {current_version}...{new_version}
```

--------------------------------

### Serialization Templates Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

Specifies the default list of templates for serializing version parts back into a version string. Bumpversion tries these formats sequentially, choosing the last one that can represent all non-optional values. Each string uses Python Format String Syntax.

```text
serialize

required
: No

default
: `["{major}.{minor}.{patch}"]`

type
: an array of strings

command line option
: `--serialize`

environment var
: `BUMPVERSION_SERIALIZE`
```

--------------------------------

### Run a Single Test Function

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Execute a specific test function within a file. This allows for the most granular level of testing.

```bash
uv run pytest --agent-digest=term -p no:sugar tests/test_files.py::test_function_name
```

--------------------------------

### TOML Version Part Configuration with Values

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/version-parts.md

Configure a version part to use a sequence of predefined values instead of numeric incrementing. This is useful for non-numeric parts like release names.

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

--------------------------------

### bump-my-version CLI

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/cli.md

The bump-my-version CLI tool allows you to manage and increment version numbers in your project files. It supports various commands for different versioning tasks.

```APIDOC
## bump-my-version CLI Reference

This section outlines the commands and options available for the `bump-my-version` command-line tool.

### Usage

```bash
bump-my-version [OPTIONS] COMMAND [ARGS]...
```

### Commands

- **bump**: Bumps the version in the specified files.
- **--help**: Shows help information for the command.

### Options

- **--help**: Shows help information for the command.

### Example Usage

To bump the patch version in a `pyproject.toml` file:

```bash
bump-my-version patch pyproject.toml
```

To see all available commands and options:

```bash
bump-my-version --help
```
```

--------------------------------

### TOML Serialization Formats

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/version-parts.md

Define multiple serialization formats for version strings. Bump My Version selects the first format that matches the current version's components, omitting optional values when appropriate.

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

--------------------------------

### Run a Single Test File

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Execute tests within a specific file. This command is useful for targeted testing during development.

```bash
uv run pytest --agent-digest=term -p no:sugar tests/test_files.py
```

--------------------------------

### Initial CalVer Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/calver.md

Configure bump-my-version to use CalVer with a YYYY.MM.DD.patch format. This TOML file defines the version parsing and serialization rules.

```toml
[tool.bumpversion]
current_version = "2024.3.1.4"
parse = """(?x)                     # Verbose mode
    (?P<release>                    # The release part
        (?:[1-9][0-9]{3})\.        # YYYY.
        (?:1[0-2]|[1-9])\.         # MM.
        (?:3[0-1]|[1-2][0-9]|[1-9]) # DD
    )
    (?:\.(?P<patch>\d+))?         # .patch, optional
"""
serialize = ["{release}.{patch}", "{release}"]

[tool.bumpversion.parts.release]
calver_format = "{YYYY}.{MM}.{DD}"

```

--------------------------------

### Search Template Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

Defines the template string for searching. It's rendered using the formatting context and can be overridden by individual file configurations. This is useful for targeting specific version occurrences in a file.

```text
search

required
: No

default
: `{current_version}`

type
: string

command line option
: `--search`

environment var
: `BUMPVERSION_SEARCH`
```

--------------------------------

### Enable Shell Hooks for Compatibility

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/hooks.md

Opt-in to allow shell metacharacters in hook strings by setting `allow_shell_hooks = true`. This restores previous behavior but carries security risks if input is untrusted.

```toml
[tool.bumpversion]
allow_shell_hooks = true
post_commit_hooks = ["echo $BVHOOK_NEW_VERSION | tee version.txt"]

```

--------------------------------

### Sign Tags Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

A boolean option to determine if created tags should be signed. This only applies when the `tag` option is also set to `True`.

```text
sign_tags

required
: No

default
: `False` (Don't sign tags)

type
: boolean

command line option
: `--sign-tags | --no-sign-tags`

environment var
: `BUMPVERSION_SIGN_TAGS`
```

--------------------------------

### Basic Search and Replace with Template Strings

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/search-and-replace-config.md

Use template strings with curly braces for version placeholders in search and replace patterns. This is suitable for simple, non-regex searches.

```toml
[tool.bumpversion]
current_version = "1.2.3"

[[tool.bumpversion.files]]
filename = "config.ini"
search = "[myproject]\nversion={current_version}"
replace = "[myproject]\nversion={new_version}"
```

--------------------------------

### Multiline Search and Replace with TOML Strings

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/search-and-replace-config.md

Utilize TOML's multiline string syntax for more readable, multi-line search and replace patterns. This is useful for configurations spanning multiple lines.

```toml
[tool.bumpversion]
current_version = "1.2.3"

[[tool.bumpversion.files]]
filename = "config.ini"
search = """
[myproject]
version={current_version}"""

replace = """
[myproject]
version={new_version}"""
```

--------------------------------

### Run All Tests with Optimized Output

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Execute all project tests using pytest with optimized output flags. Ensure the `--agent-digest=term -p no:sugar` flags are included for better agent interaction.

```bash
uv run pytest --agent-digest=term -p no:sugar
```

--------------------------------

### Check Docstring Coverage

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Verify that docstring coverage meets the project's requirement of staying above 95%.

```bash
uv run interrogate bumpversion/
```

--------------------------------

### Run Project Tests

Source: https://github.com/callowayproject/bump-my-version/blob/master/CONTRIBUTING.md

Execute all project tests using pytest. Ensure your development environment is set up correctly before running this command.

```sh
pytest
```

--------------------------------

### Configure Multiple File Modifications in TOML

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/file.md

Use TOML to specify an array of file configurations. Each entry can define a filename and optionally search/replace patterns for version updates. This is useful for altering specific files multiple times within a single version bump.

```toml
[[tool.bumpversion.files]]
filename = "coolapp/__init__.py"

[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
search = "Unreleased"

[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
search = "{current_version}...HEAD"
replace = "{current_version}...{new_version}"
```

--------------------------------

### Rewrite Shell-Syntax Hooks to Scripts

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/hooks.md

Replace shell-syntax hooks that rely on pipes, redirects, or variable expansion with executable script files. This avoids the need for `allow_shell_hooks` and enhances security.

```toml
[tool.bumpversion]
# These will raise HookError by default
post_commit_hooks = [
    "echo $BVHOOK_NEW_VERSION > version.txt",
    "git log --oneline | head -5",
]

[tool.bumpversion]
# Pass the script file directly — no shell required
post_commit_hooks = [
    "path/to/update-version-file.sh",
    "path/to/show-log.sh",
]

```

```bash
#!/bin/bash
echo "$BVHOOK_NEW_VERSION" > version.txt

```

--------------------------------

### GitHub Actions Workflow for Version Bumping

Source: https://github.com/callowayproject/bump-my-version/blob/master/README.md

This workflow automates version bumping using bump-my-version. It allows manual input for the bump type (major, minor, patch) and automatically commits and tags the changes. Ensure you have the necessary permissions set for the workflow.

```yaml
name: Bump version

on:
  workflow_dispatch:
    inputs:
      bump-type:
        description: 'Bump type'
        required: true
        default: 'patch'
        type: choice
        options:
        - major
        - minor
        - patch

jobs:
  build:
    permissions:
      id-token: write
      pull-requests: read
      contents: write
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the code
        uses: actions/checkout@v4

      - name: Bump version
        id: bump
        uses: callowayproject/bump-my-version@master
        env:
          BUMPVERSION_TAG: "true"
        with:
          args: ${{ inputs.bump-type }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Check
        if: steps.bump.outputs.bumped == 'true'
        run: |
          echo "Version was bumped from ${{ steps.bump.outputs.previous-version }} to ${{ steps.bump.outputs.current-version }}"
```

--------------------------------

### Search with Regular Expressions and Escaping

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/search-and-replace-config.md

Configure search patterns using Python's regular expression syntax. Remember to double curly braces and escape backslashes for TOML.

```toml
search = "{current_version} date-released: \d{{4}}-\d{{2}}-\d{{2}}"
```

```ini
search = "{current_version} date-released: \d{{4}}-\d{{2}}-\d{{2}}"
```

--------------------------------

### Bumping Release Resets Patch

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/calver.md

Demonstrates how bumping the 'release' component resets the 'patch' component to its default value, even if the release date itself hasn't changed.

```console
$ date -I      
2024-03-1
$ bump-my-version show-bump
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.1
                    ╰─ patch ─── 2024.3.1.5

```

```console
$ date -I      
2024-03-2
$ bump-my-version show-bump
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.2
                    ╰─ patch ─── 2024.3.2

```

--------------------------------

### Tag Name Template Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

The template used to render the name of the tag when `tag` is enabled. This string is templated using Python Format String Syntax.

```text
tag_name

required
: No

default
: `v{new_version}`

type
: string

command line option
: `--tag-name`

environment var
: `BUMPVERSION_TAG_NAME`
```

--------------------------------

### Tag Creation Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

A boolean option to enable or disable the creation of a Git tag after committing changes. If enabled, the tag is named using the `tag_name` option.

```text
tag

required
: No

default
: `False` (Don't create a tag)

type
: boolean

command line option
: `--tag | --no-tag`

environment var
: `BUMPVERSION_TAG`
```

--------------------------------

### Perform Type Checking with Mypy

Source: https://github.com/callowayproject/bump-my-version/blob/master/AGENTS.md

Run Mypy for static type checking to catch potential type-related errors in the codebase.

```bash
uv run mypy bumpversion/
```

--------------------------------

### Dry Run Version Increment

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/tutorials/getting-started.md

Perform a dry run of the 'bump' subcommand to see the planned changes without modifying any files. Use -vv for detailed debugging output.

```ansi-shell-session
$ bump-my-version bump minor --dry-run -vv
{% include-markdown "../assets/getting-started-dry-run.ansi" comments=false %}

```

--------------------------------

### Updated Go Module Declaration after Major Version Bump

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/custom-version-formats-by-file.md

Shows the updated go.mod file after a major version bump, reflecting the new module path with the incremented major version.

```go
module github.com/myorg/myproject/v3
```

--------------------------------

### Configure Movable Tags

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/movable-version-tags.md

Define a list of serialization strings for movable tags in TOML format. These strings determine how tags like 'latest', 'v{new_major}.{new_minor}', and 'v{new_major}' are generated and managed.

```toml
moveable_tags = [
    "latest",
    "v{new_major}.{new_minor}",
    "v{new_major}"
]
```

--------------------------------

### Configure Replacements with Literal Quotes

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/howtos/avoid-incorrect-replacements.md

When the version string includes literal quotes, ensure your search and replace patterns also include these quotes to match correctly. This prevents errors when updating versions in shell scripts or similar formats.

```toml
[[tool.bumpversion.files]]
filename = "version.sh"
search = "MY_VERSION=\"{current_version}\""
replace = "MY_VERSION=\"{new_version}\""
```

--------------------------------

### TOML Independent Version Part Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/explanation/version-parts.md

Mark a version part as independent. Independent parts are not reset when other dependent parts change, allowing them to increment separately.

```toml
[tool.bumpversion.parts.build]
independent = true
```

--------------------------------

### Tag Message Template Configuration

Source: https://github.com/callowayproject/bump-my-version/blob/master/docs/reference/configuration/global.md

The template string used for the tag message when creating a tag. This string is templated using Python Format String Syntax. An empty `tag_message` value creates a lightweight tag instead of an annotated one.

```text
tag_message

required
: No

default
: `Bump version: {current_version} → {new_version}`

type
: string

command line option
: `--tag-message`

environment var
: `BUMPVERSION_TAG_MESSAGE`
```

--------------------------------

### Configure Giscus Theme on Load and Change

Source: https://github.com/callowayproject/bump-my-version/blob/master/overrides/partials/comments.html

This JavaScript code snippet dynamically sets the Giscus comment theme based on the website's color palette. It applies the theme on initial page load and updates it when the user changes the theme, ensuring a consistent user experience.

```javascript
var giscus = document.querySelector("script[src*=giscus]"); // Set palette on initial load
var palette = __md_get("__palette");
if (palette && typeof palette.color === "object") {
  var theme = palette.color.scheme === "slate" ? "transparent_dark" : "light";
  // Instruct Giscus to set theme
  giscus.setAttribute("data-theme", theme);
}
// Register event handlers after documented loaded
document.addEventListener("DOMContentLoaded", function () {
  var ref = document.querySelector("[data-md-component=palette]");
  ref.addEventListener("change", function () {
    var palette = __md_get("__palette");
    if (palette && typeof palette.color === "object") {
      var theme = palette.color.scheme === "slate" ? "transparent_dark" : "light";
      // Instruct Giscus to change theme
      var frame = document.querySelector(".giscus-frame");
      frame.contentWindow.postMessage(
        {
          giscus: {
            setConfig: {
              theme,
            },
          },
        },
        "https://giscus.app",
      );
    }
  });
});
```