From cdc33b886aa023f8a9ef78fbbb1f345cc7c7c128 Mon Sep 17 00:00:00 2001 From: <> Date: Thu, 14 Nov 2024 13:05:58 +0000 Subject: [PATCH] Deployed 0a9506b with MkDocs version: 1.6.1 --- 404.html | 2 +- CHANGELOG/index.html | 2 +- CONTRIBUTING/index.html | 6 +++--- explanation/index.html | 2 +- explanation/mental-model/index.html | 2 +- explanation/show-subcommand/index.html | 2 +- explanation/version-parts/index.html | 2 +- howtos/avoid-incorrect-replacements/index.html | 2 +- howtos/calver/index.html | 2 +- .../custom-version-formats-by-file/index.html | 2 +- howtos/multiple-replacements/index.html | 2 +- howtos/nav/index.html | 2 +- howtos/update-a-date/index.html | 2 +- index.html | 2 +- reference/api/bumpversion/aliases/index.html | 4 ++-- reference/api/bumpversion/autocast/index.html | 4 ++-- reference/api/bumpversion/bump/index.html | 4 ++-- reference/api/bumpversion/cli/index.html | 4 ++-- .../api/bumpversion/config/create/index.html | 4 ++-- .../api/bumpversion/config/files/index.html | 4 ++-- .../bumpversion/config/files_legacy/index.html | 4 ++-- reference/api/bumpversion/config/index.html | 4 ++-- .../api/bumpversion/config/models/index.html | 4 ++-- .../api/bumpversion/config/utils/index.html | 4 ++-- reference/api/bumpversion/context/index.html | 4 ++-- reference/api/bumpversion/exceptions/index.html | 4 ++-- reference/api/bumpversion/files/index.html | 4 ++-- reference/api/bumpversion/hooks/index.html | 4 ++-- .../api/bumpversion/indented_logger/index.html | 4 ++-- reference/api/bumpversion/index.html | 4 ++-- reference/api/bumpversion/scm/index.html | 4 ++-- reference/api/bumpversion/show/index.html | 4 ++-- reference/api/bumpversion/ui/index.html | 4 ++-- reference/api/bumpversion/utils/index.html | 4 ++-- .../versioning/conventions/index.html | 4 ++-- .../bumpversion/versioning/functions/index.html | 4 ++-- reference/api/bumpversion/versioning/index.html | 4 ++-- .../bumpversion/versioning/models/index.html | 4 ++-- .../versioning/serialization/index.html | 4 ++-- .../versioning/version_config/index.html | 4 ++-- reference/api/bumpversion/visualize/index.html | 4 ++-- reference/api/bumpversion/yaml_dump/index.html | 4 ++-- reference/api/nav/index.html | 4 ++-- reference/calver_reference/index.html | 2 +- reference/cli/index.html | 2 +- reference/configuration/file/index.html | 2 +- reference/configuration/global/index.html | 2 +- reference/configuration/index.html | 2 +- .../configuration/version-component/index.html | 2 +- reference/formatting-context/index.html | 2 +- reference/hooks/index.html | 2 +- reference/index.html | 2 +- reference/search-and-replace-config/index.html | 2 +- search/search_index.json | 2 +- sitemap.xml.gz | Bin 127 -> 127 bytes tutorials/getting-started/index.html | 2 +- tutorials/nav/index.html | 2 +- .../semantic-versioning-example/index.html | 2 +- 58 files changed, 88 insertions(+), 88 deletions(-) diff --git a/404.html b/404.html index 28aaba0..626ac05 100644 --- a/404.html +++ b/404.html @@ -12,7 +12,7 @@ - + diff --git a/CHANGELOG/index.html b/CHANGELOG/index.html index d7bad4b..411c8b6 100644 --- a/CHANGELOG/index.html +++ b/CHANGELOG/index.html @@ -16,7 +16,7 @@ - + diff --git a/CONTRIBUTING/index.html b/CONTRIBUTING/index.html index 73ea956..b77190d 100644 --- a/CONTRIBUTING/index.html +++ b/CONTRIBUTING/index.html @@ -14,7 +14,7 @@ - + @@ -2210,8 +2210,8 @@
Once setup, you should be able to run tests:
diff --git a/explanation/index.html b/explanation/index.html index 3ab3109..688ca9e 100644 --- a/explanation/index.html +++ b/explanation/index.html @@ -16,7 +16,7 @@ - + diff --git a/explanation/mental-model/index.html b/explanation/mental-model/index.html index d45fcae..46a2b6e 100644 --- a/explanation/mental-model/index.html +++ b/explanation/mental-model/index.html @@ -16,7 +16,7 @@ - + diff --git a/explanation/show-subcommand/index.html b/explanation/show-subcommand/index.html index 7067721..fd06b41 100644 --- a/explanation/show-subcommand/index.html +++ b/explanation/show-subcommand/index.html @@ -16,7 +16,7 @@ - + diff --git a/explanation/version-parts/index.html b/explanation/version-parts/index.html index dbd563e..459a6d5 100644 --- a/explanation/version-parts/index.html +++ b/explanation/version-parts/index.html @@ -16,7 +16,7 @@ - + diff --git a/howtos/avoid-incorrect-replacements/index.html b/howtos/avoid-incorrect-replacements/index.html index 96642a9..1cf165e 100644 --- a/howtos/avoid-incorrect-replacements/index.html +++ b/howtos/avoid-incorrect-replacements/index.html @@ -16,7 +16,7 @@ - + diff --git a/howtos/calver/index.html b/howtos/calver/index.html index 8d1252d..97ccbfc 100644 --- a/howtos/calver/index.html +++ b/howtos/calver/index.html @@ -16,7 +16,7 @@ - + diff --git a/howtos/custom-version-formats-by-file/index.html b/howtos/custom-version-formats-by-file/index.html index df2b9c9..d1e28db 100644 --- a/howtos/custom-version-formats-by-file/index.html +++ b/howtos/custom-version-formats-by-file/index.html @@ -16,7 +16,7 @@ - + diff --git a/howtos/multiple-replacements/index.html b/howtos/multiple-replacements/index.html index 0e5e581..4f67092 100644 --- a/howtos/multiple-replacements/index.html +++ b/howtos/multiple-replacements/index.html @@ -16,7 +16,7 @@ - + diff --git a/howtos/nav/index.html b/howtos/nav/index.html index 484d54f..d98daf6 100644 --- a/howtos/nav/index.html +++ b/howtos/nav/index.html @@ -12,7 +12,7 @@ - + diff --git a/howtos/update-a-date/index.html b/howtos/update-a-date/index.html index 6de8c1d..750f7c5 100644 --- a/howtos/update-a-date/index.html +++ b/howtos/update-a-date/index.html @@ -16,7 +16,7 @@ - + diff --git a/index.html b/index.html index 9a94ec3..5bb4a34 100644 --- a/index.html +++ b/index.html @@ -14,7 +14,7 @@ - + diff --git a/reference/api/bumpversion/aliases/index.html b/reference/api/bumpversion/aliases/index.html index f2e6f86..9a7a35d 100644 --- a/reference/api/bumpversion/aliases/index.html +++ b/reference/api/bumpversion/aliases/index.html @@ -16,7 +16,7 @@ - + @@ -2083,7 +2083,7 @@Bump My Version\u2019s purpose is to:
You can download and install the latest version of this software from the Python package index (PyPI) as follows:
pip install --upgrade bump-my-version\n
"},{"location":"CHANGELOG/","title":"Changelog","text":""},{"location":"CHANGELOG/#0281-2024-11-03","title":"0.28.1 (2024-11-03)","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 9fb0347
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.9 \u2192 v0.7.1
Compare the full difference.
"},{"location":"CHANGELOG/#new","title":"New","text":"Add Docker support and configure Dependabot for Docker updates. 0315db4
Introduce a Dockerfile for containerized environments and add a .dockerignore file to exclude unnecessary files. Also, update dependabot.yml to include daily checks for Docker image updates. - Add inputs
section in GHA workflow example. 813e7f5
Switch from ADD to COPY in Dockerfile. a5fc5c0
This change updates the Dockerfile to use the COPY instruction instead of ADD. COPY is preferred when only copying files because it is more explicit and simpler. - [pre-commit.ci] pre-commit autoupdate. 7c48f98
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.8 \u2192 v0.6.9
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_1","title":"Fixes","text":"Refactor and enhance error handling. c84bfa7
Updated subprocess calls to disable check, refined lint configurations, fixed type annotations and exceptions, and improved dictionary path validation.
Add HookError for failed hook execution with tests. 39fc233
Raise HookError when a hook script exits with a non-zero status. Modified logger to display warnings instead of debug messages in such scenarios. Added tests to ensure exceptions are raised for failed hooks.
[pre-commit.ci] pre-commit autoupdate. 130478d
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.5 \u2192 v0.6.7
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_2","title":"Fixes","text":"Fixed missing new version info in some hook environments. 24a9bdc
Introduce the new_version_env
function and update existing functions (get_setup_hook_env
and get_pre_commit_hook_env
) to include new version environment variables. Added new tests for verifying the inclusion of OS, SCM, current, and new version information in hook environments.
[pre-commit.ci] pre-commit autoupdate. d21d6df
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.2 \u2192 v0.6.4
[pre-commit.ci] pre-commit autoupdate. b6773ac
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.7 \u2192 v0.6.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_3","title":"Fixes","text":"Add hooks configuration fields. d6b24f0
Introduced setup_hooks
, pre_bump_hooks
, and post_bump_hooks
fields to configuration models. Updated corresponding test fixtures to verify these new fields. - Add current_tag field to scm_info. 304c599
Updated the scm_info structure to include a new field, current_tag, across various configuration files and source code. This ensures that the current tag is tracked and represented in the output formats correctly.
Enhance hook handling and testing across hook types. 49f1953
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.6 \u2192 v0.5.7
Changed the terminology for hooks. 049b470
Change pre-bump and post-bump to pre-commit and post-commit to better indicate their order of operations.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_4","title":"Fixes","text":"Fixed terminology in tests. 0338da2
Updated test parameter and assertion messages to use \u201cversion component\u201d instead of \u201cversion part\u201d for clarity and consistency. This change affects the test cases that detect bad or missing version inputs. - Fixed documentation layout. 57958ea
Fixed inconsistent terms in docstrings. dfdf23e
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_5","title":"Fixes","text":"Refactor version parsing in visualize function. 5f25300
Simplify the version parsing process by utilizing the raise_error parameter in the parse method, removing the need for a separate error check. This change ensures that parsing errors are immediately raised and handled cleanly within the visualize function. - Refactor and rename version_part
to versioning.version_config
. 5b90817
Moved version_part.py
to versioning/version_config.py
and updated all import statements accordingly. Enhanced error handling in VersionConfig
by adding raise_error
flag and relevant exception raising for invalid version strings. Refined tests to reflect these changes. - Fix version visualization and add verbose logging. ad46978
Raise an exception for unparsable versions and aggregate visualization output in a list before printing. Add a verbose logging option to the show_bump
command for detailed logging control.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_6","title":"Fixes","text":"Fix JSON serialization. d3f3022
Extended the default_encoder function to handle Path objects by converting them to their string representation. This ensures that Path objects can be properly serialized to JSON format.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_7","title":"Fixes","text":"Fixes repository path checks. ff3f72a
Checked for relative paths when determining if the file was part of the repo or not. - Fixed test to use globs. 72f9841
[pre-commit.ci] pre-commit autoupdate. 58cc73e
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.5 \u2192 v0.5.6
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_8","title":"Fixes","text":"Refactor error handling and improve logging in utils. 890b692
Extracted error formatting to a dedicated function and applied it across the codebase. Improved command path handling in add_path
and enhanced test coverage with necessary imports and logging configurations. - Fix dictionary merging in SCMInfo. 5fb5ef2
Replaced the bitwise OR operator with the update method for merging dictionaries for 3.8 support - Refactor SCM info retrieval and config file update checks. 500ecd3
Replaced ChainMap with MutableMapping in function signatures and types. Enhanced SCM info handling by splitting code into dedicated methods for commit and revision info retrieval. Added logic to prevent config file updates when the file is outside the repo and implemented corresponding test.
Add repository_root field and refactor subprocess handling. 25670d0
Introduced the repository_root
field to store the root path of the repository in the data classes. Refactored subprocess handling to use a new run_command
utility for improved readability and error handling consistency. Removed unnecessary dependency from .pre-commit-config.yaml
to streamline dependencies.
Simplify run_command return type. b91224e
Changed the return type of run_command from CompletedProcess[str] to CompletedProcess. This was done to remove unnecessary type specificity and ensure compatibility with different Python versions. The update maintains functionality and improves code readability. - [pre-commit.ci] pre-commit autoupdate. e0ba544
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.2 \u2192 v0.5.5
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_9","title":"Fixes","text":"Fix KeyError in TOML file handling. f3c328a
The code has been updated to handle KeyErrors when updating TOML files. If a KeyError is raised, it\u2019s now caught and managed depending on the file_change attributes \u2018ignore_missing_file\u2019 or \u2018ignore_missing_version\u2019. This aims to provide more robust handling of edge cases in TOML files. In addition, a new test case has been added to ensure current version is not required in the configuration.
Fixes #212
[pre-commit.ci] pre-commit autoupdate. 536c7b1
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.10 \u2192 v0.5.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_10","title":"Fixes","text":"Fixed tag version extraction. 67eea3d
The output of git describe
uses -
as a delimiter. Parsing tags caused splits in the parsing of version numbers.
This joins all the remaining parts of the git describe
with a -
. - Fixed pydoclint configuration. 0386073
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_11","title":"Fixes","text":"Refactor error handling in SCM and add error handling test. 7ca6356
This commit includes a new test in test_scm.py to verify the correct formatting and raising of subprocess errors in the SCM module. Additionally, the subprocess error handling has been refactored in the SCM module to include a new method, format_and_raise_error, for improved code readability and reusability.
[pre-commit.ci] pre-commit autoupdate. 60acc2d
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.9 \u2192 v0.4.10
Compare the full difference.
"},{"location":"CHANGELOG/#new_5","title":"New","text":"Add VersionNotFoundError test in test_bump.py. cb050a8
The code in test_bump.py file has been modified to include a test for VersionNotFoundError exception. This ensures that the implementation properly handles cases where a specified version could not be found. - Add test for no commit on modification error. 7527029
A test has been added to the bumpversion library to ensure that no commit and tag is made if there is an error modification. Specifically, the test checks the \u201cdo_bump\u201d function and asserts that \u201cmock_commit_and_tag\u201d and \u201cmock_update_config_file\u201d are not called under these conditions.
[pre-commit.ci] pre-commit autoupdate. 0e3a154
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.8 \u2192 v0.4.9
Improve error message for SCM command failures. 8f72f86
The error message for failures in the SCM command execution has been enhanced. Now it displays not only the command\u2019s return code but also the standard output and error, improving the debugging process.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_12","title":"Fixes","text":"Refactor valid_bumps and invalid_bumps to include_bumps and exclude_bumps. 2df57cc
The configuration parameters valid_bumps
and invalid_bumps
were renamed to include_bumps
and exclude_bumps
respectively. This new naming better denotes their function, and the changes were consistently applied across all related files and tests. Numerous fixture outputs were also updated to reflect these changes. - Fixed spelling in CODE_OF_CONDUCT.md. 254ea44
Add file filtering based on valid and invalid bumps. f9f7f96
This commit introduces the ability to filter files based on whether the specified bump type is valid or not. It adds valid_bumps
and invalid_bumps
lists in the file configurations and adjusts the bumping process to consider these configurations. Tests are updated to reflect these new handling of valid and invalid bumps. - Add new files to .gitignore. 34e4dc1
Several new file types have been added to .gitignore for ignoring during commits. These include \u2018.python-version\u2019, \u2018requirements-dev.lock\u2019, and \u2018requirements.lock\u2019 files. - Add valid_bumps and invalid_bumps to file configuration. 9458851
Updated the configuration file model to support valid_bumps and invalid_bumps. This feature provides control over which version section updates can trigger file changes. Adjusted various test fixtures and cleaned up tests to match these changes. Also, some updates were made to the documentation accordingly.
[pre-commit.ci] pre-commit autoupdate. e44f6af
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.4 \u2192 v0.4.8
Update documentation for clarification. 2224808
The changes made update the wording in the documentation to clarify the roles of include_bumps
and exclude_bumps
in the bump-my-version configuration. Additionally, unnecessary repetition was removed and overlapping examples were also corrected. - Update docs/reference/configuration.md. 7c801c0
co-authored-by: wkoot 3715211+wkoot@users.noreply.github.com
Compare the full difference.
"},{"location":"CHANGELOG/#new_7","title":"New","text":"Add extensive documentation for the \u2018show\u2019 subcommand. 91409d8
This commit adds extensive documentation for the show
subcommand in the program\u2019s reference. It also includes smaller updates and corrections to other parts of the documentation. An in-depth example usage of show
is added both to the dedicated show.md
file and in the function\u2019s docstring.
Compare the full difference.
"},{"location":"CHANGELOG/#other_11","title":"Other","text":"[pre-commit.ci] auto fixes from pre-commit.com hooks. 1b57c2b
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. e813eda
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.3 \u2192 v0.4.4
[pre-commit.ci] pre-commit autoupdate. 05a0dd6
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.2 \u2192 v0.4.3
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_13","title":"Fixes","text":"Fixed a bug in the glob tests. 1041fe9
Was not properly looking in the correct relative directories. - Fixed test for Windows glob paths. ea45c4c
Adds glob_exclude
file specification parameter. 420e3bd
User can prune the files resolved via the glob
parameter.
Fixes #184
[pre-commit.ci] pre-commit autoupdate. ce02aa7
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.1 \u2192 v0.4.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_14","title":"Fixes","text":"Fixed the indentation problem. ec3cd99
[pre-commit.ci] pre-commit autoupdate. e916f87
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.7 \u2192 v0.4.1
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_15","title":"Fixes","text":"Fixed the rendering of numeric version components. c522c75
[pre-commit.ci] pre-commit autoupdate. 9b09da8
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.5 \u2192 v0.3.7
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_16","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. f438bc6
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.4 \u2192 v0.3.5
Pre-commit: Discover typos with codespell. 2509fc7
Related to: * #168 - [pre-commit.ci] pre-commit autoupdate. be5cb79
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.3 \u2192 v0.3.4
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_17","title":"Fixes","text":"Added always_increment
attribute for parts. 53ee848
This is a requirement for CalVer to ensure they always increment with each bump, but it will work for any type. - Added CalVer function and formatting. 7a0e639
calver_format
attribute for CalVer parts.Compare the full difference.
"},{"location":"CHANGELOG/#fixes_18","title":"Fixes","text":"Fixed platform-dependent encoding. f8b4d65
encoding=\"utf-8\"
to all writes.[pre-commit.ci] pre-commit autoupdate. e92000a
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.2 \u2192 v0.3.3
Bump the github-actions group with 3 updates. a422c58
Bumps the github-actions group with 3 updates: actions/checkout, actions/setup-python and codecov/codecov-action.
Updates actions/checkout
from 3 to 4 - Release notes - Changelog - Commits
Updates actions/setup-python
from 4 to 5 - Release notes - Commits
Updates codecov/codecov-action
from 3 to 4 - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions
signed-off-by: dependabot[bot] support@github.com
Keep GitHub Actions up to date with GitHub\u2019s Dependabot. 2e55fa1
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_19","title":"Fixes","text":"Fixed bad options not returning an error code. e88f0a9
Fixes #153 - Fix issue on version.yaml. 7d14065
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_20","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. be1a568
updates: - github.com/astral-sh/ruff-pre-commit: v0.2.2 \u2192 v0.3.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_21","title":"Fixes","text":"Removes ability to call the CLI without subcommand. e56c944
BREAKING CHANGE: You must use bump-my-version bump
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_22","title":"Fixes","text":"Fixed \u2013ignore-missing-version and \u2013ignore-missing-files options. 7635873
The CLI options were defaulting to False
when missing. This overrode the configuration.
Fixes #140
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_23","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_24","title":"Fixes","text":"Fixed naming issue for docs. 2850aa7
Added how-to doc. 68643a9
[pre-commit.ci] pre-commit autoupdate. c495d3d
updates: - github.com/astral-sh/ruff-pre-commit: v0.2.1 \u2192 v0.2.2
Compare the full difference.
"},{"location":"CHANGELOG/#new_12","title":"New","text":"--ignore-missing-files
option to bump. fcfaac7ignore_missing_files
. b473a19Compare the full difference.
"},{"location":"CHANGELOG/#fixes_25","title":"Fixes","text":"Fix encoding when reading text. c03476a
Fixes #68
[pre-commit.ci] pre-commit autoupdate. 491b4aa
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.14 \u2192 v0.2.0
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_26","title":"Fixes","text":"Refactored VersionComponentConfig to VersionComponentSpec. b538308
More consistent with VersionSpec
[pre-commit.ci] pre-commit autoupdate. a2a3fe6
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.11 \u2192 v0.1.14
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_27","title":"Fixes","text":"Refactored serialization. 0ac2cd8
Refactored verioning models. 88e7f71
depends_on
version component configurationdepends_on
is required for PEP440 versioningCompare the full difference.
"},{"location":"CHANGELOG/#fixes_28","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_29","title":"Fixes","text":"Refactored the create subcommand. f529d28
Added show-bump
subcommand. 0bbd814
bump
commandCompare the full difference.
"},{"location":"CHANGELOG/#fixes_30","title":"Fixes","text":"Fixed extra whitespace added when updating pyproject.toml. 839f17f
get_nested_value
and set_nested_value
as replacements for dotted-notation.[pre-commit.ci] pre-commit autoupdate. ee4d2f3
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.9 \u2192 v0.1.11
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_31","title":"Fixes","text":"Fixed empty string replacement bug. d9965ab
Only a missing replacement value will trigger one of the fallback options.
Fixes #117
Compare the full difference.
"},{"location":"CHANGELOG/#new_15","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. 2e9a400
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.7 \u2192 v0.1.9
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_32","title":"Fixes","text":"Fixed testing automation. 19215f1
--no-tag
flagCompare the full difference.
"},{"location":"CHANGELOG/#fixes_33","title":"Fixes","text":"Fix miscast of current_version. b8ea252
Fixes #99
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_34","title":"Fixes","text":"Fixed regression in config update. 2bbbd74
Fixes #108
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_35","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_36","title":"Fixes","text":"Changed default regex CLI value to None. 93191f3
Fixes #64
The default value of False was overriding other values.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_37","title":"Fixes","text":"Fixed regression regarding multiple changes in one file. e7a7629
Changed the method of marking changes from a dict keyed by the file name to a list of FileChanges.
FileChanges encapsulate a single change to a file. - Refactored logging to provide indented output. 4e68214
Refactored FileConfig to FileChange. 249a999
This better describes what the class does: describe a file change.
Also moved get_search_pattern
to the class, since it is specific to each instance - Refactored config file management. a4c90b2
Moved the INI format stuff into files_legacy.py - Fixes generate-requirements.sh to upgrade. 121ef69
Changed the management of file changes. 909396d
File changes are hashable to weed out duplication. - Removed some commented lines. 89686b8
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_38","title":"Fixes","text":"Fixed issue with tag name. e218264
Fixes #74
current_version and tag_name now do not need to match exactly - Fixed logic in auto bump workflow. 909a53f
Fixes https://github.com/callowayproject/bump-my-version/issues/85. 97049e0
HG returns the tags in the order they were created so we want the last one in the list - Fixed autoversioning. a308a35
Added key_path to FileConfig. e160b40
filename
, glob
, and key_path
[pre-commit.ci] auto fixes from pre-commit.com hooks. 8188a42
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 4c81ad4
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.3 \u2192 v0.1.5
[pre-commit.ci] pre-commit autoupdate. 7109d70
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.3 \u2192 v0.1.6
Refactored configuration file updating. e407974
TOML files are parsed, specific values are updated, and re-written to avoid updating the wrong data.
It uses a two-way parser, so all formatting and comments are maintained.
INI-type configuration files use the old way, since that format is deprecated.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_39","title":"Fixes","text":"Fix dev versioning. 1eed99b
Add -h for help option. fda71b0
Fixes #67
Drop Python3.7 as compatible version. 890edc8
Since this is no longer tested, it\u2019s safer to start at 3.8. - [pre-commit.ci] auto fixes from pre-commit.com hooks. fbcef03
for more information, see https://pre-commit.ci - Recommend calling \u2018bump-my-version\u2019 instead of \u2018bumpversion\u2019. 9fb1a1d
[pre-commit.ci] pre-commit autoupdate. e2579d6
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.290 \u2192 v0.0.292
[pre-commit.ci] pre-commit autoupdate. e21fdd9
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.290 \u2192 v0.1.1
[pre-commit.ci] pre-commit autoupdate. 7e5d1bc
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.290 \u2192 v0.1.3
Changed the default regex search to non-regex. 0034716
Fixes #59
Compare the full difference.
"},{"location":"CHANGELOG/#other_27","title":"Other","text":"[pre-commit.ci] pre-commit autoupdate. 4a3d046
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.285 \u2192 v0.0.290
Compare the full difference.
"},{"location":"CHANGELOG/#updates_19","title":"Updates","text":"Refactored file resolution, inclusion, and exclusion. 646af54
resolved_filemap
propertyfiles_to_modify
propertyCompare the full difference.
"},{"location":"CHANGELOG/#fixes_40","title":"Fixes","text":"Fixed file configuration overrides. c1ef3b2
Fixes #55
The file config was ignoring falsey values when constructing the dict.
It now ignores None
values. - Fixed documentation regarding regex config. cd71a1a
[pre-commit.ci] pre-commit autoupdate. 7c38c40
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.284 \u2192 v0.0.285
[pre-commit.ci] pre-commit autoupdate. c30bd12
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.282 \u2192 v0.0.284
[pre-commit.ci] pre-commit autoupdate. 95c89fb
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.281 \u2192 v0.0.282
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_41","title":"Fixes","text":"Fixed modified context when committing. 130bbe0
Compare the full difference.
"},{"location":"CHANGELOG/#other_29","title":"Other","text":"[pre-commit.ci] auto fixes from pre-commit.com hooks. 4b457d0
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. adb7e4c
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.277 \u2192 v0.0.281
Remove pygments_style
from docsrc/conf.py. 32798a9
The theme defaults, subjectively, look better.
Compare the full difference.
"},{"location":"CHANGELOG/#new_21","title":"New","text":"Added configuration and command-line no_regex
option. a295a32
no_regex
--no-regex
flag added for bump
and replace
sub-commandsCompare the full difference.
"},{"location":"CHANGELOG/#new_22","title":"New","text":"--ignore-missing-version
flag to bump
and replace
. a5bd008Added ignore-missing-version
configuration. 45c85be
False
--list
option will go bye-bye in 1.0bumpversion
without a subcomand will leave in 1.0Compare the full difference.
"},{"location":"CHANGELOG/#fixes_42","title":"Fixes","text":"Fix search and replace options for replace. 781e8d8
--search
and --replace
options now completely override any other search and replace logic.Fixes #34
[pre-commit.ci] pre-commit autoupdate. 531738d
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.276 \u2192 v0.0.277
[pre-commit.ci] pre-commit autoupdate. 61e6747
updates: - https://github.com/charliermarsh/ruff-pre-commit \u2192 https://github.com/astral-sh/ruff-pre-commit
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_43","title":"Fixes","text":"Fixed typing issue. bfe5306
ClassVar[List[str]]
_TEST_USABLE_COMMAND
, _COMMIT_COMMAND
, and _ALL_TAGS_COMMAND
affectedAdded replace subcommand. 8722a0f
bump
butbumpversion show new_version --increment <versionpart>
to see what the new version would beshort_branch_name
to version rendering context. 7f7e50cshort_branch_name
is the branch name, lower case, containing only a-z and 0-9, and truncated to 20 characters.Fixes #28
[pre-commit.ci] auto fixes from pre-commit.com hooks. 5e6f566
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. f1acd35
updates: - github.com/charliermarsh/ruff-pre-commit: v0.0.272 \u2192 v0.0.275
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_44","title":"Fixes","text":"Fixed --help
and bump
invocations. 9d965e5
--help
works for individual sub-commands, but not for the commandbump
now works and fixed teststomlkit.parse()
returns a TOMLDocument
.unwrap()
converts it into a dict
branch_name
to SCM information. 173be1aAdds --increment
option to show
subcommand. b01fffc
new_version
to the available output.show
subcommand. 9bce887--list
optionChanges bump-my-version into subcommands. 31ffbcf
bump-my-version
forwards command to bump-my-version bump
subcommand--help
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_45","title":"Fixes","text":"Fixes reporting the wrong version missing in a file. efb04e9
current_version
for each file being modified.[pre-commit.ci] auto fixes from pre-commit.com hooks. 5476cdf
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 6e500c2
updates: - github.com/charliermarsh/ruff-pre-commit: v0.0.270 \u2192 v0.0.272
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_46","title":"Fixes","text":"Fixed issue with formatting. da7544f
There is an underlying edge case where the deriving previous environment variables with multiple ways of formatting version numbers will fail.
Added documentation for replacing strings in different files. 893ec03
Fixes #6
Made VERSION_PART
optional. f236b7d
VERSION_PART
is detected from the arguments based on the configurationChanged exception type raised when bad version part is detected. 1e3ebc5
Fixes #7
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_47","title":"Fixes","text":"Fixes release.yaml. 01870d5
Outputs the notes to a file instead of an environment variable.
[pre-commit.ci] auto fixes from pre-commit.com hooks. 266002f
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. edc444f
updates: - github.com/charliermarsh/ruff-pre-commit: v0.0.261 \u2192 v0.0.270
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_48","title":"Fixes","text":"Fixed vague commit and tagging info. 4fb5158
[pre-commit.ci] pre-commit autoupdate. d626f7d
updates: - https://github.com/python/black \u2192 https://github.com/psf/black
Changed the version serialization. c529452
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_49","title":"Fixes","text":"Fixes issue when new version equals current version. 64b0de3
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_50","title":"Fixes","text":"Fixed issue with windows testing. b8abc44
Fixed configuration file detection. fbf85c2
Doesn\u2019t just stop when it finds one, it checks for the existence of the header. - Fixed logging output and output in general. 0aea9dc
Added new workflows. a9cac5b
Added PYTHONUTF8 mode. 91a73e2
Added files for coverage to ignore. cfbba08
Updated workflows. 857835d
Changed BaseVCS to SourceCodeManager. 11c5609
Just for consistency. - Modified the group command back to a single command. 6d4179b
Will eventually change to a group command, but later.
First off, thanks for taking the time to contribute! \u2764\ufe0f
All types of contributions are encouraged and valued. See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it much easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. \ud83c\udf89
If you like the project but don\u2019t have time to contribute, that\u2019s fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: - Star the project - Tweet about it - Refer to this project in your project\u2019s readme - Mention the project at local meetups and tell your friends/colleagues
"},{"location":"CONTRIBUTING/#table-of-contents","title":"Table of Contents","text":"This project and everyone participating in it are governed by the Bump My Version Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to coreyoordt@gmail.com.
"},{"location":"CONTRIBUTING/#i-have-a-question","title":"I Have a Question","text":"If you want to ask a question, we assume that you have read the available Documentation.
Before you ask a question, it is best to search for existing Issues that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
If you then still feel the need to ask a question and need clarification, we recommend the following:
We will then take care of the issue as soon as possible.
"},{"location":"CONTRIBUTING/#reporting-bugs","title":"Reporting Bugs","text":""},{"location":"CONTRIBUTING/#before-submitting-a-bug-report","title":"Before Submitting a Bug Report","text":"A good bug report shouldn\u2019t leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information, and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.
You must never report security-related issues, vulnerabilities, or bugs that include sensitive information to the issue tracker or elsewhere in public. Instead, sensitive bugs must be sent by email to coreyoordt@gmail.com.
We use GitHub issues to track bugs and errors. If you run into an issue with the project:
Once it\u2019s filed:
This section guides you through submitting an enhancement suggestion for Bump My Version, including completely new features and minor improvements to existing functionality. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
"},{"location":"CONTRIBUTING/#before-submitting-an-enhancement","title":"Before Submitting an Enhancement","text":"Enhancement suggestions are tracked as GitHub issues.
When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.
"},{"location":"CONTRIBUTING/#setup","title":"Setup","text":"There are several ways to create an isolated Python development environment. This is the default method.
Run the following in a terminal:
# Clone the repository\ngit clone https://github.com/callowayproject/bump-my-version.git\n\n# Enter the repository\ncd bump-my-version\n\n# Create, then activate a virtual environment\npython -m venv env\nsource env/bin/activate\n\n# Install the development requirements\npython -m pip install -r requirements/dev.txt\n
"},{"location":"CONTRIBUTING/#run-tests","title":"Run tests","text":"Once setup, you should be able to run tests:
pytest\n
"},{"location":"CONTRIBUTING/#install-pre-commit-hooks","title":"Install Pre-commit Hooks","text":"Pre-commit hooks are scripts that run every time you make a commit. If any of the scripts fail, it stops the commit. You can see a listing of the checks in the .pre-commit-config.yaml
file.
pre-commit install\n
"},{"location":"CONTRIBUTING/#improving-the-documentation","title":"Improving The Documentation","text":"Please, please help us here.
"},{"location":"CONTRIBUTING/#styleguides","title":"Styleguides","text":""},{"location":"CONTRIBUTING/#coding-style","title":"Coding Style","text":"All of the basic coding styles are configured into tools for fixing and checking them. Pre-commit is used to automate the process.
"},{"location":"CONTRIBUTING/#commit-messages","title":"Commit Messages","text":"Commit messages are used to generate the change log.
New changes
Commit messages are categorized as \u201cnew\u201d if the commit message starts with:
For example: Added this cool new feature
or New document type added
.
Updates
Commit messages are categorized as \u201cupdates\u201d if the commit message starts with:
For example: Modified the taxonomy schema
or Improves performance by 419%
Fixes
Commit messages are categorizes as \u201cfixes\u201d if the commit message starts with:
For example: Fixes bug #123
Other
All other commit messages are categorized as \u201cother.\u201d
Ignoring commit messages
To have the change log generator ignore this commit, add to the summary line:
@minor
!minor
@cosmetic
!cosmetic
@refactor
!refactor
@wip
!wip
If you would like to be a maintainer, reach out to coreyoordt@gmail.com.
"},{"location":"CONTRIBUTING/#attribution","title":"Attribution","text":"This guide is based on the contributing-gen. Make your own!
"},{"location":"explanation/","title":"Index","text":"There are four main concepts in Bump My Version:
The predecessor to Bump My Version, bumpversion, was designed to have the configuration file optional. All configuration values could be specified on the command line. This only worked in the simplest of version schemes.
While Bump My Version can do many things without a configuration file, it is designed to have a configuration file. The configuration file is required to specify the version scheme. The configuration file also specifies the files to change and how to change them.
"},{"location":"explanation/mental-model/#version-handling","title":"Version handling","text":"Bump My Version abstracts the version handling into a few concepts:
A version spec defines the rules for incrementing a version.
A version component spec defines how a single part of a version spec, such as major
, minor
, or patch
, works. It defines the types of values, how to increment the component, and how to reset it.
A version parser is a regular expression used in several ways. Its named capture groups define the possible components in a version spec and the order in which they appear. It also parses a version string into version component names and their values.
A version is the concrete representation of a version spec. It is a mapping of version component names to version components.
A version component is the concrete representation of a version component spec. It is a version component spec with a specific value.
A version serialization format is a list of format strings used to serialize a version into a string.
"},{"location":"explanation/mental-model/#how-a-version-spec-is-generated","title":"How a version spec is generated","text":"How a configuration file is used to generate a version spec.The most important part of the configuration file is the version parser. It defines the structure of the version spec.
If the configuration file contains a version component spec that matches a named capture group in the version parser, then that version component spec is used in the version spec. The yellow and green named capture groups in the diagram demonstrate this.
If the configuration file does not contain a version component spec that matches a named capture group in the version parser, then a default version component spec is used. The blue named capture group in the diagram demonstrates this.
The component dependency graph determines the order in which the version components are incremented and reset. For example, in the diagram, the patch component depends on the minor component, which depends on the major
component. Therefore, when the major
component is incremented, the minor
component is reset, which cascades to the patch
component.
The version spec has a create_version
method that takes a mapping of version component names to values.
Each version component spec has a create_component
method that takes a value. The create_version
method calls the create_component
method for each version component spec in the version spec with the value from the mapping.
The create_component
assembles its version spec_ with the version components to create a version.
Optional value rule. Version component specs can define an optional value. For example, numeric components have 0
as an optional value. Optional values may be omitted from the serialization as long as all dependent components also have optional values.
Required value rule. Version component specs is required if its value or the value of any of its dependent components is not optional.
A valid serialization contains all the required components in the version spec based on the required value rule.
An invalid serialization does not contain all the required components in the version spec based on the required value rule.
The optimal serialization is the valid serialization that uses the fewest components.
The serialize
method of the version spec returns either the optimal serialization or the first invalid serialization.
No optional values
In this example, the major
component is 1
, the minor
component is 2
, and patch
component is 3
. Since none of the values are optional (0
), only one serialization format is valid. This one valid format is the optimal format.
One optional value
A version with values major=1, minor=2, and patch=0 has two valid serializations. The optimal serialization is the one that uses the fewest components. 1.2
in this example.
Two optional values
A version with values major=1, minor=0, and patch=0 has three valid serializations. The optimal serialization is the one that uses the fewest components. 1
in this example.
No valid serialization options
A version with values major=1, minor=2, and patch=3 has no valid serializations in this example. The serialize
method returns the first invalid serialization.
The main purpose of the show
subcommand is to provide access to configuration data via scripts.
The configuration object is a dict
containing nested data structures. The arguments and options of this command relate to extracting data from the configuration object and presenting the extracted data.
The positional arguments determine the data shown. If nothing or all
is passed, the entire configuration is shown.
Positional arguments are specified using a format like Django variable resolution.
Examples:
a.b
specifies the \u201cb\u201d key in the nested dictionaries: {\"a\": {\"b\": \"value\"}}
a.3
specifies the 4th item (the first is 0) of the list at key \u201ca\u201d: {\"a\": [\"no\", \"nay\", \"nyet\", \"value\"]}
If only one positional argument is passed, the default format only shows its value. If no positional arguments, several positional arguments, or all
is passed, the output from pprint.pprint
is shown.
This makes getting the current version easy:
$ bump-my-version show current_version\n1.0.1\n
You can request the output be formatted as YAML or JSON:
$ bump-my-version show --format yaml current_version\ncurrent_version: \"1.0.1\"\n$ bump-my-version show --format json current_version\n{\n \"current_version\": \"1.0.1\"\n}\n
"},{"location":"explanation/show-subcommand/#including-the-incremented-version-before-bumping","title":"Including the incremented version before bumping","text":"Your workflow might want to know the new version before you actually do the bumping. The --increment
or -i
option accepts a version part to bump and adds a new_version
key into the configuration.
$ bump-my-version --increment patch show\n1.0.2\n$ bump-my-version --increment minor show\n1.1.0\n$ bump-my-version --increment major show\n2.0.0\n
"},{"location":"explanation/version-parts/","title":"Version components","text":"A version configuration consists of the following:
A version string consists of one or more parts; e.g., version 1.0.2
has three parts, separated by a dot (.
) character.
The names of these parts are defined in the named groups within the parse
regular expression. The default configuration calls them major, minor, and patch.
The serialize
configuration value is a list of default formats. You have the option for multiple serialization formats to omit optional values. For example, the following configuration:
serialize = [\n \"{major}.{minor}.{patch}\",\n \"{major}.{minor}\",\n]\n
Bump-my-version will serialize using the first format if the patch
value is not 0
. If the patch
value is 0
, Bump My Version will use the second format.
A version part configuration consists of the following:
There are two incrementing functions: numeric and value. The numeric function uses integer values and returns the next integer value. The values function uses a sequence of values and returns the next value until finished.
By default, parts use the numeric function starting at 0.
You can configure a part using the values function by providing a list of values in the version part\u2019s configuration. For example, for the release_name
part:
[tool.bumpversion.parts.release_name]\nvalues = [\n \"witty-warthog\", \n \"ridiculous-rat\", \n \"marvelous-mantis\",\n]\n
"},{"location":"explanation/version-parts/#optional-values","title":"Optional values","text":"By default, the first value of a version part is considered optional. An optional value may be omitted from the version serialization. Using the example from above:
serialize = [\n \"{major}.{minor}.{patch}\",\n \"{major}.{minor}\",\n]\n
Version 1.4.0
is rendered as 1.4
since the patch
is 0
; as the first value, it is optional.
Optional values are helpful for non-numeric version parts that indicate development stages, such as alpha or beta.
Example:
[tool.bumpversion]\ncurrent_version = \"1.0.0\"\nparse = \"\"\"(?x)\n (?P<major>[0-9]+)\n \\\\.(?P<minor>[0-9]+)\n \\\\.(?P<patch>[0-9]+)\n (?:\n -(?P<pre_label>alpha|beta|stable)\n (?:-(?P<pre_n>[0-9]+))?\n )?\n\"\"\"\nserialize = [\n \"{major}.{minor}.{patch}-{pre_label}-{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\n\n[tool.bumpversion.parts.pre_label]\noptional_value = \"stable\"\nvalues =[\n \"alpha\",\n \"beta\",\n \"stable\",\n]\n
Bumping the patch
part of version 1.0.0
would change the version to 1.0.1-alpha-0
. Bumping the pre_label
part would change the version to 1.0.1-beta-0
. Bumping the pre_label
part again would change the version to 1.0.1
. The stable-0
is not serialized because both stable
and 0
are optional.
You can specify the starting number with the first_value configuration for numeric version parts.
For example, if we added the following to the above configuration:
[tool.bumpversion.parts.pre_n]\nfirst_value = \"1\"\n
Bumping the patch
value of version 1.0.0
would change the version to 1.0.1-alpha-1
instead of 1.0.1-alpha-0
.
In the pattern {major}.{minor}.{patch}-{pre_label}-{pre_n}
, each version part resets to its first value when the element preceding it changes. All these version parts are dependent.
You can include a value that incremented independently from the other parts, such as a build
part: {major}.{minor}.{patch}-{pre_label}-{pre_n}+{build}
\u2014in the configuration for that part, set independent=true
.
[tool.bumpversion.parts.build]\nindependent = true\n
"},{"location":"explanation/version-parts/#reference","title":"Reference","text":"In files that have multiple version strings, Bump My Version may find the wrong string and replace it. Given this requirements.txt
for MyProject
:
Django>=1.5.6,<1.6\nMyProject==1.5.6\n
The default search and replace templates will replace the wrong text. Instead of changing MyProject
\u2019s version from 1.5.6
to 1.6.0
, it changes Django
\u2019s version:
Django>=1.6.0,<1.6\nMyProject==1.5.6\n
Providing search and replace templates for the requirements.txt
file will avoid this.
This .bumpversion.toml
will ensure only the line containing MyProject
will be changed:
[tool.bumpversion]\ncurrent_version = \"1.5.6\"\n\n[[tool.bumpversion.files]]\nfilename = \"requirements.txt\"\nsearch = \"MyProject=={current_version}\"\nreplace = \"MyProject=={new_version}\"\n
If the string to be replaced includes literal quotes, the search and replace patterns must include them to match. Given the file version.sh
:
MY_VERSION=\"1.2.3\"\n
Then the following search and replace patterns (including quotes) would be required:
[[tool.bumpversion.files]]\nfilename = \"version.sh\"\nsearch = \"MY_VERSION=\\\"{current_version}\\\"\"\nreplace = \"MY_VERSION=\\\"{new_version}\\\"\"\n
"},{"location":"howtos/calver/","title":"Using Calendar Versioning (CalVer)","text":"Calendar Versioning (CalVer) is a versioning scheme that uses a date-based version number.
For this example, we will use the following format: YYYY.MM.DD.patch
. It will yield numbers like:
2022.2.1
for the first patch of February 1, 20222022.2.1.1
for the second patch of February 1, 2022[tool.bumpversion]\ncurrent_version = \"2024.3.1.4\"\nparse = \"\"\"(?x) # Verbose mode\n (?P<release> # The release part\n (?:[1-9][0-9]{3})\\\\. # YYYY.\n (?:1[0-2]|[1-9])\\\\. # MM.\n (?:3[0-1]|[1-2][0-9]|[1-9]) # DD\n )\n (?:\\\\.(?P<patch>\\\\d+))? # .patch, optional\n\"\"\"\nserialize = [\"{release}.{patch}\", \"{release}\"]\n\n[tool.bumpversion.parts.release]\ncalver_format = \"{YYYY}.{MM}.{DD}\"\n
You can look up the regular expressions for the CalVer format in the CalVer reference.
"},{"location":"howtos/calver/#expected-behavior","title":"Expected behavior","text":"always_increment
by default.always_increment
are incremented first.always_increment
component\u2019s value changed, its dependent components are marked for reset to their default values.When you bump the calendar version, the patch is reset to 0 even if the release did not change.
Bumping the release resets patch$ date -I \n2024-03-1\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.1\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.1.5\n
The next day:
Bumping the release resets patch, the next day$ date -I \n2024-03-2\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.2\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.2\n
"},{"location":"howtos/calver/#the-result-of-a-bump-to-patch-depends-on-the-date","title":"The result of a bump to patch depends on the date","text":"Calendar Versioned parts are updated with every bump, regardless of the part being bumped. If you are bumping the version within the same time period (in this example, the same day), the release
part will not change. So bumping the patch
part will increment the patch
part only.
$ date -I \n2024-03-1\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.1\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.1.5\n
However, if you bump the version on the next day, the release
part will also be updated.
$ date -I \n2024-03-2\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.2\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.2\n
"},{"location":"howtos/custom-version-formats-by-file/","title":"Custom version formats in different files","text":"You can use file configurations to replace the version in multiple files, even if each file has the version formatted differently.
In a module-aware Go project, when you create a major version of your module beyond v1
, your module name must include the major version number (e.g., github.com/myorg/myproject/v2
). However, you also have the full version in a YAML file named release-channels.yaml
.
go.mod
file:
module github.com/myorg/myproject/v2\n\ngo 1.12\n\nrequire (\n ...\n)\n
release-channels.yaml
file:
stable: \"v2.21.4\"\n
You can use Bump My Version to maintain the major version number within the go.mod
file by using the parse
and serialize
options, as in this example:
.bumpversion.toml
file:
[tool.bumpversion]\ncurrent_version = \"2.21.4\"\n\n[[tool.bumpversion.files]]\nfilename = \"go.mod\"\nparse = \"(?P<major>\\\\d+)\"\nserialize = \"{major}\"\nsearch = \"module github.com/myorg/myproject/v{current_version}\"\nreplace = \"module github.com/myorg/myproject/v{new_version}\"\n\n[[tool.bumpversion.files]]\nfilename = \"release-channels.yaml\"\n
While all the version bumps are minor
or patch
, the go.mod
file doesn\u2019t change, while the release-channels.yaml
file will. As soon as you do a major
version bump, the go.mod
file now contains this module directive:
module github.com/myorg/myproject/v3\n
"},{"location":"howtos/multiple-replacements/","title":"Multiple replacements within the same file","text":"To make several replacements in the same file, you must configure multiple [[tool.bumpversion.files]]
sections for the same file with different configuration options.
In this example, the changelog is generated before the version bump. It uses Unreleased
as the heading and includes a link to GitHub to compare this version (HEAD
) with the previous version.
To change Unreleased
to the current version, we have an entry with search
set to Unreleased
. The default replace
value is {new_version}
, so changing it is unnecessary.
To change the link, another entry has its search
set to {current_version}...HEAD
and the replace
set to {current_version}...{new_version}
.
[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"Unreleased\"\n\n[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"{current_version}...HEAD\"\nreplace = \"{current_version}...{new_version}\"\n
"},{"location":"howtos/nav/","title":"Nav","text":"Many times when bumping a version, you will also want to update a date in a file. This is a common use case for changelogs, but it could be any file that contains a date. In this example, we have an __init__.py
that looks like this:
__date__ = '2022-12-19'\n__version__ = '0.4.0'\n
The desired outcome is to update the date to the current date. For example, if today is February 23, 2024, the init.py file should look like this after a minor
bump:
__date__ = '2024-02-23'\n__version__ = '0.5.0'\n
"},{"location":"howtos/update-a-date/#setting-up-the-file-configurations","title":"Setting up the file configurations","text":"We need Bump My Version to update the __init__.py
file twice: once for the version and once for the date. Here is the necessary configuration:
[[tool.bumpversion.files]]\nfilename = '__init__.py'\nsearch = \"__date__ = '\\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}'\"\nreplace = \"__date__ = '{now:%Y-%m-%d}'\"\nregex = true\n\n[[tool.bumpversion.files]]\nfilename = '__init__.py'\n
"},{"location":"reference/","title":"Index","text":"The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to define the version format in the calver_format
configuration options. Formatting codes, surrounded by { }
can be combined to create a custom version format. For example, the format YYYY.MM.DD
can be defined as \"{YYYY}.{MM}.{DD}\"
.
YYYY
2000, 2001, \u2026, 2099 Full year YY
0, 1, 2, \u2026, 99 Short year as integer 0Y
00, 01, 02, \u2026, 99 Short Year, zero-padded MMM
Jan, Feb, jan, f\u00e9v Month abbreviation, locale-based MM
1, 2, \u2026, 12 Month as integer 0M
01, 02, \u2026, 12 Month, zero-padded DD
1, 2, \u2026, 31 Day of month as integer 0D
01, 02, \u2026, 31 Day of month, zero-padded JJJ
1, 2, 3, \u2026, 366 Day of year as integer 00J
001, 002, \u2026, 366 Day of year, zero-padded Q
1, 2, 3, 4 Quarter WW
0, 1, 2, \u2026, 53 Week number, Monday is first day 0W
00, 01, 02, \u2026, 53 Week number, Monday is first day, zero-padded UU
0, 1, 2, \u2026, 53 Week number, Sunday is first day 0U
00, 01, 02, \u2026, 53 Week number, Sunday is first day, zero-padded VV
1, 2, \u2026, 53 ISO 8601 week number as integer 0V
01, 02, \u2026, 53 ISO 8601 week number, zero-padded GGGG
2000, 2001, \u2026, 2099 ISO 8601 week-based year GG
0, 1, 2, \u2026, 99 ISO 8601 short week-based year as integer 0G
01, 02, \u2026, 99 ISO 8601 short week-based year, zero-padded Example configuration[tool.bumpversion.parts.release]\ncalver_format = \"{YYYY}.{MM}.{DD}\"\n
"},{"location":"reference/calver_reference/#parsing-calver-versions","title":"Parsing CalVer versions","text":"Using the following chart, we can set up the version parsing:
Code RegexYYYY
(?:[1-9][0-9]{3})
YY
(?:[1-9][0-9]?)
0Y
(?:[0-9]{2})
MMM
See below MM
(?:1[0-2]\\|[1-9])
0M
(?:1[0-2]\\|0[1-9])
DD
(?:3[0-1]\\|[1-2][0-9]\\|[1-9])
0D
(?:3[0-1]\\|[1-2][0-9]\\|0[1-9])
JJJ
(?:36[0-6]\\|3[0-5][0-9]\\|[1-2][0-9][0-9]\\|[1-9][0-9]\\|[1-9])
00J
(?:36[0-6]\\|3[0-5][0-9]\\|[1-2][0-9][0-9]\\|0[1-9][0-9]\\|00[1-9])
Q
(?:[1-4])
WW
(?:5[0-3]\\|[1-4][0-9]\\|[0-9])
0W
(?:5[0-3]\\|[0-4][0-9])
UU
(?:5[0-3]\\|[1-4][0-9]\\|[0-9])
0U
(?:5[0-3]\\|[0-4][0-9])
VV
(?:5[0-3]\\|[1-4][0-9]\\|[1-9])
0V
(?:5[0-3]\\|[1-4][0-9]\\|0[1-9])
GGGG
(?:[1-9][0-9]{3})
GG
(?:[0-9][0-9]?)
0G
(?:[0-9]{2})
Month abbreviations
The month abbreviation is locale-based. Here are some examples:
(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
for English
(?:jan|f\u00e9v|mar|avr|mai|jui|jui|ao\u00fb|sep|oct|nov|d\u00e9c)
for French
You can use these regular expressions to parse CalVer versions in your project. For example, the following parse
configuration can be used to parse a version string in the format YYYY.MM.DD
as the release
part of the version string:
[tool.bumpversion]\nparse = \"\"\"(?x) # Verbose mode\n (?P<release>\n (?:[1-9][0-9]{3})\\\\. # YYYY.\n (?:1[0-2]|[1-9])\\\\. # MM.\n (?:3[0-1]|[1-2][0-9]|[1-9]) # DD\n )\n\"\"\"\n
"},{"location":"reference/cli/","title":"CLI Reference","text":""},{"location":"reference/cli/#bump-my-version","title":"bump-my-version","text":"Version bump your Python project.
Usage:
bump-my-version [OPTIONS] COMMAND [ARGS]...\n
Options:
Name Type Description Default--version
boolean Show the version and exit. False
--help
boolean Show this message and exit. False
Subcommands
Change the version.
ARGS may contain any of the following:
VERSION_PART is the part of the version to increase, e.g. minor
. Valid values include those given in the --serialize
/ --parse
option.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
Usage:
bump-my-version bump [OPTIONS] [ARGS]...\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None -v
, --verbose
integer range (0
and above) Print verbose logging to stderr. Can specify several times for more verbosity. 0
--allow-dirty
/ --no-allow-dirty
boolean Don\u2019t abort if working directory is dirty, or explicitly abort if dirty. None --current-version
text Version that needs to be updated None --new-version
text New version that should be in the files None --parse
text Regex parsing the version string None --serialize
text How to format what is parsed back to a version None --search
text Template for complete string to search None --replace
text Template for complete string to replace None --regex
/ --no-regex
boolean Treat the search parameter as a regular expression or explicitly do not treat it as a regular expression. None --no-configured-files
boolean Only replace the version in files specified on the command line, ignoring the files from the configuration file. False
--ignore-missing-files
/ --no-ignore-missing-files
boolean Ignore any missing files when searching and replacing in files. None --ignore-missing-version
/ --no-ignore-missing-version
boolean Ignore any Version Not Found errors when searching and replacing in files. None --dry-run
, -n
boolean Don\u2019t write any files, just pretend. False
--commit
/ --no-commit
boolean Commit to version control None --tag
/ --no-tag
boolean Create a tag in version control None --sign-tags
/ --no-sign-tags
boolean Sign tags if created None --tag-name
text Tag name (only works with \u2013tag) None --tag-message
text Tag message None -m
, --message
text Commit message None --commit-args
text Extra arguments to commit command None --help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-replace","title":"bump-my-version replace","text":"Replace the version in files.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
Usage:
bump-my-version replace [OPTIONS] [FILES]...\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None -v
, --verbose
integer range (0
and above) Print verbose logging to stderr. Can specify several times for more verbosity. 0
--allow-dirty
/ --no-allow-dirty
boolean Don\u2019t abort if working directory is dirty, or explicitly abort if dirty. None --current-version
text Version that needs to be updated None --new-version
text New version that should be in the files. If not specified, it will be None. None --parse
text Regex parsing the version string None --serialize
text How to format what is parsed back to a version None --search
text Template for complete string to search None --replace
text Template for complete string to replace None --regex
/ --no-regex
boolean Treat the search parameter as a regular expression or explicitly do not treat it as a regular expression. False
--no-configured-files
boolean Only replace the version in files specified on the command line, ignoring the files from the configuration file. False
--ignore-missing-version
boolean Ignore any Version Not Found errors when searching and replacing in files. False
--ignore-missing-files
boolean Ignore any missing files when searching and replacing in files. False
--dry-run
, -n
boolean Don\u2019t write any files, just pretend. False
--help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-sample-config","title":"bump-my-version sample-config","text":"Print a sample configuration file.
Usage:
bump-my-version sample-config [OPTIONS]\n
Options:
Name Type Description Default--prompt
/ --no-prompt
boolean Ask the user questions about the configuration. True
--destination
choice (stdout
| .bumpversion.toml
| pyproject.toml
) Where to write the sample configuration. stdout
--help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-show","title":"bump-my-version show","text":"Show current configuration information.
ARGS may contain one or more configuration attributes. For example:
bump-my-version show current_version
bump-my-version show files.0.filename
bump-my-version show scm_info.branch_name
bump-my-version show current_version scm_info.distance_to_latest_tag
Usage:
bump-my-version show [OPTIONS] [ARGS]...\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None -f
, --format
choice (default
| yaml
| json
) Specify the output format. default
-i
, --increment
text Increment the version component and add new_version
to the configuration. None --help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-show-bump","title":"bump-my-version show-bump","text":"Show the possible versions resulting from the bump subcommand.
Usage:
bump-my-version show-bump [OPTIONS] [VERSION]\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None --ascii
boolean Use ASCII characters only. False
-v
, --verbose
integer range (0
and above) Print verbose logging to stderr. Can specify several times for more verbosity. 0
--help
boolean Show this message and exit. False
"},{"location":"reference/formatting-context/","title":"Formatting context","text":"These fields are available for
#
The literal hash or octothorpe character. ;
The literal semicolon character."},{"location":"reference/formatting-context/#date-and-time-fields","title":"Date and time fields","text":"now
A Python datetime object representing the current local time, without a time zone reference. utcnow
A Python datetime object representing the current local time in the UTC time zone. You can provide additional formatting guidance for datetime objects using formatting codes. Put the formatting codes after the field and a colon. For example, {now:%Y-%m-%d}
would output the current local time as 2023-04-20
.
These fields will only have values if the code is in a Git or Mercurial repository.
commit_sha
The latest commit reference. distance_to_latest_tag
The number of commits since the latest tag. dirty
A boolean indicating if the current repository has pending changes. branch_name
The current branch name. short_branch_name
The current branch name, converted to lowercase, with non-alphanumeric characters removed and truncated to 20 characters. For example, feature/MY-long_branch-name
would become featuremylongbranchn
."},{"location":"reference/formatting-context/#version-fields","title":"Version fields","text":"current_version
The current version serialized as a string current_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have current_major
, current_minor
, and current_patch
available. new_version
The new version serialized as a string new_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have new_major
, new_minor
, and new_patch
available. Note
The following fields are only available when serializing a version.
<version component>
Each version part defined by the version configuration parsing regular expression. The default configuration would have major
, minor
, and patch
available."},{"location":"reference/formatting-context/#environment-variables","title":"Environment variables","text":"Every environment variable available at runtime is included with a $
prefix. For example if USER
was in the environment, {$USER}
would render that value.
Tip
If you use environment variables in your version serialization, you might want to ensure they are set by executing export VAR=value
before running the bump-my-version
command.
A hook suite is a list of hooks to run sequentially. A hook is either an individual shell command or an executable script.
There are three hook suites: setup, pre-commit, and post-commit. During the version increment process this is the order of operations:
Note
Don\u2019t confuse the pre-commit and post-commit hook suites with Git pre- and post-commit hooks. Those hook suites are named for their adjacency to the commit and tag operation.
"},{"location":"reference/hooks/#configuration","title":"Configuration","text":"Configure each hook suite with the setup_hooks
, pre_commit_hooks
, or post_commit_hooks
keys.
Each suite takes a list of strings. The strings may be individual commands:
Calling individual commands[tool.bumpversion]\nsetup_hooks = [\n \"git config --global user.email \\\"bump-my-version@github.actions\\\"\",\n \"git config --global user.name \\\"Testing Git\\\"\",\n \"git --version\",\n \"git config --list\",\n]\npre_commit_hooks = [\"cat CHANGELOG.md\"]\npost_commit_hooks = [\"echo Done\"]\n
or the path to an executable script:
Calling a shell script[tool.bumpversion]\nsetup_hooks = [\"path/to/setup.sh\"]\npre_commit_hooks = [\"path/to/pre-commit.sh\"]\npost_commit_hooks = [\"path/to/post-commit.sh\"]\n
Note
You can make a script executable using the following steps:
#!/bin/bash
chmod u+x path/to/script.sh
to set the executable bitEach hook has these environment variables set when executed.
"},{"location":"reference/hooks/#inherited-environment","title":"Inherited environment","text":"All environment variables set before bump-my-version was run are available.
"},{"location":"reference/hooks/#date-and-time-fields","title":"Date and time fields","text":"BVHOOK_NOW
The ISO-8601-formatted current local time without a time zone reference. BVHOOK_UTCNOW
The ISO-8601-formatted current local time in the UTC time zone."},{"location":"reference/hooks/#source-code-management-fields","title":"Source code management fields","text":"Note
These fields will only have values if the code is in a Git or Mercurial repository.
BVHOOK_COMMIT_SHA
The latest commit reference. BHOOK_DISTANCE_TO_LATEST_TAG
The number of commits since the latest tag. BVHOOK_IS_DIRTY
A boolean indicating if the current repository has pending changes. BVHOOK_BRANCH_NAME
The current branch name. BVHOOK_SHORT_BRANCH_NAME
The current branch name, converted to lowercase, with non-alphanumeric characters removed and truncated to 20 characters. For example, feature/MY-long_branch-name
would become featuremylongbranchn
."},{"location":"reference/hooks/#current-version-fields","title":"Current version fields","text":"BVHOOK_CURRENT_VERSION
The current version serialized as a string BVHOOK_CURRENT_TAG
The current tag BVHOOK_CURRENT_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have BVHOOK_CURRENT_MAJOR
, BVHOOK_CURRENT_MINOR
, and BVHOOK_CURRENT_PATCH
available."},{"location":"reference/hooks/#new-version-fields","title":"New version fields","text":"Note
These are not available in the setup hook suite.
BVHOOK_NEW_VERSION
The new version serialized as a string BVHOOK_NEW_TAG
The new tag BVHOOK_NEW_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have BVHOOK_NEW_MAJOR
, BVHOOK_NEW_MINOR
, and BVHOOK_NEW_PATCH
available."},{"location":"reference/hooks/#outputs","title":"Outputs","text":"The stdout
and stderr
streams are echoed to the console if you pass the -vv
option.
Bump my version does not execute any hooks during a dry run. With the verbose output option it will state which hooks it would have run.
"},{"location":"reference/search-and-replace-config/","title":"Search and replace configuration","text":"Bump-my-version uses a combination of template strings using a formatting context and regular expressions to search the configured files for the old or current version and replace the text with the new version.
Bump My Version defaults to using a simple string search. If the search template is not a valid regular expression or if the no-regex
flag is True
. The search template is always rendered using the formatting context. The basic logic is:
no-regex
flag is True
, use the search string rendered with the unescaped context.Both the search and replace templates are rendered using the formatting context. However, only the search template is also treated as a regular expression. The replacement fields available in the formatting context are enclosed in curly braces {}
.
The search and replace templates can be multiple lines, like so:
[tool.bumpversion]\ncurrent_version = \"1.2.3\"\n\n[[tool.bumpversion.files]]\nfilename = \"config.ini\"\nsearch = \"[myproject]\\nversion={current_version}\"\nreplace = \"[myproject]\\nversion={new_version}\"\n
Alternatively, using TOML\u2019s multiline strings:
[tool.bumpversion]\ncurrent_version = \"1.2.3\"\n\n[[tool.bumpversion.files]]\nfilename = \"config.ini\"\nsearch = \"\"\"\n[myproject]\nversion={current_version}\"\"\"\n\nreplace = \"\"\"\n[myproject]\nversion={new_version}\"\"\"\n
"},{"location":"reference/search-and-replace-config/#using-regular-expressions","title":"Using regular expressions","text":"Only the search template will use Python\u2019s regular expression syntax with minor changes. The template string is rendered using the formatting context. The resulting string is treated as a regular expression for searching unless configured otherwise.
Curly braces ({}
) must be doubled in the regular expression to escape them from the string-formatting process.
If you are using a TOML-formatted configuration file, you must also escape backslashes (\\
) in the regular expression. The TOML parser will treat a single backslash as an escape character.
The following template:
TOMLCFGsearch = \"{current_version} date-released: \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\"\n
search = \"{current_version} date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}\"\n
Gets rendered to:
1\\.2\\.3 date-released: \\d{4}-\\d{2}-\\d{2}\n
This string is used as a regular expression pattern to search.
"},{"location":"reference/search-and-replace-config/#regular-expression-special-characters","title":"Regular expression special characters","text":"The .
, ^
, $
, *
, +
, ?
, ()
, []
, {}
, \\
, |
characters are special characters in regular expressions. If your search string contains these characters, you must escape them with a backslash (\\
) to treat them as literal characters or set the no-regex
flag to True
.
For example, if you are looking for this string in a file:
[Unreleased] 2023-07-17\n
and you use this search pattern:
[Unreleased] \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\n
Bump My Version will not find the string. While the rendered regular expression [Unreleased] \\d{4}-\\d{2}-\\d{2}
is valid, it is not searching for the literal [Unreleased]
. Instead, it matches a single character in the list U
, n
, r
, e
, l
, a
, s
, d
.
You must escape the [
and ]
to treat them as literal characters:
\\[Unreleased\\] \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\n
"},{"location":"reference/api/nav/","title":"Nav","text":"
aliases","text":"Utilities for handling command aliases.
"},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases.AliasedGroup","title":"AliasedGroup","text":" Bases: RichGroup
This following example implements a subclass of Group that accepts a prefix for a command.
If there were a command called push
, it would accept pus
as an alias (so long as it was unique)
get_command(\n ctx: Context, cmd_name: str\n) -> Optional[click.Command]\n
Given a context and a command name, this returns a Command object if it exists or returns None.
"},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases.AliasedGroup.resolve_command","title":"resolve_command","text":"resolve_command(ctx: Context, args: List[str]) -> tuple\n
Find the command and make sure the full command name is returned.
"},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/autocast/","title":"
autocast","text":"Automatically detect the true Python type of a string and cast it to the correct type.
Based on https://github.com/cgreer/cgAutoCast/blob/master/cgAutoCast.py
Only used by Legacy configuration file parser.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.autocast_value","title":"autocast_value","text":"autocast_value(var: Any) -> Any\n
Guess the string representation of the variable\u2019s type.
Parameters:
var
Value to autocast.
TYPE: Any
Returns:
Any
The autocasted value.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.boolify","title":"boolify","text":"boolify(s: str) -> bool\n
Convert a string to a boolean.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.listify","title":"listify","text":"listify(s: str) -> list\n
Convert a string representation of a list into list of homogeneous basic types.
Type of elements in list is determined via first element. Successive elements are cast to that type.
Parameters:
s
String representation of a list.
TYPE: str
Raises:
ValueError
If string does not represent a list.
TypeError
If string does not represent a list of homogeneous basic types.
Returns:
list
List of homogeneous basic types.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.noneify","title":"noneify","text":"noneify(s: str) -> None\n
Convert a string to None.
"},{"location":"reference/api/bumpversion/bump/","title":"
bump","text":"Version changing methods.
"},{"location":"reference/api/bumpversion/bump/#bumpversion.bump-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/bump/#bumpversion.bump-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/bump/#bumpversion.bump.commit_and_tag","title":"commit_and_tag","text":"commit_and_tag(\n config: Config,\n config_file: Optional[Path],\n configured_files: List[ConfiguredFile],\n ctx: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Commit and tag the changes if a tool is configured.
Parameters:
config
The configuration
TYPE: Config
config_file
The configuration file to include in the commit, if it exists
TYPE: Optional[Path]
configured_files
A list of files to commit
TYPE: List[ConfiguredFile]
ctx
The context used to render the tag and tag message
TYPE: MutableMapping
dry_run
True if the operation should be a dry run
TYPE: bool
DEFAULT: False
do_bump(\n version_part: Optional[str],\n new_version: Optional[str],\n config: Config,\n config_file: Optional[Path] = None,\n dry_run: bool = False,\n) -> None\n
Bump the version_part to the next value or set the version to new_version.
Parameters:
version_part
The name of the version component to bump
TYPE: Optional[str]
new_version
The explicit version to set
TYPE: Optional[str]
config
The configuration to use
TYPE: Config
config_file
The configuration file to update
TYPE: Optional[Path]
DEFAULT: None
dry_run
True if the operation should be a dry run
TYPE: bool
DEFAULT: False
get_next_version(\n current_version: Version,\n config: Config,\n version_part: Optional[str],\n new_version: Optional[str],\n) -> Version\n
Bump the version_part to the next value.
Parameters:
current_version
The current version
TYPE: Version
config
The current configuration
TYPE: Config
version_part
Optional part of the version to bump
TYPE: Optional[str]
new_version
Optional specific version to bump to
TYPE: Optional[str]
Returns:
Version
The new version
Raises:
ConfigurationError
If it can\u2019t generate the next version.
"},{"location":"reference/api/bumpversion/cli/","title":"
cli","text":"bump-my-version Command line interface.
"},{"location":"reference/api/bumpversion/cli/#bumpversion.cli-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/cli/#bumpversion.cli-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/cli/#bumpversion.cli.bump","title":"bump","text":"bump(\n args: list,\n config_file: Optional[str],\n verbose: int,\n allow_dirty: Optional[bool],\n current_version: Optional[str],\n new_version: Optional[str],\n parse: Optional[str],\n serialize: Optional[List[str]],\n search: Optional[str],\n replace: Optional[str],\n regex: Optional[bool],\n no_configured_files: bool,\n ignore_missing_files: bool,\n ignore_missing_version: bool,\n dry_run: bool,\n commit: Optional[bool],\n tag: Optional[bool],\n sign_tags: Optional[bool],\n tag_name: Optional[str],\n tag_message: Optional[str],\n message: Optional[str],\n commit_args: Optional[str],\n) -> None\n
Change the version.
ARGS may contain any of the following:
VERSION_PART is the part of the version to increase, e.g. minor
. Valid values include those given in the --serialize
/ --parse
option.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
cli(ctx: Context) -> None\n
Version bump your Python project.
"},{"location":"reference/api/bumpversion/cli/#bumpversion.cli.replace","title":"replace","text":"replace(\n files: list,\n config_file: Optional[str],\n verbose: int,\n allow_dirty: Optional[bool],\n current_version: Optional[str],\n new_version: Optional[str],\n parse: Optional[str],\n serialize: Optional[List[str]],\n search: Optional[str],\n replace: Optional[str],\n regex: bool,\n no_configured_files: bool,\n ignore_missing_version: bool,\n ignore_missing_files: bool,\n dry_run: bool,\n) -> None\n
Replace the version in files.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
sample_config(prompt: bool, destination: str) -> None\n
Print a sample configuration file.
"},{"location":"reference/api/bumpversion/cli/#bumpversion.cli.show","title":"show","text":"show(\n args: List[str],\n config_file: Optional[str],\n format_: str,\n increment: Optional[str],\n) -> None\n
Show current configuration information.
ARGS may contain one or more configuration attributes. For example:
bump-my-version show current_version
bump-my-version show files.0.filename
bump-my-version show scm_info.branch_name
bump-my-version show current_version scm_info.distance_to_latest_tag
show_bump(\n version: str,\n config_file: Optional[str],\n ascii: bool,\n verbose: int,\n) -> None\n
Show the possible versions resulting from the bump subcommand.
"},{"location":"reference/api/bumpversion/context/","title":"
context","text":"Context for rendering messages and tags.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/context/#bumpversion.context-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/context/#bumpversion.context.base_context","title":"base_context","text":"base_context(\n scm_info: Optional[SCMInfo] = None,\n) -> ChainMap\n
The default context for rendering messages and tags.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.calver_string_to_regex","title":"calver_string_to_regex","text":"calver_string_to_regex(calver_format: str) -> str\n
Convert the calver format string to a regex pattern.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.get_context","title":"get_context","text":"get_context(\n config: Config,\n current_version: Optional[Version] = None,\n new_version: Optional[Version] = None,\n) -> ChainMap\n
Return the context for rendering messages and tags.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.get_datetime_info","title":"get_datetime_info","text":"get_datetime_info(current_dt: datetime.datetime) -> dict\n
Return the full structure of the given datetime for formatting.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.prefixed_environ","title":"prefixed_environ","text":"prefixed_environ() -> dict\n
Return a dict of the environment with keys wrapped in ${}
.
exceptions","text":"Custom exceptions for BumpVersion.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.BadInputError","title":"BadInputError","text":"BadInputError(message: str, ctx: Optional[Context] = None)\n
Bases: BumpVersionError
User input was bad.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.BumpVersionError","title":"BumpVersionError","text":"BumpVersionError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: UsageError
Custom base class for all BumpVersion exception types.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.ConfigurationError","title":"ConfigurationError","text":"ConfigurationError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
A configuration key-value is missing or in the wrong type.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.DirtyWorkingDirectoryError","title":"DirtyWorkingDirectoryError","text":"DirtyWorkingDirectoryError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
The working directory is dirty, and it is not allowed.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.FormattingError","title":"FormattingError","text":"FormattingError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
We are unable to represent a version required by a format.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.HookError","title":"HookError","text":"HookError(message: str, ctx: Optional[Context] = None)\n
Bases: BumpVersionError
A hook failed.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.InvalidVersionPartError","title":"InvalidVersionPartError","text":"InvalidVersionPartError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
The specified part (e.g. \u2018bugfix\u2019) was not found.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.MissingValueError","title":"MissingValueError","text":"MissingValueError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
A part required for a version format is empty.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.SignedTagsError","title":"SignedTagsError","text":"SignedTagsError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
The VCS does not support signed tags.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.VersionNotFoundError","title":"VersionNotFoundError","text":"VersionNotFoundError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
A version number was not found in a source file.
"},{"location":"reference/api/bumpversion/files/","title":"
files","text":"Methods for changing files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile","title":"ConfiguredFile","text":"ConfiguredFile(\n file_change: FileChange,\n version_config: VersionConfig,\n search: Optional[str] = None,\n replace: Optional[str] = None,\n)\n
A file to modify in a configured way.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile.get_file_contents","title":"get_file_contents","text":"get_file_contents() -> str\n
Return the contents of the file.
Raises:
FileNotFoundError
if the file doesn\u2019t exist
Returns:
str
The contents of the file
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile.make_file_change","title":"make_file_change","text":"make_file_change(\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Make the change to the file.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile.write_file_contents","title":"write_file_contents","text":"write_file_contents(contents: str) -> None\n
Write the contents of the file.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.DataFileUpdater","title":"DataFileUpdater","text":"DataFileUpdater(\n file_change: FileChange,\n version_part_configs: Dict[str, VersionComponentSpec],\n)\n
A class to handle updating files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.DataFileUpdater-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.DataFileUpdater.update_file","title":"update_file","text":"update_file(\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Update the files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.FileUpdater","title":"FileUpdater","text":"FileUpdater(\n file_change: FileChange,\n version_config: VersionConfig,\n search: Optional[str] = None,\n replace: Optional[str] = None,\n)\n
A class to handle updating files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.FileUpdater-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.FileUpdater.update_file","title":"update_file","text":"update_file(\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Update the files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.contains_pattern","title":"contains_pattern","text":"contains_pattern(search: re.Pattern, contents: str) -> bool\n
Does the search pattern match any part of the contents?
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.log_changes","title":"log_changes","text":"log_changes(\n file_path: str,\n file_content_before: str,\n file_content_after: str,\n dry_run: bool = False,\n) -> None\n
Log the changes that would be made to the file.
Parameters:
file_path
The path to the file
TYPE: str
file_content_before
The file contents before the change
TYPE: str
file_content_after
The file contents after the change
TYPE: str
dry_run
True if this is a report-only job
TYPE: bool
DEFAULT: False
modify_files(\n files: List[ConfiguredFile],\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Modify the files, searching and replacing values according to the FileConfig.
Parameters:
files
The list of configured files
TYPE: List[ConfiguredFile]
current_version
The current version
TYPE: Version
new_version
The next version
TYPE: Version
context
The context used for rendering the version
TYPE: MutableMapping
dry_run
True if this should be a report-only job
TYPE: bool
DEFAULT: False
resolve_file_config(\n files: List[FileChange],\n version_config: VersionConfig,\n search: Optional[str] = None,\n replace: Optional[str] = None,\n) -> List[ConfiguredFile]\n
Resolve the files, searching and replacing values according to the FileConfig.
Parameters:
files
A list of file configurations
TYPE: List[FileChange]
version_config
How the version should be changed
TYPE: VersionConfig
search
The search pattern to use instead of any configured search pattern
TYPE: Optional[str]
DEFAULT: None
replace
The replace pattern to use instead of any configured replace pattern
TYPE: Optional[str]
DEFAULT: None
Returns:
List[ConfiguredFile]
A list of ConfiguredFiles
"},{"location":"reference/api/bumpversion/hooks/","title":"
hooks","text":"Implementation of the hook interface.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.base_env","title":"base_env","text":"base_env(config: Config) -> Dict[str, str]\n
Provide the base environment variables.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.get_post_commit_hook_env","title":"get_post_commit_hook_env","text":"get_post_commit_hook_env(\n config: Config,\n current_version: Version,\n new_version: Version,\n) -> Dict[str, str]\n
Provide the environment dictionary for post_commit_hook
s.
get_pre_commit_hook_env(\n config: Config,\n current_version: Version,\n new_version: Version,\n) -> Dict[str, str]\n
Provide the environment dictionary for pre_commit_hook
s.
get_setup_hook_env(\n config: Config, current_version: Version\n) -> Dict[str, str]\n
Provide the environment dictionary for setup_hook
s.
new_version_env(\n config: Config,\n current_version: Version,\n new_version: Version,\n) -> Dict[str, str]\n
Provide the environment dictionary for new_version serialized and tag name.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_command","title":"run_command","text":"run_command(\n script: str, environment: Optional[dict] = None\n) -> subprocess.CompletedProcess\n
Runs command-line programs using the shell.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_hooks","title":"run_hooks","text":"run_hooks(\n hooks: List[str],\n env: Dict[str, str],\n dry_run: bool = False,\n) -> None\n
Run a list of command-line programs using the shell.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_post_commit_hooks","title":"run_post_commit_hooks","text":"run_post_commit_hooks(\n config: Config,\n current_version: Version,\n new_version: Version,\n dry_run: bool = False,\n) -> None\n
Run the post-commit hooks.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_pre_commit_hooks","title":"run_pre_commit_hooks","text":"run_pre_commit_hooks(\n config: Config,\n current_version: Version,\n new_version: Version,\n dry_run: bool = False,\n) -> None\n
Run the pre-commit hooks.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_setup_hooks","title":"run_setup_hooks","text":"run_setup_hooks(\n config: Config,\n current_version: Version,\n dry_run: bool = False,\n) -> None\n
Run the setup hooks.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.scm_env","title":"scm_env","text":"scm_env(config: Config) -> Dict[str, str]\n
Provide the scm environment variables.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.version_env","title":"version_env","text":"version_env(\n version: Version, version_prefix: str\n) -> Dict[str, str]\n
Provide the environment variables for each version component with a prefix.
"},{"location":"reference/api/bumpversion/indented_logger/","title":"
indented_logger","text":"A logger adapter that adds an indent to the beginning of each message.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter","title":"IndentedLoggerAdapter","text":"IndentedLoggerAdapter(\n logger: logging.Logger,\n extra: Optional[dict] = None,\n depth: int = 2,\n indent_char: str = \" \",\n reset: bool = False,\n)\n
Bases: LoggerAdapter
Logger adapter that adds an indent to the beginning of each message.
Parameters:
logger
The logger to adapt.
TYPE: Logger
extra
Extra values to add to the logging context.
TYPE: Optional[dict]
DEFAULT: None
depth
The number of indent_char
to generate for each indent level.
TYPE: int
DEFAULT: 2
indent_char
The character or string to use for indenting.
TYPE: str
DEFAULT: ' '
reset
True
if the indent level should be reset to zero.
TYPE: bool
DEFAULT: False
property
","text":"current_indent: int\n
The current indent level.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.indent_str","title":"indent_strproperty
","text":"indent_str: str\n
The indent string.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.dedent","title":"dedent","text":"dedent(amount: int = 1) -> None\n
Decrease the indent level by amount
.
indent(amount: int = 1) -> None\n
Increase the indent level by amount
.
process(\n msg: str, kwargs: Optional[MutableMapping[str, Any]]\n) -> Tuple[str, MutableMapping[str, Any]]\n
Process the message and add the indent.
Parameters:
msg
The logging message.
TYPE: str
kwargs
Keyword arguments passed to the logger.
TYPE: Optional[MutableMapping[str, Any]]
Returns:
Tuple[str, MutableMapping[str, Any]]
A tuple containing the message and keyword arguments.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.reset","title":"reset","text":"reset() -> None\n
Reset the indent level to zero.
"},{"location":"reference/api/bumpversion/scm/","title":"
scm","text":"Version control system management.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git","title":"Git","text":" Bases: SourceCodeManager
Git implementation.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.add_path","title":"add_pathclassmethod
","text":"add_path(path: Union[str, Path]) -> None\n
Add a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.assert_nondirty","title":"assert_nondirtyclassmethod
","text":"assert_nondirty() -> None\n
Assert that the working directory is not dirty.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.latest_tag_info","title":"latest_tag_infoclassmethod
","text":"latest_tag_info(\n tag_name: str, parse_pattern: str\n) -> SCMInfo\n
Return information about the latest tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.tag","title":"tagclassmethod
","text":"tag(\n name: str,\n sign: bool = False,\n message: Optional[str] = None,\n) -> None\n
Create a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. Otherwise, it uses an annotated tag.
Parameters:
name
The name of the tag
TYPE: str
sign
True to sign the tag
TYPE: bool
DEFAULT: False
message
An optional message to annotate the tag.
TYPE: Optional[str]
DEFAULT: None
Bases: SourceCodeManager
Mercurial implementation.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.add_path","title":"add_pathclassmethod
","text":"add_path(path: Union[str, Path]) -> None\n
Add a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.assert_nondirty","title":"assert_nondirtyclassmethod
","text":"assert_nondirty() -> None\n
Assert that the working directory is clean.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.latest_tag_info","title":"latest_tag_infoclassmethod
","text":"latest_tag_info(\n tag_name: str, parse_pattern: str\n) -> SCMInfo\n
Return information about the latest tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.tag","title":"tagclassmethod
","text":"tag(\n name: str,\n sign: bool = False,\n message: Optional[str] = None,\n) -> None\n
Create a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. Otherwise, it uses an annotated tag.
Parameters:
name
The name of the tag
TYPE: str
sign
True to sign the tag
TYPE: bool
DEFAULT: False
message
A optional message to annotate the tag.
TYPE: Optional[str]
DEFAULT: None
Raises:
SignedTagsError
If sign
is True
dataclass
","text":"SCMInfo(\n tool: Optional[Type[SourceCodeManager]] = None,\n commit_sha: Optional[str] = None,\n distance_to_latest_tag: int = 0,\n current_version: Optional[str] = None,\n current_tag: Optional[str] = None,\n branch_name: Optional[str] = None,\n short_branch_name: Optional[str] = None,\n repository_root: Optional[Path] = None,\n dirty: Optional[bool] = None,\n)\n
Information about the current source code manager and state.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SCMInfo-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SCMInfo.path_in_repo","title":"path_in_repo","text":"path_in_repo(path: Union[Path, str]) -> bool\n
Return whether a path is inside this repository.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager","title":"SourceCodeManager","text":"Base class for version control systems.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.add_path","title":"add_pathclassmethod
","text":"add_path(path: Union[str, Path]) -> None\n
Add a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.assert_nondirty","title":"assert_nondirtyclassmethod
","text":"assert_nondirty() -> None\n
Assert that the working directory is not dirty.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.commit","title":"commitclassmethod
","text":"commit(\n message: str,\n current_version: str,\n new_version: str,\n extra_args: Optional[list] = None,\n) -> None\n
Commit the changes.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.commit_to_scm","title":"commit_to_scmclassmethod
","text":"commit_to_scm(\n files: List[Union[str, Path]],\n config: Config,\n context: MutableMapping,\n extra_args: Optional[List[str]] = None,\n dry_run: bool = False,\n) -> None\n
Commit the files to the source code management system.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.format_and_raise_error","title":"format_and_raise_errorclassmethod
","text":"format_and_raise_error(\n exc: Union[TypeError, subprocess.CalledProcessError]\n) -> None\n
Format the error message from an exception and re-raise it as a BumpVersionError.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.get_all_tags","title":"get_all_tagsclassmethod
","text":"get_all_tags() -> List[str]\n
Return all tags in VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.get_version_from_tag","title":"get_version_from_tagclassmethod
","text":"get_version_from_tag(\n tag: str, tag_name: str, parse_pattern: str\n) -> Optional[str]\n
Return the version from a tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.is_usable","title":"is_usableclassmethod
","text":"is_usable() -> bool\n
Is the VCS implementation usable.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.latest_tag_info","title":"latest_tag_infoclassmethod
","text":"latest_tag_info(\n tag_name: str, parse_pattern: str\n) -> SCMInfo\n
Return information about the latest tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.tag","title":"tagclassmethod
","text":"tag(\n name: str,\n sign: bool = False,\n message: Optional[str] = None,\n) -> None\n
Create a tag of the new_version in VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.tag_in_scm","title":"tag_in_scmclassmethod
","text":"tag_in_scm(\n config: Config,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Tag the current commit in the source code management system.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.get_scm_info","title":"get_scm_info","text":"get_scm_info(tag_name: str, parse_pattern: str) -> SCMInfo\n
Return a dict with the latest source code management info.
"},{"location":"reference/api/bumpversion/show/","title":"
show","text":"Functions for displaying information about the version.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/show/#bumpversion.show-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/show/#bumpversion.show.do_show","title":"do_show","text":"do_show(\n *args,\n config: Config,\n format_: str = \"default\",\n increment: Optional[str] = None\n) -> None\n
Show current version or configuration information.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_default","title":"output_default","text":"output_default(value: dict) -> None\n
Output the value with key=value or just value if there is only one item.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_json","title":"output_json","text":"output_json(value: dict) -> None\n
Output the value as json.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_yaml","title":"output_yaml","text":"output_yaml(value: dict) -> None\n
Output the value as yaml.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.resolve_name","title":"resolve_name","text":"resolve_name(\n obj: Any,\n name: str,\n default: Any = None,\n err_on_missing: bool = False,\n) -> Any\n
Get a key or attr name
from obj or default value.
Copied and modified from Django Template variable resolutions
Resolution methods:
Parameters:
obj
The object to access
TYPE: Any
name
A dotted name to the value, such as mykey.0.name
TYPE: str
default
If the name cannot be resolved from the object, return this value
TYPE: Any
DEFAULT: None
err_on_missing
Raise a BadInputError
if the name cannot be resolved
TYPE: bool
DEFAULT: False
Returns:
Any
The value at the resolved name or the default value.
Raises:
BadInputError
If we cannot resolve the name and err_on_missing
is True
AttributeError
If a @property decorator raised it
TypeError
If a @property decorator raised it
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.resolve_name--noqa-dar401","title":"noqa: DAR401","text":""},{"location":"reference/api/bumpversion/ui/","title":"
ui","text":"Utilities for user interface.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/ui/#bumpversion.ui-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.get_indented_logger","title":"get_indented_logger","text":"get_indented_logger(name: str) -> IndentedLoggerAdapter\n
Get a logger with indentation.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_error","title":"print_error","text":"print_error(msg: str) -> None\n
Raise an error and exit.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_info","title":"print_info","text":"print_info(msg: str) -> None\n
Echo a message to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_warning","title":"print_warning","text":"print_warning(msg: str) -> None\n
Echo a warning to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.setup_logging","title":"setup_logging","text":"setup_logging(verbose: int = 0) -> None\n
Configure the logging.
"},{"location":"reference/api/bumpversion/utils/","title":"
utils","text":"General utilities.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/utils/#bumpversion.utils-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.extract_regex_flags","title":"extract_regex_flags","text":"extract_regex_flags(regex_pattern: str) -> Tuple[str, str]\n
Extract the regex flags from the regex pattern.
Parameters:
regex_pattern
The pattern that might start with regex flags
TYPE: str
Returns:
Tuple[str, str]
A tuple of the regex pattern without the flag string and regex flag string
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.format_and_raise_error","title":"format_and_raise_error","text":"format_and_raise_error(\n exc: Union[TypeError, subprocess.CalledProcessError]\n) -> None\n
Format the error message from an exception and re-raise it as a BumpVersionError.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.get_nested_value","title":"get_nested_value","text":"get_nested_value(d: dict, path: str) -> Any\n
Retrieves the value of a nested key in a dictionary based on the given path.
Parameters:
d
The dictionary to search.
TYPE: dict
path
A string representing the path to the nested key, separated by periods.
TYPE: str
Returns:
Any
The value of the nested key.
Raises:
KeyError
If a key in the path does not exist.
ValueError
If an element in the path is not a dictionary.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.get_overrides","title":"get_overrides","text":"get_overrides(**kwargs) -> dict\n
Return a dictionary containing only the overridden key-values.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.key_val_string","title":"key_val_string","text":"key_val_string(d: dict) -> str\n
Render the dictionary as a comma-delimited key=value string.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.labels_for_format","title":"labels_for_format","text":"labels_for_format(serialize_format: str) -> List[str]\n
Return a list of labels for the given serialize_format.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.recursive_sort_dict","title":"recursive_sort_dict","text":"recursive_sort_dict(input_value: Any) -> Any\n
Sort a dictionary recursively.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.run_command","title":"run_command","text":"run_command(\n command: list, env: Optional[dict] = None\n) -> CompletedProcess\n
Run a shell command and return its output.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.set_nested_value","title":"set_nested_value","text":"set_nested_value(d: dict, value: Any, path: str) -> None\n
Sets the value of a nested key in a dictionary based on the given path.
Parameters:
d
The dictionary to search.
TYPE: dict
value
The value to set.
TYPE: Any
path
A string representing the path to the nested key, separated by periods.
TYPE: str
Raises:
ValueError
If an element in the path is not a dictionary.
KeyError
If a key in the path does not exist.
"},{"location":"reference/api/bumpversion/visualize/","title":"
visualize","text":"Visualize the bumpversion process.
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.Border","title":"Borderdataclass
","text":"Border(\n corner_bottom_right: str,\n corner_top_right: str,\n corner_top_left: str,\n corner_bottom_left: str,\n divider_left: str,\n divider_up: str,\n divider_down: str,\n divider_right: str,\n line: str,\n pipe: str,\n cross: str,\n)\n
A border definition.
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.connection_str","title":"connection_str","text":"connection_str(\n border: Border,\n has_next: bool = False,\n has_previous: bool = False,\n) -> str\n
Return the correct connection string based on the next and previous.
Parameters:
border
The border definition to draw the lines
TYPE: Border
has_next
If True
, there is a next line
TYPE: bool
DEFAULT: False
has_previous
If True
, there is a previous line
TYPE: bool
DEFAULT: False
Returns:
str
A string that connects left-to-right and top-to-bottom based on the next and previous
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.filter_version_parts","title":"filter_version_parts","text":"filter_version_parts(config: Config) -> List[str]\n
Return the version parts that are in the configuration.
Parameters:
config
The configuration to check against
TYPE: Config
Returns:
List[str]
The version parts that are in the configuration
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.labeled_line","title":"labeled_line","text":"labeled_line(\n label: str,\n border: Border,\n fit_length: Optional[int] = None,\n) -> str\n
Return the version part string with the correct padding.
Parameters:
label
The label to render
TYPE: str
border
The border definition to draw the lines
TYPE: Border
fit_length
The length to fit the label to
TYPE: Optional[int]
DEFAULT: None
Returns:
str
A labeled line with leading and trailing spaces
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.lead_string","title":"lead_string","text":"lead_string(\n version_str: str, border: Border, blank: bool = False\n) -> str\n
Return the first part of a string with the bump character or spaces of the correct amount.
Examples:
>>> lead_string(\"1.0.0\", Border(*BOX_CHARS[\"light\"]))\n'1.0.0 \u2500\u2500 bump \u2500'\n>>> lead_string(\"1.0.0\", Border(*BOX_CHARS[\"light\"]), blank=True)\n' '\n
Parameters:
version_str
The string to render as the starting point
TYPE: str
border
The border definition to draw the lines
TYPE: Border
blank
If True
, return a blank string the same length as the version bump string
TYPE: bool
DEFAULT: False
Returns:
str
The version bump string or a blank string
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.visualize","title":"visualize","text":"visualize(\n config: Config,\n version_str: str,\n box_style: str = \"light\",\n) -> None\n
Output a visualization of the bump-my-version bump process.
"},{"location":"reference/api/bumpversion/yaml_dump/","title":"
yaml_dump","text":"A simple YAML dumper to avoid extra dependencies.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.YAMLDumpers","title":"YAMLDumpers","text":" Bases: UserDict
Registry of YAML dumpers.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.YAMLDumpers-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.YAMLDumpers.add_dumper","title":"add_dumper","text":"add_dumper(data_type: type, dumper: DumperFunc) -> None\n
Add a YAML dumper.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.dump","title":"dump","text":"dump(data: Any) -> str\n
Dump a value to a string buffer.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_bool","title":"format_bool","text":"format_bool(val: bool) -> str\n
Return a YAML representation of a bool.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_date","title":"format_date","text":"format_date(val: datetime.date) -> str\n
Return a YAML representation of a date.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_datetime","title":"format_datetime","text":"format_datetime(val: datetime.datetime) -> str\n
Return a string representation of a value.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_dict","title":"format_dict","text":"format_dict(val: dict) -> str\n
Return a YAML representation of a dict.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_float","title":"format_float","text":"format_float(data: float) -> str\n
Return a YAML representation of a float.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_int","title":"format_int","text":"format_int(val: int) -> str\n
Return a YAML representation of an int.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_none","title":"format_none","text":"format_none(_: None) -> str\n
Return a YAML representation of None.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_sequence","title":"format_sequence","text":"format_sequence(val: Union[list, tuple]) -> str\n
Return a string representation of a value.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_str","title":"format_str","text":"format_str(val: str) -> str\n
Return a YAML representation of a string.
"},{"location":"reference/api/bumpversion/config/","title":"Index","text":"Configuration management.
"},{"location":"reference/api/bumpversion/config/#bumpversion.config-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/#bumpversion.config-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/#bumpversion.config.check_current_version","title":"check_current_version","text":"check_current_version(config: Config) -> str\n
Returns the current version.
If the current version is not specified in the config file, command line or env variable, it attempts to retrieve it via a tag.
Parameters:
config
The current configuration dictionary.
TYPE: Config
Returns:
str
The version number
Raises:
ConfigurationError
If it can\u2019t find the current version
"},{"location":"reference/api/bumpversion/config/#bumpversion.config.get_configuration","title":"get_configuration","text":"get_configuration(\n config_file: Union[str, Path, None] = None,\n **overrides: Any\n) -> Config\n
Return the configuration based on any configuration files and overrides.
Parameters:
config_file
An explicit configuration file to use, otherwise search for one
TYPE: Union[str, Path, None]
DEFAULT: None
**overrides
Specific configuration key-values to override in the configuration
TYPE: Any
DEFAULT: {}
Returns:
Config
The configuration
"},{"location":"reference/api/bumpversion/config/#bumpversion.config.set_config_defaults","title":"set_config_defaults","text":"set_config_defaults(\n parsed_config: dict[str, Any], **overrides: Any\n) -> dict[str, Any]\n
Apply the defaults to the parsed config.
"},{"location":"reference/api/bumpversion/config/create/","title":"
create","text":"Module for creating a new config file.
"},{"location":"reference/api/bumpversion/config/create/#bumpversion.config.create-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/create/#bumpversion.config.create.create_configuration","title":"create_configuration","text":"create_configuration(\n destination: str, prompt: bool\n) -> TOMLDocument\n
Create a new configuration as a TOMLDocument.
Parameters:
destination
stdout
or a path to a new or existing file.
TYPE: str
prompt
True
if the user should be prompted for input.
TYPE: bool
Returns:
TOMLDocument
The TOMLDocument structure with the updated configuration.
"},{"location":"reference/api/bumpversion/config/create/#bumpversion.config.create.get_defaults_from_dest","title":"get_defaults_from_dest","text":"get_defaults_from_dest(\n destination: str,\n) -> Tuple[dict, TOMLDocument]\n
Get the default configuration and the configuration from the destination.
"},{"location":"reference/api/bumpversion/config/files/","title":"
files","text":"Contains methods for finding and reading configuration files.
"},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files.find_config_file","title":"find_config_file","text":"find_config_file(\n explicit_file: Union[str, Path, None] = None\n) -> Union[Path, None]\n
Find the configuration file, if it exists.
If no explicit configuration file is passed, it will search in several files to find its configuration.
Parameters:
explicit_file
The configuration file to explicitly use.
TYPE: Union[str, Path, None]
DEFAULT: None
Returns:
Union[Path, None]
The configuration file path
"},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files.read_config_file","title":"read_config_file","text":"read_config_file(\n config_file: Union[str, Path, None] = None\n) -> Dict[str, Any]\n
Read the configuration file, if it exists.
If no explicit configuration file is passed, it will search in several files to find its configuration.
Parameters:
config_file
The configuration file to explicitly use.
TYPE: Union[str, Path, None]
DEFAULT: None
Returns:
Dict[str, Any]
A dictionary of read key-values
"},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files.read_toml_file","title":"read_toml_file","text":"read_toml_file(file_path: Path) -> Dict[str, Any]\n
Parse a TOML file and return the bumpversion
section.
Parameters:
file_path
The path to the TOML file.
TYPE: Path
Returns:
dict
A dictionary of the bumpversion
section.
TYPE: Dict[str, Any]
update_config_file(\n config_file: Union[str, Path],\n config: Config,\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Update the current_version key in the configuration file.
Parameters:
config_file
The configuration file to explicitly use.
TYPE: Union[str, Path]
config
The configuration to use.
TYPE: Config
current_version
The current version.
TYPE: Version
new_version
The new version.
TYPE: Version
context
The context to use for serialization.
TYPE: MutableMapping
dry_run
True if the update should be a dry run.
TYPE: bool
DEFAULT: False
files_legacy","text":"This module handles the legacy config file format.
"},{"location":"reference/api/bumpversion/config/files_legacy/#bumpversion.config.files_legacy-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/files_legacy/#bumpversion.config.files_legacy.read_ini_file","title":"read_ini_file","text":"read_ini_file(file_path: Path) -> Dict[str, Any]\n
Parse an INI file and return a dictionary of sections and their options.
Parameters:
file_path
The path to the INI file.
TYPE: Path
Returns:
dict
A dictionary of sections and their options.
TYPE: Dict[str, Any]
update_ini_config_file(\n config_file: Union[str, Path],\n current_version: str,\n new_version: str,\n dry_run: bool = False,\n) -> None\n
Update the current_version key in the configuration file.
Instead of parsing and re-writing the config file with new information, it will use a regular expression to just replace the current_version value. The idea is it will avoid unintentional changes (like formatting) to the config file.
Parameters:
config_file
The configuration file to explicitly use.
TYPE: Union[str, Path]
current_version
The serialized current version.
TYPE: str
new_version
The serialized new version.
TYPE: str
dry_run
True if the update should be a dry run.
TYPE: bool
DEFAULT: False
models","text":"Bump My Version configuration models.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config","title":"Config","text":" Bases: BaseSettings
Bump Version configuration.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.files_to_modify","title":"files_to_modifyproperty
","text":"files_to_modify: List[FileChange]\n
Return a list of files to modify.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.resolved_filemap","title":"resolved_filemapproperty
","text":"resolved_filemap: Dict[str, List[FileChange]]\n
Return the cached resolved filemap.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.version_config","title":"version_configproperty
","text":"version_config: 'VersionConfig'\n
Return the version configuration.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.add_files","title":"add_files","text":"add_files(filename: Union[str, List[str]]) -> None\n
Add a filename to the list of files.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.version_spec","title":"version_spec","text":"version_spec(\n version: Optional[str] = None,\n) -> \"VersionSpec\"\n
Return the version specification.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange","title":"FileChange","text":" Bases: BaseModel
A change to make to a file.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange.__hash__","title":"__hash__","text":"__hash__()\n
Return a hash of the model.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange.get_search_pattern","title":"get_search_pattern","text":"get_search_pattern(\n context: MutableMapping,\n) -> Tuple[re.Pattern, str]\n
Render the search pattern and return the compiled regex pattern and the raw pattern.
Parameters:
context
The context to use for rendering the search pattern
TYPE: MutableMapping
Returns:
Tuple[Pattern, str]
A tuple of the compiled regex pattern and the raw pattern as a string.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/utils/","title":"
utils","text":"Helper functions for the config module.
"},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils.get_all_file_configs","title":"get_all_file_configs","text":"get_all_file_configs(config_dict: dict) -> List[FileChange]\n
Make sure all version components are included.
"},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils.get_all_part_configs","title":"get_all_part_configs","text":"get_all_part_configs(\n config_dict: dict,\n) -> Dict[str, VersionComponentSpec]\n
Make sure all version components are included.
"},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils.resolve_glob_files","title":"resolve_glob_files","text":"resolve_glob_files(\n file_cfg: FileChange,\n) -> List[FileChange]\n
Return a list of file configurations that match the glob pattern.
Parameters:
file_cfg
The file configuration containing the glob pattern
TYPE: FileChange
Returns:
List[FileChange]
A list of resolved file configurations according to the pattern.
"},{"location":"reference/api/bumpversion/versioning/","title":"Index","text":"Module for managing Versions and their internal parts.
"},{"location":"reference/api/bumpversion/versioning/conventions/","title":"
conventions","text":"Standard version conventions.
"},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions.pep440_version_spec","title":"pep440_version_spec","text":"pep440_version_spec() -> VersionSpec\n
Return a VersionSpec for PEP 440.
"},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions.semver_spec","title":"semver_spec","text":"semver_spec() -> VersionSpec\n
Return a VersionSpec for SEMVER.
"},{"location":"reference/api/bumpversion/versioning/functions/","title":"
functions","text":"Generators for version parts.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.CalVerFunction","title":"CalVerFunction","text":"CalVerFunction(calver_format: str)\n
Bases: PartFunction
This is a class that provides a CalVer function for version parts.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.CalVerFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.CalVerFunction.bump","title":"bump","text":"bump(value: Optional[str] = None) -> str\n
Return the optional value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.IndependentFunction","title":"IndependentFunction","text":"IndependentFunction(value: Union[str, int, None] = None)\n
Bases: PartFunction
This is a class that provides an independent function for version parts.
It simply returns the optional value, which is equal to the first value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.IndependentFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.IndependentFunction.bump","title":"bump","text":"bump(value: Optional[str] = None) -> str\n
Return the optional value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.NumericFunction","title":"NumericFunction","text":"NumericFunction(\n optional_value: Union[str, int, None] = None,\n first_value: Union[str, int, None] = None,\n)\n
Bases: PartFunction
This is a class that provides a numeric function for version parts.
It simply starts with the provided first_value (0 by default) and increases it following the sequence of integer numbers.
The optional value of this function is equal to the first value.
This function also supports alphanumeric parts, altering just the numeric part (e.g. \u2018r3\u2019 \u2013> \u2018r4\u2019). Only the first numeric group found in the part is considered (e.g. \u2018r3-001\u2019 \u2013> \u2018r4-001\u2019).
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.NumericFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.NumericFunction.bump","title":"bump","text":"bump(value: Union[str, int]) -> str\n
Increase the first numerical value by one.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.PartFunction","title":"PartFunction","text":"Base class for a version part function.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.PartFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.PartFunction.bump","title":"bump","text":"bump(value: str) -> str\n
Increase the value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.ValuesFunction","title":"ValuesFunction","text":"ValuesFunction(\n values: List[str],\n optional_value: Optional[str] = None,\n first_value: Optional[str] = None,\n)\n
Bases: PartFunction
This is a class that provides a values list based function for version parts.
It is initialized with a list of values and iterates through them when bumping the part.
The default optional value of this function is equal to the first value, but may be otherwise specified.
When trying to bump a part which has already the maximum value in the list you get a ValueError exception.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.ValuesFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.ValuesFunction.bump","title":"bump","text":"bump(value: str) -> str\n
Return the item after value
in the list.
models","text":"Models for managing versioning of software projects.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version","title":"Version","text":"Version(\n version_spec: VersionSpec,\n components: Dict[str, VersionComponent],\n original: Optional[str] = None,\n)\n
The specification of a version and its parts.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version.bump","title":"bump","text":"bump(component_name: str) -> 'Version'\n
Increase the value of the specified component, reset its dependents, and return a new Version.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version.required_components","title":"required_components","text":"required_components() -> List[str]\n
Return the names of the parts that are required.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version.values","title":"values","text":"values() -> Dict[str, VersionComponent]\n
Return the values of the parts.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent","title":"VersionComponent","text":"VersionComponent(\n values: Optional[list] = None,\n optional_value: Optional[str] = None,\n first_value: Union[str, int, None] = None,\n independent: bool = False,\n always_increment: bool = False,\n calver_format: Optional[str] = None,\n source: Optional[str] = None,\n value: Union[str, int, None] = None,\n)\n
Represent part of a version number.
Determines the PartFunction that rules how the part behaves when increased or reset based on the configuration given.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.is_independent","title":"is_independentproperty
","text":"is_independent: bool\n
Is the part independent of the other parts?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.is_optional","title":"is_optionalproperty
","text":"is_optional: bool\n
Is the part optional?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.value","title":"valueproperty
","text":"value: str\n
Return the value of the part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.bump","title":"bump","text":"bump() -> 'VersionComponent'\n
Return a part with bumped value.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.copy","title":"copy","text":"copy() -> 'VersionComponent'\n
Return a copy of the part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.null","title":"null","text":"null() -> 'VersionComponent'\n
Return a part with first value.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec","title":"VersionComponentSpec","text":" Bases: BaseModel
Configuration of a version component.
This is used to read in the configuration from the bumpversion config file.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.always_increment","title":"always_incrementclass-attribute
instance-attribute
","text":"always_increment: bool = False\n
Should the component always increment, even if it is not necessary?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.calver_format","title":"calver_formatclass-attribute
instance-attribute
","text":"calver_format: Optional[str] = None\n
The format string for a CalVer component.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.depends_on","title":"depends_onclass-attribute
instance-attribute
","text":"depends_on: Optional[str] = None\n
The name of the component this component depends on.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.first_value","title":"first_valueclass-attribute
instance-attribute
","text":"first_value: Union[str, int, None] = None\n
The first value to increment from.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.independent","title":"independentclass-attribute
instance-attribute
","text":"independent: bool = False\n
Is the component independent of the other components?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.optional_value","title":"optional_valueclass-attribute
instance-attribute
","text":"optional_value: Optional[str] = None\n
The value that is optional to include in the version.
class-attribute
instance-attribute
","text":"values: Optional[list] = None\n
The possible values for the component. If it and calver_format
is None, the component is numeric.
create_component(\n value: Union[str, int, None] = None\n) -> VersionComponent\n
Generate a version component from the configuration.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.set_always_increment_with_calver","title":"set_always_increment_with_calverclassmethod
","text":"set_always_increment_with_calver(data: Any) -> Any\n
Set always_increment to True if calver_format is present.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec","title":"VersionSpec","text":"VersionSpec(\n components: Dict[str, VersionComponentSpec],\n order: Optional[List[str]] = None,\n)\n
The specification of a version\u2019s components and their relationships.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec.create_version","title":"create_version","text":"create_version(values: Dict[str, str]) -> 'Version'\n
Generate a version from the given values.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec.get_dependents","title":"get_dependents","text":"get_dependents(component_name: str) -> List[str]\n
Return the parts that depend on the given part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/serialization/","title":"
serialization","text":"Functions for serializing and deserializing version objects.
"},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization.multisort","title":"multisort","text":"multisort(xs: list, specs: tuple) -> list\n
Sort a list of dictionaries by multiple keys.
From https://docs.python.org/3/howto/sorting.html#sort-stability-and-complex-sorts
Parameters:
xs
The list of dictionaries to sort
TYPE: list
specs
A tuple of (key, reverse) pairs
TYPE: tuple
Returns:
list
The sorted list
"},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization.parse_version","title":"parse_version","text":"parse_version(\n version_string: str, parse_pattern: str\n) -> Dict[str, str]\n
Parse a version string into a dictionary of the parts and values using a regular expression.
Parameters:
version_string
Version string to parse
TYPE: str
parse_pattern
The regular expression pattern to use for parsing
TYPE: str
Returns:
Dict[str, str]
A dictionary of version part labels and their values, or an empty dictionary
Dict[str, str]
if the version string doesn\u2019t match.
Raises:
BumpVersionError
If the parse_pattern is not a valid regular expression
"},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization.serialize","title":"serialize","text":"serialize(\n version: Version,\n serialize_patterns: List[str],\n context: MutableMapping,\n) -> str\n
Attempts to serialize a version with the given serialization format.
Parameters:
version
The version to serialize
TYPE: Version
serialize_patterns
The serialization format to use, using Python\u2019s format string syntax
TYPE: List[str]
context
The context to use when serializing the version
TYPE: MutableMapping
Raises:
FormattingError
if a serialization pattern
Returns:
str
The serialized version as a string
"},{"location":"reference/api/bumpversion/versioning/version_config/","title":"
version_config","text":"Module for managing Versions and their internal parts.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig","title":"VersionConfig","text":"VersionConfig(\n parse: str,\n serialize: Tuple[str],\n search: str,\n replace: str,\n part_configs: Optional[\n Dict[str, VersionComponentSpec]\n ] = None,\n)\n
Hold a complete representation of a version string.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig.order","title":"orderproperty
","text":"order: List[str]\n
Return the order of the labels in a serialization format.
Currently, order depends on the first given serialization format. This seems like a good idea because this should be the most complete format.
Returns:
List[str]
A list of version part labels in the order they should be rendered.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig.parse","title":"parse","text":"parse(\n version_string: Optional[str] = None,\n raise_error: bool = False,\n) -> Optional[Version]\n
Parse a version string into a Version object.
Parameters:
version_string
Version string to parse
TYPE: Optional[str]
DEFAULT: None
raise_error
Raise an exception if a version string is invalid
TYPE: bool
DEFAULT: False
Returns:
Optional[Version]
A Version object representing the string.
Raises:
BumpVersionError
If a version string is invalid and raise_error is True.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig.serialize","title":"serialize","text":"serialize(version: Version, context: MutableMapping) -> str\n
Serialize a version to a string.
Parameters:
version
The version to serialize
TYPE: Version
context
The context to use when serializing the version
TYPE: MutableMapping
Returns:
str
The serialized version as a string
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config-functions","title":"Functions","text":""},{"location":"reference/configuration/","title":"Configuration","text":"Bump My Version looks in three places for configuration information (in order of precedence):
Bump My Version looks in four places for the configuration file to parse (in order of precedence):
--config-file <FILE>
(command line argument)BUMPVERSION_CONFIG_FILE=file
(environment variable).bumpversion.cfg
(legacy).bumpversion.toml
setup.cfg
(legacy)pyproject.toml
.toml
files are recommended. We will likely drop support for ini
-style formats in the future. You should add your configuration file to your source code management system.
By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified.
"},{"location":"reference/configuration/#configuration-sections","title":"Configuration sections","text":"This section configures which files Bump My Version should update by replacing their current version with the newly bumped version.
"},{"location":"reference/configuration/file/#filename","title":"filename","text":"required Yes\u2021 default empty type stringThe name of the file to modify.
Note
\u2021 This is only used with TOML configuration and is only required if glob
is not specified. INI-style configuration files specify the file name as part of the grouping.
The glob pattern specifying the files to modify.
Note
\u2021 This is only used with TOML configuration, and is only required if filename
is not specified. INI-style configuration files specify the glob pattern as part of the grouping.
A list of glob patterns to exclude from the files found via the glob
parameter. Does nothing if filename
is specified.
parse
field type string This is an override to the default pattern to parse the version number from this file.
"},{"location":"reference/configuration/file/#serialize","title":"serialize","text":"required No default the value configured in the globalserialize
field type an array of strings This is an override to the default templates to serialize the new version number in this file.
"},{"location":"reference/configuration/file/#search","title":"search","text":"required No default the value configured in the globalsearch
field type string This is an override to the default template string how to search for the string to be replaced in the file.
"},{"location":"reference/configuration/file/#regex","title":"regex","text":"required No default the value configured in the globalregex
field type boolean If True
, treat the search
parameter as a regular expression.
replace
field type string This is an override to the template to create the string that will replace the current version number in the file.
"},{"location":"reference/configuration/file/#ignore_missing_version","title":"ignore_missing_version","text":"required No default The value configured in the globalignore_missing_version
field type boolean If True
, don\u2019t fail if the version string to be replaced is not found in the file.
ignore_missing_file
field type boolean if True
, don\u2019t fail if the configured file is missing.
The include_bumps
file configuration allows you to control when bump-my-version includes this file for changes. Its alternative is the exclude_bumps
configuration. When a bump <version component>
command is issued, this file is changed only if the version component is in this list and not in exclude_bumps
. The parse configuration defines version components.
The default value, or an empty list, includes all version components.
"},{"location":"reference/configuration/file/#exclude_bumps","title":"exclude_bumps","text":"required No default[]
type list of strings The exclude_bumps
file configuration allows you to control when bump-my-version excludes this file for changes. Its alternative is the include_bumps
configuration. When a bump <version component>
command is issued, this file is only changed if the version component is not in this list. The parse configuration defines version components.
The default value does not exclude anything.
"},{"location":"reference/configuration/file/#examples","title":"Examples","text":"TOMLCFGTOML allows us to specify the files using an array of tables. TOML configuration adds two fields to each file configuration: filename
and glob
. These fields are mutually exclusive: if you specify a value for both, only the glob
value is used.
For example, to change coolapp/__init__.py
with the defaults and alter CHANGELOG.md
twice:
[[tool.bumpversion.files]]\nfilename = \"coolapp/__init__.py\"\n\n[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"Unreleased\"\n\n[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"{current_version}...HEAD\"\nreplace = \"{current_version}...{new_version}\"\n
INI-style configuration is in the section: [bumpversion:file:<filename>]
or [bumpversion:glob:<glob pattern>]
.
Both, file:
and glob:
are configured the same. Their difference is that file will match file names directly like requirements.txt
. While glob also matches multiple files via wildcards like **/pom.xml
.
Note
The configuration file format requires each section header to be unique. If you want to process a certain file multiple times, you may append a description between parens to the file
keyword: [bumpversion:file (special one):\u2026]
.
For example, to change coolapp/__init__.py
with the defaults and alter CHANGELOG.md
twice:
[bumpversion:file:coolapp/__init__.py]\n\n[bumpversion:file(version heading):CHANGELOG.md]\nsearch = Unreleased\n\n[bumpversion:file(previous version):CHANGELOG.md]\nsearch = {current_version}...HEAD\nreplace = {current_version}...{new_version}\n
"},{"location":"reference/configuration/global/","title":"Global Configuration","text":"The general configuration is grouped in a [tool.bumpversion]
or [bumpversion]
section, depending on if it is a TOML or INI file, respectfully.
False
type boolean command line option --allow-dirty | --no-allow-dirty
environment var BUMPVERSION_ALLOW_DIRTY
Bump-my-version\u2019s default behavior is to abort if the working directory has uncommitted changes. This protects you from releasing unversioned files and overwriting unsaved changes.
"},{"location":"reference/configuration/global/#commit","title":"commit","text":"required No defaultFalse
(Don\u2019t create a commit) type boolean command line option --commit | --no-commit
environment var BUMPVERSION_COMMIT
Whether to create a commit using git or Mercurial.
If you have pre-commit hooks, add an option to commit_args
to turn off your pre-commit hooks. For Git, use --no-verify
and use --config hooks.pre-commit=
for Mercurial.
\"\"
type string command line option --commit-args
environment var BUMPVERSION_COMMIT_ARGS
Extra arguments to pass to commit command. This is only used when the commit
option is set to True
.
If you have pre-commit hooks, add an option to turn off your pre-commit hooks. For Git, use --no-verify
and use --config hooks.pre-commit=
for Mercurial.
\"\"
type string command line option --current-version
environment var BUMPVERSION_CURRENT_VERSION
The current version of the software package before bumping. A value for this is required.
"},{"location":"reference/configuration/global/#ignore_missing_files","title":"ignore_missing_files","text":"required No defaultFalse
type boolean command line option --ignore-missing-files
environment var BUMPVERSION_IGNORE_MISSING_FILES
If True
, don\u2019t fail if the configured file is missing.
False
type boolean command line option --ignore-missing-version
environment var BUMPVERSION_IGNORE_MISSING_VERSION
If True
, don\u2019t fail if the version string to be replaced is not found in the file.
Bump version: {current_version} \u2192 {new_version}
type string command line option --message
environment var BUMPVERSION_MESSAGE
The commit message template to use when creating a commit. This is only used when the commit
option is set to True
.
This string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
"},{"location":"reference/configuration/global/#parse","title":"parse","text":"required No default(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)
type string command line option --parse
environment var BUMPVERSION_PARSE
This is the default regular expression (Python regular expression syntax) for finding and parsing the version string into its components. Individual part or file configurations may override this.
The regular expression must be able to parse all strings produced by the configured serialize
value. Named matching groups (\u201c(?P<name>...)
\u201d) indicate the version part the matched value belongs to.
False
type boolean command line option --regex | --no-regex
environment var BUMPVERSION_REGEX
Treat the search
string as a regular expression.
{new_version}
type string command line option --replace
environment var BUMPVERSION_REPLACE
This is the template to create the string that will replace the current version number in the file.
"},{"location":"reference/configuration/global/#search","title":"search","text":"required No default{current_version}
type string command line option --search
environment var BUMPVERSION_SEARCH
This is the template string for searching. It is rendered using the formatting context for searching in the file. Individual file configurations may override this. This can span multiple lines and is templated using Python Format String Syntax. The formatting context reference describes the available variables.
This is useful if there is the remotest possibility that the current version number might be present multiple times in the file and you mean to bump only one of the occurrences.
"},{"location":"reference/configuration/global/#serialize","title":"serialize","text":"required No default[\"{major}.{minor}.{patch}\"]
type an array of strings command line option --serialize
environment var BUMPVERSION_SERIALIZE
This is the default list of templates specifying how to serialize the version parts back to a version string. Individual part or file configurations may override this.
Since version parts can be optional, bumpversion will try the serialization formats beginning with the first and choose the last one where all values can all non-optional values are represented.
In this example (in TOML):
serialize = [\n \"{major}.{minor}.{patch}\",\n \"{major}.{minor}\",\n \"{major}\"\n]\n
Since 0
is optional by default, Version 1.8.9
will serialize to 1.8.9
, 1.9.0
will serialize to 1.9
, and version 2.0.0
will serialize as 2
.
Each string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
"},{"location":"reference/configuration/global/#sign_tags","title":"sign_tags","text":"required No defaultFalse
(Don\u2019t sign tags) type boolean command line option --sign-tags | --no-sign-tags
environment var BUMPVERSION_SIGN_TAGS
If True
, sign the created tag, when tag
is True
.
False
(Don\u2019t create a tag) type boolean command line option --tag | --no-tag
environment var BUMPVERSION_TAG
If True
, create a tag after committing the changes. The tag is named using the tag_name
option.
If you are using git
, don\u2019t forget to git-push
with the --tags
flag when you are done.
Bump version: {current_version} \u2192 {new_version}
type string command line option --tag-message
environment var BUMPVERSION_TAG_MESSAGE
The tag message template to use when creating a tag when tag
is True
This string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
Bump My Version creates an annotated tag in Git by default. To turn this off and create a lightweight tag, you must explicitly set an empty tag_message
value.
v{new_version}
type string command line option --tag-name
environment var BUMPVERSION_TAG_NAME
The template used to render the tag when tag
is True
.
This string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
"},{"location":"reference/configuration/global/#examples","title":"Examples","text":"TOMLCFG[tool.bumpversion]\nallow_dirty = false\ncommit = false\nmessage = \"Bump version: {current_version} \u2192 {new_version}\"\ncommit_args = \"\"\ntag = false\nsign_tags = false\ntag_name = \"v{new_version}\"\ntag_message = \"Bump version: {current_version} \u2192 {new_version}\"\ncurrent_version = \"1.0.0\"\nparse = \"(?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)\"\nserialize = [\n \"{major}.{minor}.{patch}\"\n]\nsearch = \"{current_version}\"\nreplace = \"{new_version}\"\n
[bumpversion]\nallow_dirty = False\ncommit = False\nmessage = Bump version: {current_version} \u2192 {new_version}\ncommit_args = \ntag = False\nsign_tags = False\ntag_name = v{new_version}\ntag_message = Bump version: {current_version} \u2192 {new_version}\ncurrent_version = 1.0.0\nparse = (?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)\nserialize =\n {major}.{minor}.{patch}\nsearch = {current_version}\nreplace = {new_version}\n
"},{"location":"reference/configuration/version-component/","title":"Version component-specific configuration","text":"Version component configuration is grouped in a [tool.bumpversion.parts.<partname>]
or [bumpversion:part:<partname>]
section, depending on if it is a TOML or INI file, respectfully.
You only need to configure version parts if they deviate from the default, and then you only need to specify the overridden options.
"},{"location":"reference/configuration/version-component/#values","title":"values","text":"required No default numeric (i.e.0
, 1
, 2
, \u2026) type array of strings An explicit list of all values to iterate through when bumping this part. An empty array is treated as indicating numeric
values.
values
, 0
when using numeric values type string When the version part matches this value, it is considered optional when serializing the final version string.
Note
Numeric values are still treated as strings internally, so when specifying an optional value, you must use a string.
"},{"location":"reference/configuration/version-component/#first_value","title":"first_value","text":"required No default The first entry invalues
, 0
when using numeric values type string When the part is reset, the value will be set to the value specified here.
Note
Numeric values are still treated as strings internally, so when specifying a first value, you must use a string.
"},{"location":"reference/configuration/version-component/#independent","title":"independent","text":"required No defaultFalse
type boolean When this value is set to True
, the part is not reset when other parts are incremented. Its incrementation is independent of the other parts. It is useful when you have a build number in your version that is incremented independently of the actual version.
False
(True
if calver_format
is set) type boolean When this value is set to True
, the part is always incremented when the version is bumped, regardless of the target part.
The calver_format
is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the CalVer reference.
[tool.bumpversion.parts.release]\nvalues = [\n \"alpha\",\n \"beta\",\n \"gamma\"\n]\noptional_value = \"gamma\"\n
[bumpversion:part:release]\noptional_value = gamma\nvalues =\n alpha\n beta\n gamma\n
"},{"location":"tutorials/getting-started/","title":"Getting Started","text":""},{"location":"tutorials/getting-started/#installation","title":"Installation","text":"You can download and install the latest version of this software from the Python package index (PyPI) as follows:
pip install --upgrade bump-my-version\n
"},{"location":"tutorials/getting-started/#create-a-default-configuration","title":"Create a default configuration","text":"The default configuration uses a simplified version of semantic versioning.
Note
Python projects can use pyproject.toml
as the --destination
of the sample config.
$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml\n$ cat .bumpversion.toml\n[tool.bumpversion]\ncurrent_version = \"0.1.0\"\nparse = \"(?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)\"\nserialize = [\"{major}.{minor}.{patch}\"]\nsearch = \"{current_version}\"\nreplace = \"{new_version}\"\nregex = false\nignore_missing_version = false\ntag = false\nsign_tags = false\ntag_name = \"v{new_version}\"\ntag_message = \"Bump version: {current_version} \u2192 {new_version}\"\nallow_dirty = false\ncommit = false\nmessage = \"Bump version: {current_version} \u2192 {new_version}\"\ncommit_args = \"\"\n
"},{"location":"tutorials/getting-started/#visualize-the-versioning-path","title":"Visualize the versioning path","text":"You can see the potential versioning paths with the show-bump
subcommand. This visualization will help debug any versioning logic you implement.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0\n \u251c\u2500 minor \u2500 0.2.0\n \u2570\u2500 patch \u2500 0.1.1\n
You can also pass in a specific version to see how bumping that version would work.
Showing the potential versioning path from a specific version$ bump-my-version show-bump 1.2.3\n1.2.3 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0\n \u251c\u2500 minor \u2500 1.3.0\n \u2570\u2500 patch \u2500 1.2.4\n
"},{"location":"tutorials/getting-started/#configure-a-file-to-modify-when-bumping","title":"Configure a file to modify when bumping","text":"Let\u2019s say your version is stored in a file named VERSION
. Every time you bump your version, that file needs to change.
Create the VERSION
file with the current version 0.1.0
:
$ echo \"0.1.0\" >> VERSION\n
Add the following to the .bumpversion.toml
file.
[[tool.bumpversion.files]]\nfilename = \"VERSION\"\n
Now bump-my-version will look in the VERSION
file for the current version in that file and replace it with the new version on each bump-my-version bump
command.
You will increment the version using the bump
subcommand. You \u201cbump\u201d a specific segment of the version. These segments are defined in the parse
configuration. In this configuration ((?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)
) the segments are major
, minor
, patch
.
The --dry-run
option will explain all the steps it performs without permanent changes. Use the -vv
option to get the full description for debugging later.
Note
If you are in a Git or Mercurial repository, you may see additional messages.
Incrementing the minor segment$ bump-my-version bump minor --dry-run -vv\nStarting BumpVersion 0.25.1\nReading configuration\n Reading config file: /users/gettingstarted/.bumpversion.toml\n Parsing current version '0.1.0'\n Parsing version '0.1.0' using regexp '(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)'\n Parsed the following values: major=0, minor=1, patch=0\n Attempting to increment part 'minor'\n Values are now: major=0, minor=2, patch=0\n Serializing version '<bumpversion.Version:major=0, minor=2, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.2.0'\n New version will be '0.2.0'\nDry run active, won't touch any files.\n\nFile VERSION: replace `{current_version}` with `{new_version}`\n Serializing the current version\n Serializing version '<bumpversion.Version:major=0, minor=1, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.1.0'\n Serializing the new version\n Serializing version '<bumpversion.Version:major=0, minor=2, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.2.0'\n Rendering search pattern with context\n No RegEx flag detected. Searching for the default pattern: '0\\.1\\.0'\n Found '0\\.1\\.0' at line 1: 0.1.0\n Would change file VERSION:\n *** before VERSION\n --- after VERSION\n ***************\n *** 1 ****\n ! 0.1.0\n --- 1 ----\n ! 0.2.0\n\nProcessing config file: /users/gettingstarted/.bumpversion.toml\n Serializing version '<bumpversion.Version:major=0, minor=1, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.1.0'\n Serializing version '<bumpversion.Version:major=0, minor=2, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.2.0'\n Rendering search pattern with context\n No RegEx flag detected. Searching for the default pattern: '0\\.1\\.0'\n Found '0\\.1\\.0' at line 1: 0.1.0\n Would change file /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version:\n *** before /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version\n --- after /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version\n ***************\n *** 1 ****\n ! 0.1.0\n --- 1 ----\n ! 0.2.0\nDone.\n
"},{"location":"tutorials/nav/","title":"Nav","text":"The default configuration uses a simplified version of semantic versioning.
Generating a default configuration$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml\n$ cat .bumpversion.toml\n[tool.bumpversion]\ncurrent_version = \"0.1.0\"\nparse = \"(?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)\"\nserialize = [\"{major}.{minor}.{patch}\"]\nsearch = \"{current_version}\"\nreplace = \"{new_version}\"\nregex = false\nignore_missing_version = false\ntag = false\nsign_tags = false\ntag_name = \"v{new_version}\"\ntag_message = \"Bump version: {current_version} \u2192 {new_version}\"\nallow_dirty = false\ncommit = false\nmessage = \"Bump version: {current_version} \u2192 {new_version}\"\ncommit_args = \"\"\n
"},{"location":"tutorials/semantic-versioning-example/#visualize-the-versioning-path","title":"Visualize the versioning path","text":"You can see the potential versioning paths with the show-bump
subcommand.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0\n \u251c\u2500 minor \u2500 0.2.0\n \u2570\u2500 patch \u2500 0.1.1\n$ bump-my-version show-bump 1.2.3\n1.2.3 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0\n \u251c\u2500 minor \u2500 1.3.0\n \u2570\u2500 patch \u2500 1.2.4\n
The default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?
"},{"location":"tutorials/semantic-versioning-example/#add-support-for-pre-release-versions","title":"Add support for pre-release versions","text":"Alter the parse
configuration to support pre-release versions. This parse
option uses an extended (or verbose) regular expression to extract the version components from the current version.
parse = \"\"\"(?x)\n (?P<major>0|[1-9]\\\\d*)\\\\.\n (?P<minor>0|[1-9]\\\\d*)\\\\.\n (?P<patch>0|[1-9]\\\\d*)\n (?:\n - # dash separator for pre-release section\n (?P<pre_l>[a-zA-Z-]+) # pre-release label\n (?P<pre_n>0|[1-9]\\\\d*) # pre-release version number\n )? # pre-release section is optional\n\"\"\"\n
Alter the serialize
configuration to support pre-release versions.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\n
Add a new configuration section for the pre_l
part.
[tool.bumpversion.parts.pre_l]\nvalues = [\"dev\", \"rc\", \"final\"]\noptional_value = \"final\"\n
"},{"location":"tutorials/semantic-versioning-example/#visualize-the-new-versioning-path","title":"Visualize the new versioning path","text":"Now when you run bump-my-version show-bump
, you can see the new pre-release versioning path.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0-dev0\n \u251c\u2500 minor \u2500 0.2.0-dev0\n \u251c\u2500 patch \u2500 0.1.1-dev0\n \u251c\u2500 pre_l \u2500 invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.\n \u2570\u2500 pre_n \u2500 0.1.0-final1\n
The pre_l
is not bump-able because it is already at the maximum value. The pre_n
is bump-able because it is not at the maximum value.
If we run bump-my-version show-bump 1.0.0-dev0
, we can see the new versioning path for a dev
starting version.
$ bump-my-version show-bump 1.0.0-dev0\n1.0.0-dev0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u251c\u2500 pre_l \u2500 1.0.0-rc0\n \u2570\u2500 pre_n \u2500 1.0.0-dev1\n
Finally, we can see the new versioning path for a rc
starting version.
$ bump-my-version show-bump 1.0.0-rc0 \n1.0.0-rc0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u251c\u2500 pre_l \u2500 1.0.0\n \u2570\u2500 pre_n \u2500 1.0.0-rc1\n
The full development and release path is:
1.0.0
bump patch
\u2192 1.0.1-dev0
bump pre_n
\u2192 1.0.1-dev1
bump pre_l
\u2192 1.0.1-rc0
bump pre_n
\u2192 1.0.1-rc1
bump pre_l
\u2192 1.0.1
bump-my-version bump pre_n
.bump-my-version bump pre_l
.bump-my-version bump pre_n
.bump-my-version bump pre_l
.The pre_n
or pre-release number is a number that increases with each pre-release. You can automate this by changing the serialization configuration.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}\",\n \"{major}.{minor}.{patch}\",\n]\n
The distance_to_latest_tag
is a special value that is replaced with the number of commits since the last tag. This is a good value to use for the pre_n
because it will always increase with each commit.
Now when you run bump-my-version show-bump
, you can see the new pre-release versioning path.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0-dev0\n \u251c\u2500 minor \u2500 0.2.0-dev0\n \u251c\u2500 patch \u2500 0.1.1-dev0\n \u2570\u2500 pre_l \u2500 invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.\n$ bump-my-version show-bump 1.0.0-dev0\n1.0.0-dev0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u2570\u2500 pre_l \u2500 1.0.0-rc0\n$ bump-my-version show-bump 1.0.0-rc0 \n1.0.0-rc0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u2570\u2500 pre_l \u2500 1.0.0\n
The pre_n
path is now missing because it is automated.
The full development and release path now is:
1.0.0
bump patch
\u2192 1.0.1-dev0
1.0.1-dev1
bump pre_l
\u2192 1.0.1-rc0
1.0.1-rc1
bump pre_l
\u2192 1.0.1
bump-my-version bump pre_l
.bump-my-version bump pre_l
.Bump My Version\u2019s purpose is to:
You can download and install the latest version of this software from the Python package index (PyPI) as follows:
pip install --upgrade bump-my-version\n
"},{"location":"CHANGELOG/","title":"Changelog","text":""},{"location":"CHANGELOG/#0281-2024-11-03","title":"0.28.1 (2024-11-03)","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 9fb0347
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.9 \u2192 v0.7.1
Compare the full difference.
"},{"location":"CHANGELOG/#new","title":"New","text":"Add Docker support and configure Dependabot for Docker updates. 0315db4
Introduce a Dockerfile for containerized environments and add a .dockerignore file to exclude unnecessary files. Also, update dependabot.yml to include daily checks for Docker image updates. - Add inputs
section in GHA workflow example. 813e7f5
Switch from ADD to COPY in Dockerfile. a5fc5c0
This change updates the Dockerfile to use the COPY instruction instead of ADD. COPY is preferred when only copying files because it is more explicit and simpler. - [pre-commit.ci] pre-commit autoupdate. 7c48f98
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.8 \u2192 v0.6.9
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_1","title":"Fixes","text":"Refactor and enhance error handling. c84bfa7
Updated subprocess calls to disable check, refined lint configurations, fixed type annotations and exceptions, and improved dictionary path validation.
Add HookError for failed hook execution with tests. 39fc233
Raise HookError when a hook script exits with a non-zero status. Modified logger to display warnings instead of debug messages in such scenarios. Added tests to ensure exceptions are raised for failed hooks.
[pre-commit.ci] pre-commit autoupdate. 130478d
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.5 \u2192 v0.6.7
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_2","title":"Fixes","text":"Fixed missing new version info in some hook environments. 24a9bdc
Introduce the new_version_env
function and update existing functions (get_setup_hook_env
and get_pre_commit_hook_env
) to include new version environment variables. Added new tests for verifying the inclusion of OS, SCM, current, and new version information in hook environments.
[pre-commit.ci] pre-commit autoupdate. d21d6df
updates: - github.com/astral-sh/ruff-pre-commit: v0.6.2 \u2192 v0.6.4
[pre-commit.ci] pre-commit autoupdate. b6773ac
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.7 \u2192 v0.6.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_3","title":"Fixes","text":"Add hooks configuration fields. d6b24f0
Introduced setup_hooks
, pre_bump_hooks
, and post_bump_hooks
fields to configuration models. Updated corresponding test fixtures to verify these new fields. - Add current_tag field to scm_info. 304c599
Updated the scm_info structure to include a new field, current_tag, across various configuration files and source code. This ensures that the current tag is tracked and represented in the output formats correctly.
Enhance hook handling and testing across hook types. 49f1953
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.6 \u2192 v0.5.7
Changed the terminology for hooks. 049b470
Change pre-bump and post-bump to pre-commit and post-commit to better indicate their order of operations.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_4","title":"Fixes","text":"Fixed terminology in tests. 0338da2
Updated test parameter and assertion messages to use \u201cversion component\u201d instead of \u201cversion part\u201d for clarity and consistency. This change affects the test cases that detect bad or missing version inputs. - Fixed documentation layout. 57958ea
Fixed inconsistent terms in docstrings. dfdf23e
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_5","title":"Fixes","text":"Refactor version parsing in visualize function. 5f25300
Simplify the version parsing process by utilizing the raise_error parameter in the parse method, removing the need for a separate error check. This change ensures that parsing errors are immediately raised and handled cleanly within the visualize function. - Refactor and rename version_part
to versioning.version_config
. 5b90817
Moved version_part.py
to versioning/version_config.py
and updated all import statements accordingly. Enhanced error handling in VersionConfig
by adding raise_error
flag and relevant exception raising for invalid version strings. Refined tests to reflect these changes. - Fix version visualization and add verbose logging. ad46978
Raise an exception for unparsable versions and aggregate visualization output in a list before printing. Add a verbose logging option to the show_bump
command for detailed logging control.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_6","title":"Fixes","text":"Fix JSON serialization. d3f3022
Extended the default_encoder function to handle Path objects by converting them to their string representation. This ensures that Path objects can be properly serialized to JSON format.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_7","title":"Fixes","text":"Fixes repository path checks. ff3f72a
Checked for relative paths when determining if the file was part of the repo or not. - Fixed test to use globs. 72f9841
[pre-commit.ci] pre-commit autoupdate. 58cc73e
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.5 \u2192 v0.5.6
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_8","title":"Fixes","text":"Refactor error handling and improve logging in utils. 890b692
Extracted error formatting to a dedicated function and applied it across the codebase. Improved command path handling in add_path
and enhanced test coverage with necessary imports and logging configurations. - Fix dictionary merging in SCMInfo. 5fb5ef2
Replaced the bitwise OR operator with the update method for merging dictionaries for 3.8 support - Refactor SCM info retrieval and config file update checks. 500ecd3
Replaced ChainMap with MutableMapping in function signatures and types. Enhanced SCM info handling by splitting code into dedicated methods for commit and revision info retrieval. Added logic to prevent config file updates when the file is outside the repo and implemented corresponding test.
Add repository_root field and refactor subprocess handling. 25670d0
Introduced the repository_root
field to store the root path of the repository in the data classes. Refactored subprocess handling to use a new run_command
utility for improved readability and error handling consistency. Removed unnecessary dependency from .pre-commit-config.yaml
to streamline dependencies.
Simplify run_command return type. b91224e
Changed the return type of run_command from CompletedProcess[str] to CompletedProcess. This was done to remove unnecessary type specificity and ensure compatibility with different Python versions. The update maintains functionality and improves code readability. - [pre-commit.ci] pre-commit autoupdate. e0ba544
updates: - github.com/astral-sh/ruff-pre-commit: v0.5.2 \u2192 v0.5.5
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_9","title":"Fixes","text":"Fix KeyError in TOML file handling. f3c328a
The code has been updated to handle KeyErrors when updating TOML files. If a KeyError is raised, it\u2019s now caught and managed depending on the file_change attributes \u2018ignore_missing_file\u2019 or \u2018ignore_missing_version\u2019. This aims to provide more robust handling of edge cases in TOML files. In addition, a new test case has been added to ensure current version is not required in the configuration.
Fixes #212
[pre-commit.ci] pre-commit autoupdate. 536c7b1
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.10 \u2192 v0.5.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_10","title":"Fixes","text":"Fixed tag version extraction. 67eea3d
The output of git describe
uses -
as a delimiter. Parsing tags caused splits in the parsing of version numbers.
This joins all the remaining parts of the git describe
with a -
. - Fixed pydoclint configuration. 0386073
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_11","title":"Fixes","text":"Refactor error handling in SCM and add error handling test. 7ca6356
This commit includes a new test in test_scm.py to verify the correct formatting and raising of subprocess errors in the SCM module. Additionally, the subprocess error handling has been refactored in the SCM module to include a new method, format_and_raise_error, for improved code readability and reusability.
[pre-commit.ci] pre-commit autoupdate. 60acc2d
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.9 \u2192 v0.4.10
Compare the full difference.
"},{"location":"CHANGELOG/#new_5","title":"New","text":"Add VersionNotFoundError test in test_bump.py. cb050a8
The code in test_bump.py file has been modified to include a test for VersionNotFoundError exception. This ensures that the implementation properly handles cases where a specified version could not be found. - Add test for no commit on modification error. 7527029
A test has been added to the bumpversion library to ensure that no commit and tag is made if there is an error modification. Specifically, the test checks the \u201cdo_bump\u201d function and asserts that \u201cmock_commit_and_tag\u201d and \u201cmock_update_config_file\u201d are not called under these conditions.
[pre-commit.ci] pre-commit autoupdate. 0e3a154
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.8 \u2192 v0.4.9
Improve error message for SCM command failures. 8f72f86
The error message for failures in the SCM command execution has been enhanced. Now it displays not only the command\u2019s return code but also the standard output and error, improving the debugging process.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_12","title":"Fixes","text":"Refactor valid_bumps and invalid_bumps to include_bumps and exclude_bumps. 2df57cc
The configuration parameters valid_bumps
and invalid_bumps
were renamed to include_bumps
and exclude_bumps
respectively. This new naming better denotes their function, and the changes were consistently applied across all related files and tests. Numerous fixture outputs were also updated to reflect these changes. - Fixed spelling in CODE_OF_CONDUCT.md. 254ea44
Add file filtering based on valid and invalid bumps. f9f7f96
This commit introduces the ability to filter files based on whether the specified bump type is valid or not. It adds valid_bumps
and invalid_bumps
lists in the file configurations and adjusts the bumping process to consider these configurations. Tests are updated to reflect these new handling of valid and invalid bumps. - Add new files to .gitignore. 34e4dc1
Several new file types have been added to .gitignore for ignoring during commits. These include \u2018.python-version\u2019, \u2018requirements-dev.lock\u2019, and \u2018requirements.lock\u2019 files. - Add valid_bumps and invalid_bumps to file configuration. 9458851
Updated the configuration file model to support valid_bumps and invalid_bumps. This feature provides control over which version section updates can trigger file changes. Adjusted various test fixtures and cleaned up tests to match these changes. Also, some updates were made to the documentation accordingly.
[pre-commit.ci] pre-commit autoupdate. e44f6af
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.4 \u2192 v0.4.8
Update documentation for clarification. 2224808
The changes made update the wording in the documentation to clarify the roles of include_bumps
and exclude_bumps
in the bump-my-version configuration. Additionally, unnecessary repetition was removed and overlapping examples were also corrected. - Update docs/reference/configuration.md. 7c801c0
co-authored-by: wkoot 3715211+wkoot@users.noreply.github.com
Compare the full difference.
"},{"location":"CHANGELOG/#new_7","title":"New","text":"Add extensive documentation for the \u2018show\u2019 subcommand. 91409d8
This commit adds extensive documentation for the show
subcommand in the program\u2019s reference. It also includes smaller updates and corrections to other parts of the documentation. An in-depth example usage of show
is added both to the dedicated show.md
file and in the function\u2019s docstring.
Compare the full difference.
"},{"location":"CHANGELOG/#other_11","title":"Other","text":"[pre-commit.ci] auto fixes from pre-commit.com hooks. 1b57c2b
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. e813eda
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.3 \u2192 v0.4.4
[pre-commit.ci] pre-commit autoupdate. 05a0dd6
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.2 \u2192 v0.4.3
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_13","title":"Fixes","text":"Fixed a bug in the glob tests. 1041fe9
Was not properly looking in the correct relative directories. - Fixed test for Windows glob paths. ea45c4c
Adds glob_exclude
file specification parameter. 420e3bd
User can prune the files resolved via the glob
parameter.
Fixes #184
[pre-commit.ci] pre-commit autoupdate. ce02aa7
updates: - github.com/astral-sh/ruff-pre-commit: v0.4.1 \u2192 v0.4.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_14","title":"Fixes","text":"Fixed the indentation problem. ec3cd99
[pre-commit.ci] pre-commit autoupdate. e916f87
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.7 \u2192 v0.4.1
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_15","title":"Fixes","text":"Fixed the rendering of numeric version components. c522c75
[pre-commit.ci] pre-commit autoupdate. 9b09da8
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.5 \u2192 v0.3.7
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_16","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. f438bc6
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.4 \u2192 v0.3.5
Pre-commit: Discover typos with codespell. 2509fc7
Related to: * #168 - [pre-commit.ci] pre-commit autoupdate. be5cb79
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.3 \u2192 v0.3.4
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_17","title":"Fixes","text":"Added always_increment
attribute for parts. 53ee848
This is a requirement for CalVer to ensure they always increment with each bump, but it will work for any type. - Added CalVer function and formatting. 7a0e639
calver_format
attribute for CalVer parts.Compare the full difference.
"},{"location":"CHANGELOG/#fixes_18","title":"Fixes","text":"Fixed platform-dependent encoding. f8b4d65
encoding=\"utf-8\"
to all writes.[pre-commit.ci] pre-commit autoupdate. e92000a
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.2 \u2192 v0.3.3
Bump the github-actions group with 3 updates. a422c58
Bumps the github-actions group with 3 updates: actions/checkout, actions/setup-python and codecov/codecov-action.
Updates actions/checkout
from 3 to 4 - Release notes - Changelog - Commits
Updates actions/setup-python
from 4 to 5 - Release notes - Commits
Updates codecov/codecov-action
from 3 to 4 - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions
signed-off-by: dependabot[bot] support@github.com
Keep GitHub Actions up to date with GitHub\u2019s Dependabot. 2e55fa1
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_19","title":"Fixes","text":"Fixed bad options not returning an error code. e88f0a9
Fixes #153 - Fix issue on version.yaml. 7d14065
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_20","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. be1a568
updates: - github.com/astral-sh/ruff-pre-commit: v0.2.2 \u2192 v0.3.2
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_21","title":"Fixes","text":"Removes ability to call the CLI without subcommand. e56c944
BREAKING CHANGE: You must use bump-my-version bump
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_22","title":"Fixes","text":"Fixed \u2013ignore-missing-version and \u2013ignore-missing-files options. 7635873
The CLI options were defaulting to False
when missing. This overrode the configuration.
Fixes #140
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_23","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_24","title":"Fixes","text":"Fixed naming issue for docs. 2850aa7
Added how-to doc. 68643a9
[pre-commit.ci] pre-commit autoupdate. c495d3d
updates: - github.com/astral-sh/ruff-pre-commit: v0.2.1 \u2192 v0.2.2
Compare the full difference.
"},{"location":"CHANGELOG/#new_12","title":"New","text":"--ignore-missing-files
option to bump. fcfaac7ignore_missing_files
. b473a19Compare the full difference.
"},{"location":"CHANGELOG/#fixes_25","title":"Fixes","text":"Fix encoding when reading text. c03476a
Fixes #68
[pre-commit.ci] pre-commit autoupdate. 491b4aa
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.14 \u2192 v0.2.0
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_26","title":"Fixes","text":"Refactored VersionComponentConfig to VersionComponentSpec. b538308
More consistent with VersionSpec
[pre-commit.ci] pre-commit autoupdate. a2a3fe6
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.11 \u2192 v0.1.14
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_27","title":"Fixes","text":"Refactored serialization. 0ac2cd8
Refactored verioning models. 88e7f71
depends_on
version component configurationdepends_on
is required for PEP440 versioningCompare the full difference.
"},{"location":"CHANGELOG/#fixes_28","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_29","title":"Fixes","text":"Refactored the create subcommand. f529d28
Added show-bump
subcommand. 0bbd814
bump
commandCompare the full difference.
"},{"location":"CHANGELOG/#fixes_30","title":"Fixes","text":"Fixed extra whitespace added when updating pyproject.toml. 839f17f
get_nested_value
and set_nested_value
as replacements for dotted-notation.[pre-commit.ci] pre-commit autoupdate. ee4d2f3
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.9 \u2192 v0.1.11
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_31","title":"Fixes","text":"Fixed empty string replacement bug. d9965ab
Only a missing replacement value will trigger one of the fallback options.
Fixes #117
Compare the full difference.
"},{"location":"CHANGELOG/#new_15","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. 2e9a400
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.7 \u2192 v0.1.9
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_32","title":"Fixes","text":"Fixed testing automation. 19215f1
--no-tag
flagCompare the full difference.
"},{"location":"CHANGELOG/#fixes_33","title":"Fixes","text":"Fix miscast of current_version. b8ea252
Fixes #99
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_34","title":"Fixes","text":"Fixed regression in config update. 2bbbd74
Fixes #108
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_35","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_36","title":"Fixes","text":"Changed default regex CLI value to None. 93191f3
Fixes #64
The default value of False was overriding other values.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_37","title":"Fixes","text":"Fixed regression regarding multiple changes in one file. e7a7629
Changed the method of marking changes from a dict keyed by the file name to a list of FileChanges.
FileChanges encapsulate a single change to a file. - Refactored logging to provide indented output. 4e68214
Refactored FileConfig to FileChange. 249a999
This better describes what the class does: describe a file change.
Also moved get_search_pattern
to the class, since it is specific to each instance - Refactored config file management. a4c90b2
Moved the INI format stuff into files_legacy.py - Fixes generate-requirements.sh to upgrade. 121ef69
Changed the management of file changes. 909396d
File changes are hashable to weed out duplication. - Removed some commented lines. 89686b8
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_38","title":"Fixes","text":"Fixed issue with tag name. e218264
Fixes #74
current_version and tag_name now do not need to match exactly - Fixed logic in auto bump workflow. 909a53f
Fixes https://github.com/callowayproject/bump-my-version/issues/85. 97049e0
HG returns the tags in the order they were created so we want the last one in the list - Fixed autoversioning. a308a35
Added key_path to FileConfig. e160b40
filename
, glob
, and key_path
[pre-commit.ci] auto fixes from pre-commit.com hooks. 8188a42
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 4c81ad4
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.3 \u2192 v0.1.5
[pre-commit.ci] pre-commit autoupdate. 7109d70
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.3 \u2192 v0.1.6
Refactored configuration file updating. e407974
TOML files are parsed, specific values are updated, and re-written to avoid updating the wrong data.
It uses a two-way parser, so all formatting and comments are maintained.
INI-type configuration files use the old way, since that format is deprecated.
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_39","title":"Fixes","text":"Fix dev versioning. 1eed99b
Add -h for help option. fda71b0
Fixes #67
Drop Python3.7 as compatible version. 890edc8
Since this is no longer tested, it\u2019s safer to start at 3.8. - [pre-commit.ci] auto fixes from pre-commit.com hooks. fbcef03
for more information, see https://pre-commit.ci - Recommend calling \u2018bump-my-version\u2019 instead of \u2018bumpversion\u2019. 9fb1a1d
[pre-commit.ci] pre-commit autoupdate. e2579d6
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.290 \u2192 v0.0.292
[pre-commit.ci] pre-commit autoupdate. e21fdd9
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.290 \u2192 v0.1.1
[pre-commit.ci] pre-commit autoupdate. 7e5d1bc
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.290 \u2192 v0.1.3
Changed the default regex search to non-regex. 0034716
Fixes #59
Compare the full difference.
"},{"location":"CHANGELOG/#other_27","title":"Other","text":"[pre-commit.ci] pre-commit autoupdate. 4a3d046
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.285 \u2192 v0.0.290
Compare the full difference.
"},{"location":"CHANGELOG/#updates_19","title":"Updates","text":"Refactored file resolution, inclusion, and exclusion. 646af54
resolved_filemap
propertyfiles_to_modify
propertyCompare the full difference.
"},{"location":"CHANGELOG/#fixes_40","title":"Fixes","text":"Fixed file configuration overrides. c1ef3b2
Fixes #55
The file config was ignoring falsey values when constructing the dict.
It now ignores None
values. - Fixed documentation regarding regex config. cd71a1a
[pre-commit.ci] pre-commit autoupdate. 7c38c40
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.284 \u2192 v0.0.285
[pre-commit.ci] pre-commit autoupdate. c30bd12
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.282 \u2192 v0.0.284
[pre-commit.ci] pre-commit autoupdate. 95c89fb
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.281 \u2192 v0.0.282
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_41","title":"Fixes","text":"Fixed modified context when committing. 130bbe0
Compare the full difference.
"},{"location":"CHANGELOG/#other_29","title":"Other","text":"[pre-commit.ci] auto fixes from pre-commit.com hooks. 4b457d0
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. adb7e4c
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.277 \u2192 v0.0.281
Remove pygments_style
from docsrc/conf.py. 32798a9
The theme defaults, subjectively, look better.
Compare the full difference.
"},{"location":"CHANGELOG/#new_21","title":"New","text":"Added configuration and command-line no_regex
option. a295a32
no_regex
--no-regex
flag added for bump
and replace
sub-commandsCompare the full difference.
"},{"location":"CHANGELOG/#new_22","title":"New","text":"--ignore-missing-version
flag to bump
and replace
. a5bd008Added ignore-missing-version
configuration. 45c85be
False
--list
option will go bye-bye in 1.0bumpversion
without a subcomand will leave in 1.0Compare the full difference.
"},{"location":"CHANGELOG/#fixes_42","title":"Fixes","text":"Fix search and replace options for replace. 781e8d8
--search
and --replace
options now completely override any other search and replace logic.Fixes #34
[pre-commit.ci] pre-commit autoupdate. 531738d
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.276 \u2192 v0.0.277
[pre-commit.ci] pre-commit autoupdate. 61e6747
updates: - https://github.com/charliermarsh/ruff-pre-commit \u2192 https://github.com/astral-sh/ruff-pre-commit
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_43","title":"Fixes","text":"Fixed typing issue. bfe5306
ClassVar[List[str]]
_TEST_USABLE_COMMAND
, _COMMIT_COMMAND
, and _ALL_TAGS_COMMAND
affectedAdded replace subcommand. 8722a0f
bump
butbumpversion show new_version --increment <versionpart>
to see what the new version would beshort_branch_name
to version rendering context. 7f7e50cshort_branch_name
is the branch name, lower case, containing only a-z and 0-9, and truncated to 20 characters.Fixes #28
[pre-commit.ci] auto fixes from pre-commit.com hooks. 5e6f566
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. f1acd35
updates: - github.com/charliermarsh/ruff-pre-commit: v0.0.272 \u2192 v0.0.275
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_44","title":"Fixes","text":"Fixed --help
and bump
invocations. 9d965e5
--help
works for individual sub-commands, but not for the commandbump
now works and fixed teststomlkit.parse()
returns a TOMLDocument
.unwrap()
converts it into a dict
branch_name
to SCM information. 173be1aAdds --increment
option to show
subcommand. b01fffc
new_version
to the available output.show
subcommand. 9bce887--list
optionChanges bump-my-version into subcommands. 31ffbcf
bump-my-version
forwards command to bump-my-version bump
subcommand--help
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_45","title":"Fixes","text":"Fixes reporting the wrong version missing in a file. efb04e9
current_version
for each file being modified.[pre-commit.ci] auto fixes from pre-commit.com hooks. 5476cdf
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 6e500c2
updates: - github.com/charliermarsh/ruff-pre-commit: v0.0.270 \u2192 v0.0.272
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_46","title":"Fixes","text":"Fixed issue with formatting. da7544f
There is an underlying edge case where the deriving previous environment variables with multiple ways of formatting version numbers will fail.
Added documentation for replacing strings in different files. 893ec03
Fixes #6
Made VERSION_PART
optional. f236b7d
VERSION_PART
is detected from the arguments based on the configurationChanged exception type raised when bad version part is detected. 1e3ebc5
Fixes #7
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_47","title":"Fixes","text":"Fixes release.yaml. 01870d5
Outputs the notes to a file instead of an environment variable.
[pre-commit.ci] auto fixes from pre-commit.com hooks. 266002f
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. edc444f
updates: - github.com/charliermarsh/ruff-pre-commit: v0.0.261 \u2192 v0.0.270
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_48","title":"Fixes","text":"Fixed vague commit and tagging info. 4fb5158
[pre-commit.ci] pre-commit autoupdate. d626f7d
updates: - https://github.com/python/black \u2192 https://github.com/psf/black
Changed the version serialization. c529452
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_49","title":"Fixes","text":"Fixes issue when new version equals current version. 64b0de3
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_50","title":"Fixes","text":"Fixed issue with windows testing. b8abc44
Fixed configuration file detection. fbf85c2
Doesn\u2019t just stop when it finds one, it checks for the existence of the header. - Fixed logging output and output in general. 0aea9dc
Added new workflows. a9cac5b
Added PYTHONUTF8 mode. 91a73e2
Added files for coverage to ignore. cfbba08
Updated workflows. 857835d
Changed BaseVCS to SourceCodeManager. 11c5609
Just for consistency. - Modified the group command back to a single command. 6d4179b
Will eventually change to a group command, but later.
First off, thanks for taking the time to contribute! \u2764\ufe0f
All types of contributions are encouraged and valued. See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it much easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. \ud83c\udf89
If you like the project but don\u2019t have time to contribute, that\u2019s fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: - Star the project - Tweet about it - Refer to this project in your project\u2019s readme - Mention the project at local meetups and tell your friends/colleagues
"},{"location":"CONTRIBUTING/#table-of-contents","title":"Table of Contents","text":"This project and everyone participating in it are governed by the Bump My Version Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to coreyoordt@gmail.com.
"},{"location":"CONTRIBUTING/#i-have-a-question","title":"I Have a Question","text":"If you want to ask a question, we assume that you have read the available Documentation.
Before you ask a question, it is best to search for existing Issues that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
If you then still feel the need to ask a question and need clarification, we recommend the following:
We will then take care of the issue as soon as possible.
"},{"location":"CONTRIBUTING/#reporting-bugs","title":"Reporting Bugs","text":""},{"location":"CONTRIBUTING/#before-submitting-a-bug-report","title":"Before Submitting a Bug Report","text":"A good bug report shouldn\u2019t leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information, and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.
You must never report security-related issues, vulnerabilities, or bugs that include sensitive information to the issue tracker or elsewhere in public. Instead, sensitive bugs must be sent by email to coreyoordt@gmail.com.
We use GitHub issues to track bugs and errors. If you run into an issue with the project:
Once it\u2019s filed:
This section guides you through submitting an enhancement suggestion for Bump My Version, including completely new features and minor improvements to existing functionality. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
"},{"location":"CONTRIBUTING/#before-submitting-an-enhancement","title":"Before Submitting an Enhancement","text":"Enhancement suggestions are tracked as GitHub issues.
When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.
"},{"location":"CONTRIBUTING/#setup","title":"Setup","text":"There are several ways to create an isolated Python development environment. This is the default method.
Run the following in a terminal:
# Clone the repository\ngit clone https://github.com/callowayproject/bump-my-version.git\n\n# Enter the repository\ncd bump-my-version\n\n# Create, then activate a virtual environment\npython -m venv env\nsource env/bin/activate\n\n# Install the project in editable mode with its optional dependencies\npython -m pip install -e .[dev,test]\n
"},{"location":"CONTRIBUTING/#run-tests","title":"Run tests","text":"Once setup, you should be able to run tests:
pytest\n
"},{"location":"CONTRIBUTING/#install-pre-commit-hooks","title":"Install Pre-commit Hooks","text":"Pre-commit hooks are scripts that run every time you make a commit. If any of the scripts fail, it stops the commit. You can see a listing of the checks in the .pre-commit-config.yaml
file.
pre-commit install\n
"},{"location":"CONTRIBUTING/#improving-the-documentation","title":"Improving The Documentation","text":"Please, please help us here.
"},{"location":"CONTRIBUTING/#styleguides","title":"Styleguides","text":""},{"location":"CONTRIBUTING/#coding-style","title":"Coding Style","text":"All of the basic coding styles are configured into tools for fixing and checking them. Pre-commit is used to automate the process.
"},{"location":"CONTRIBUTING/#commit-messages","title":"Commit Messages","text":"Commit messages are used to generate the change log.
New changes
Commit messages are categorized as \u201cnew\u201d if the commit message starts with:
For example: Added this cool new feature
or New document type added
.
Updates
Commit messages are categorized as \u201cupdates\u201d if the commit message starts with:
For example: Modified the taxonomy schema
or Improves performance by 419%
Fixes
Commit messages are categorizes as \u201cfixes\u201d if the commit message starts with:
For example: Fixes bug #123
Other
All other commit messages are categorized as \u201cother.\u201d
Ignoring commit messages
To have the change log generator ignore this commit, add to the summary line:
@minor
!minor
@cosmetic
!cosmetic
@refactor
!refactor
@wip
!wip
If you would like to be a maintainer, reach out to coreyoordt@gmail.com.
"},{"location":"CONTRIBUTING/#attribution","title":"Attribution","text":"This guide is based on the contributing-gen. Make your own!
"},{"location":"explanation/","title":"Index","text":"There are four main concepts in Bump My Version:
The predecessor to Bump My Version, bumpversion, was designed to have the configuration file optional. All configuration values could be specified on the command line. This only worked in the simplest of version schemes.
While Bump My Version can do many things without a configuration file, it is designed to have a configuration file. The configuration file is required to specify the version scheme. The configuration file also specifies the files to change and how to change them.
"},{"location":"explanation/mental-model/#version-handling","title":"Version handling","text":"Bump My Version abstracts the version handling into a few concepts:
A version spec defines the rules for incrementing a version.
A version component spec defines how a single part of a version spec, such as major
, minor
, or patch
, works. It defines the types of values, how to increment the component, and how to reset it.
A version parser is a regular expression used in several ways. Its named capture groups define the possible components in a version spec and the order in which they appear. It also parses a version string into version component names and their values.
A version is the concrete representation of a version spec. It is a mapping of version component names to version components.
A version component is the concrete representation of a version component spec. It is a version component spec with a specific value.
A version serialization format is a list of format strings used to serialize a version into a string.
"},{"location":"explanation/mental-model/#how-a-version-spec-is-generated","title":"How a version spec is generated","text":"How a configuration file is used to generate a version spec.The most important part of the configuration file is the version parser. It defines the structure of the version spec.
If the configuration file contains a version component spec that matches a named capture group in the version parser, then that version component spec is used in the version spec. The yellow and green named capture groups in the diagram demonstrate this.
If the configuration file does not contain a version component spec that matches a named capture group in the version parser, then a default version component spec is used. The blue named capture group in the diagram demonstrates this.
The component dependency graph determines the order in which the version components are incremented and reset. For example, in the diagram, the patch component depends on the minor component, which depends on the major
component. Therefore, when the major
component is incremented, the minor
component is reset, which cascades to the patch
component.
The version spec has a create_version
method that takes a mapping of version component names to values.
Each version component spec has a create_component
method that takes a value. The create_version
method calls the create_component
method for each version component spec in the version spec with the value from the mapping.
The create_component
assembles its version spec_ with the version components to create a version.
Optional value rule. Version component specs can define an optional value. For example, numeric components have 0
as an optional value. Optional values may be omitted from the serialization as long as all dependent components also have optional values.
Required value rule. Version component specs is required if its value or the value of any of its dependent components is not optional.
A valid serialization contains all the required components in the version spec based on the required value rule.
An invalid serialization does not contain all the required components in the version spec based on the required value rule.
The optimal serialization is the valid serialization that uses the fewest components.
The serialize
method of the version spec returns either the optimal serialization or the first invalid serialization.
No optional values
In this example, the major
component is 1
, the minor
component is 2
, and patch
component is 3
. Since none of the values are optional (0
), only one serialization format is valid. This one valid format is the optimal format.
One optional value
A version with values major=1, minor=2, and patch=0 has two valid serializations. The optimal serialization is the one that uses the fewest components. 1.2
in this example.
Two optional values
A version with values major=1, minor=0, and patch=0 has three valid serializations. The optimal serialization is the one that uses the fewest components. 1
in this example.
No valid serialization options
A version with values major=1, minor=2, and patch=3 has no valid serializations in this example. The serialize
method returns the first invalid serialization.
The main purpose of the show
subcommand is to provide access to configuration data via scripts.
The configuration object is a dict
containing nested data structures. The arguments and options of this command relate to extracting data from the configuration object and presenting the extracted data.
The positional arguments determine the data shown. If nothing or all
is passed, the entire configuration is shown.
Positional arguments are specified using a format like Django variable resolution.
Examples:
a.b
specifies the \u201cb\u201d key in the nested dictionaries: {\"a\": {\"b\": \"value\"}}
a.3
specifies the 4th item (the first is 0) of the list at key \u201ca\u201d: {\"a\": [\"no\", \"nay\", \"nyet\", \"value\"]}
If only one positional argument is passed, the default format only shows its value. If no positional arguments, several positional arguments, or all
is passed, the output from pprint.pprint
is shown.
This makes getting the current version easy:
$ bump-my-version show current_version\n1.0.1\n
You can request the output be formatted as YAML or JSON:
$ bump-my-version show --format yaml current_version\ncurrent_version: \"1.0.1\"\n$ bump-my-version show --format json current_version\n{\n \"current_version\": \"1.0.1\"\n}\n
"},{"location":"explanation/show-subcommand/#including-the-incremented-version-before-bumping","title":"Including the incremented version before bumping","text":"Your workflow might want to know the new version before you actually do the bumping. The --increment
or -i
option accepts a version part to bump and adds a new_version
key into the configuration.
$ bump-my-version --increment patch show\n1.0.2\n$ bump-my-version --increment minor show\n1.1.0\n$ bump-my-version --increment major show\n2.0.0\n
"},{"location":"explanation/version-parts/","title":"Version components","text":"A version configuration consists of the following:
A version string consists of one or more parts; e.g., version 1.0.2
has three parts, separated by a dot (.
) character.
The names of these parts are defined in the named groups within the parse
regular expression. The default configuration calls them major, minor, and patch.
The serialize
configuration value is a list of default formats. You have the option for multiple serialization formats to omit optional values. For example, the following configuration:
serialize = [\n \"{major}.{minor}.{patch}\",\n \"{major}.{minor}\",\n]\n
Bump-my-version will serialize using the first format if the patch
value is not 0
. If the patch
value is 0
, Bump My Version will use the second format.
A version part configuration consists of the following:
There are two incrementing functions: numeric and value. The numeric function uses integer values and returns the next integer value. The values function uses a sequence of values and returns the next value until finished.
By default, parts use the numeric function starting at 0.
You can configure a part using the values function by providing a list of values in the version part\u2019s configuration. For example, for the release_name
part:
[tool.bumpversion.parts.release_name]\nvalues = [\n \"witty-warthog\", \n \"ridiculous-rat\", \n \"marvelous-mantis\",\n]\n
"},{"location":"explanation/version-parts/#optional-values","title":"Optional values","text":"By default, the first value of a version part is considered optional. An optional value may be omitted from the version serialization. Using the example from above:
serialize = [\n \"{major}.{minor}.{patch}\",\n \"{major}.{minor}\",\n]\n
Version 1.4.0
is rendered as 1.4
since the patch
is 0
; as the first value, it is optional.
Optional values are helpful for non-numeric version parts that indicate development stages, such as alpha or beta.
Example:
[tool.bumpversion]\ncurrent_version = \"1.0.0\"\nparse = \"\"\"(?x)\n (?P<major>[0-9]+)\n \\\\.(?P<minor>[0-9]+)\n \\\\.(?P<patch>[0-9]+)\n (?:\n -(?P<pre_label>alpha|beta|stable)\n (?:-(?P<pre_n>[0-9]+))?\n )?\n\"\"\"\nserialize = [\n \"{major}.{minor}.{patch}-{pre_label}-{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\n\n[tool.bumpversion.parts.pre_label]\noptional_value = \"stable\"\nvalues =[\n \"alpha\",\n \"beta\",\n \"stable\",\n]\n
Bumping the patch
part of version 1.0.0
would change the version to 1.0.1-alpha-0
. Bumping the pre_label
part would change the version to 1.0.1-beta-0
. Bumping the pre_label
part again would change the version to 1.0.1
. The stable-0
is not serialized because both stable
and 0
are optional.
You can specify the starting number with the first_value configuration for numeric version parts.
For example, if we added the following to the above configuration:
[tool.bumpversion.parts.pre_n]\nfirst_value = \"1\"\n
Bumping the patch
value of version 1.0.0
would change the version to 1.0.1-alpha-1
instead of 1.0.1-alpha-0
.
In the pattern {major}.{minor}.{patch}-{pre_label}-{pre_n}
, each version part resets to its first value when the element preceding it changes. All these version parts are dependent.
You can include a value that incremented independently from the other parts, such as a build
part: {major}.{minor}.{patch}-{pre_label}-{pre_n}+{build}
\u2014in the configuration for that part, set independent=true
.
[tool.bumpversion.parts.build]\nindependent = true\n
"},{"location":"explanation/version-parts/#reference","title":"Reference","text":"In files that have multiple version strings, Bump My Version may find the wrong string and replace it. Given this requirements.txt
for MyProject
:
Django>=1.5.6,<1.6\nMyProject==1.5.6\n
The default search and replace templates will replace the wrong text. Instead of changing MyProject
\u2019s version from 1.5.6
to 1.6.0
, it changes Django
\u2019s version:
Django>=1.6.0,<1.6\nMyProject==1.5.6\n
Providing search and replace templates for the requirements.txt
file will avoid this.
This .bumpversion.toml
will ensure only the line containing MyProject
will be changed:
[tool.bumpversion]\ncurrent_version = \"1.5.6\"\n\n[[tool.bumpversion.files]]\nfilename = \"requirements.txt\"\nsearch = \"MyProject=={current_version}\"\nreplace = \"MyProject=={new_version}\"\n
If the string to be replaced includes literal quotes, the search and replace patterns must include them to match. Given the file version.sh
:
MY_VERSION=\"1.2.3\"\n
Then the following search and replace patterns (including quotes) would be required:
[[tool.bumpversion.files]]\nfilename = \"version.sh\"\nsearch = \"MY_VERSION=\\\"{current_version}\\\"\"\nreplace = \"MY_VERSION=\\\"{new_version}\\\"\"\n
"},{"location":"howtos/calver/","title":"Using Calendar Versioning (CalVer)","text":"Calendar Versioning (CalVer) is a versioning scheme that uses a date-based version number.
For this example, we will use the following format: YYYY.MM.DD.patch
. It will yield numbers like:
2022.2.1
for the first patch of February 1, 20222022.2.1.1
for the second patch of February 1, 2022[tool.bumpversion]\ncurrent_version = \"2024.3.1.4\"\nparse = \"\"\"(?x) # Verbose mode\n (?P<release> # The release part\n (?:[1-9][0-9]{3})\\\\. # YYYY.\n (?:1[0-2]|[1-9])\\\\. # MM.\n (?:3[0-1]|[1-2][0-9]|[1-9]) # DD\n )\n (?:\\\\.(?P<patch>\\\\d+))? # .patch, optional\n\"\"\"\nserialize = [\"{release}.{patch}\", \"{release}\"]\n\n[tool.bumpversion.parts.release]\ncalver_format = \"{YYYY}.{MM}.{DD}\"\n
You can look up the regular expressions for the CalVer format in the CalVer reference.
"},{"location":"howtos/calver/#expected-behavior","title":"Expected behavior","text":"always_increment
by default.always_increment
are incremented first.always_increment
component\u2019s value changed, its dependent components are marked for reset to their default values.When you bump the calendar version, the patch is reset to 0 even if the release did not change.
Bumping the release resets patch$ date -I \n2024-03-1\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.1\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.1.5\n
The next day:
Bumping the release resets patch, the next day$ date -I \n2024-03-2\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.2\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.2\n
"},{"location":"howtos/calver/#the-result-of-a-bump-to-patch-depends-on-the-date","title":"The result of a bump to patch depends on the date","text":"Calendar Versioned parts are updated with every bump, regardless of the part being bumped. If you are bumping the version within the same time period (in this example, the same day), the release
part will not change. So bumping the patch
part will increment the patch
part only.
$ date -I \n2024-03-1\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.1\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.1.5\n
However, if you bump the version on the next day, the release
part will also be updated.
$ date -I \n2024-03-2\n$ bump-my-version show-bump\n2024.3.1.4 \u2500\u2500 bump \u2500\u252c\u2500 release \u2500 2024.3.2\n \u2570\u2500 patch \u2500\u2500\u2500 2024.3.2\n
"},{"location":"howtos/custom-version-formats-by-file/","title":"Custom version formats in different files","text":"You can use file configurations to replace the version in multiple files, even if each file has the version formatted differently.
In a module-aware Go project, when you create a major version of your module beyond v1
, your module name must include the major version number (e.g., github.com/myorg/myproject/v2
). However, you also have the full version in a YAML file named release-channels.yaml
.
go.mod
file:
module github.com/myorg/myproject/v2\n\ngo 1.12\n\nrequire (\n ...\n)\n
release-channels.yaml
file:
stable: \"v2.21.4\"\n
You can use Bump My Version to maintain the major version number within the go.mod
file by using the parse
and serialize
options, as in this example:
.bumpversion.toml
file:
[tool.bumpversion]\ncurrent_version = \"2.21.4\"\n\n[[tool.bumpversion.files]]\nfilename = \"go.mod\"\nparse = \"(?P<major>\\\\d+)\"\nserialize = \"{major}\"\nsearch = \"module github.com/myorg/myproject/v{current_version}\"\nreplace = \"module github.com/myorg/myproject/v{new_version}\"\n\n[[tool.bumpversion.files]]\nfilename = \"release-channels.yaml\"\n
While all the version bumps are minor
or patch
, the go.mod
file doesn\u2019t change, while the release-channels.yaml
file will. As soon as you do a major
version bump, the go.mod
file now contains this module directive:
module github.com/myorg/myproject/v3\n
"},{"location":"howtos/multiple-replacements/","title":"Multiple replacements within the same file","text":"To make several replacements in the same file, you must configure multiple [[tool.bumpversion.files]]
sections for the same file with different configuration options.
In this example, the changelog is generated before the version bump. It uses Unreleased
as the heading and includes a link to GitHub to compare this version (HEAD
) with the previous version.
To change Unreleased
to the current version, we have an entry with search
set to Unreleased
. The default replace
value is {new_version}
, so changing it is unnecessary.
To change the link, another entry has its search
set to {current_version}...HEAD
and the replace
set to {current_version}...{new_version}
.
[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"Unreleased\"\n\n[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"{current_version}...HEAD\"\nreplace = \"{current_version}...{new_version}\"\n
"},{"location":"howtos/nav/","title":"Nav","text":"Many times when bumping a version, you will also want to update a date in a file. This is a common use case for changelogs, but it could be any file that contains a date. In this example, we have an __init__.py
that looks like this:
__date__ = '2022-12-19'\n__version__ = '0.4.0'\n
The desired outcome is to update the date to the current date. For example, if today is February 23, 2024, the init.py file should look like this after a minor
bump:
__date__ = '2024-02-23'\n__version__ = '0.5.0'\n
"},{"location":"howtos/update-a-date/#setting-up-the-file-configurations","title":"Setting up the file configurations","text":"We need Bump My Version to update the __init__.py
file twice: once for the version and once for the date. Here is the necessary configuration:
[[tool.bumpversion.files]]\nfilename = '__init__.py'\nsearch = \"__date__ = '\\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}'\"\nreplace = \"__date__ = '{now:%Y-%m-%d}'\"\nregex = true\n\n[[tool.bumpversion.files]]\nfilename = '__init__.py'\n
"},{"location":"reference/","title":"Index","text":"The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to define the version format in the calver_format
configuration options. Formatting codes, surrounded by { }
can be combined to create a custom version format. For example, the format YYYY.MM.DD
can be defined as \"{YYYY}.{MM}.{DD}\"
.
YYYY
2000, 2001, \u2026, 2099 Full year YY
0, 1, 2, \u2026, 99 Short year as integer 0Y
00, 01, 02, \u2026, 99 Short Year, zero-padded MMM
Jan, Feb, jan, f\u00e9v Month abbreviation, locale-based MM
1, 2, \u2026, 12 Month as integer 0M
01, 02, \u2026, 12 Month, zero-padded DD
1, 2, \u2026, 31 Day of month as integer 0D
01, 02, \u2026, 31 Day of month, zero-padded JJJ
1, 2, 3, \u2026, 366 Day of year as integer 00J
001, 002, \u2026, 366 Day of year, zero-padded Q
1, 2, 3, 4 Quarter WW
0, 1, 2, \u2026, 53 Week number, Monday is first day 0W
00, 01, 02, \u2026, 53 Week number, Monday is first day, zero-padded UU
0, 1, 2, \u2026, 53 Week number, Sunday is first day 0U
00, 01, 02, \u2026, 53 Week number, Sunday is first day, zero-padded VV
1, 2, \u2026, 53 ISO 8601 week number as integer 0V
01, 02, \u2026, 53 ISO 8601 week number, zero-padded GGGG
2000, 2001, \u2026, 2099 ISO 8601 week-based year GG
0, 1, 2, \u2026, 99 ISO 8601 short week-based year as integer 0G
01, 02, \u2026, 99 ISO 8601 short week-based year, zero-padded Example configuration[tool.bumpversion.parts.release]\ncalver_format = \"{YYYY}.{MM}.{DD}\"\n
"},{"location":"reference/calver_reference/#parsing-calver-versions","title":"Parsing CalVer versions","text":"Using the following chart, we can set up the version parsing:
Code RegexYYYY
(?:[1-9][0-9]{3})
YY
(?:[1-9][0-9]?)
0Y
(?:[0-9]{2})
MMM
See below MM
(?:1[0-2]\\|[1-9])
0M
(?:1[0-2]\\|0[1-9])
DD
(?:3[0-1]\\|[1-2][0-9]\\|[1-9])
0D
(?:3[0-1]\\|[1-2][0-9]\\|0[1-9])
JJJ
(?:36[0-6]\\|3[0-5][0-9]\\|[1-2][0-9][0-9]\\|[1-9][0-9]\\|[1-9])
00J
(?:36[0-6]\\|3[0-5][0-9]\\|[1-2][0-9][0-9]\\|0[1-9][0-9]\\|00[1-9])
Q
(?:[1-4])
WW
(?:5[0-3]\\|[1-4][0-9]\\|[0-9])
0W
(?:5[0-3]\\|[0-4][0-9])
UU
(?:5[0-3]\\|[1-4][0-9]\\|[0-9])
0U
(?:5[0-3]\\|[0-4][0-9])
VV
(?:5[0-3]\\|[1-4][0-9]\\|[1-9])
0V
(?:5[0-3]\\|[1-4][0-9]\\|0[1-9])
GGGG
(?:[1-9][0-9]{3})
GG
(?:[0-9][0-9]?)
0G
(?:[0-9]{2})
Month abbreviations
The month abbreviation is locale-based. Here are some examples:
(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
for English
(?:jan|f\u00e9v|mar|avr|mai|jui|jui|ao\u00fb|sep|oct|nov|d\u00e9c)
for French
You can use these regular expressions to parse CalVer versions in your project. For example, the following parse
configuration can be used to parse a version string in the format YYYY.MM.DD
as the release
part of the version string:
[tool.bumpversion]\nparse = \"\"\"(?x) # Verbose mode\n (?P<release>\n (?:[1-9][0-9]{3})\\\\. # YYYY.\n (?:1[0-2]|[1-9])\\\\. # MM.\n (?:3[0-1]|[1-2][0-9]|[1-9]) # DD\n )\n\"\"\"\n
"},{"location":"reference/cli/","title":"CLI Reference","text":""},{"location":"reference/cli/#bump-my-version","title":"bump-my-version","text":"Version bump your Python project.
Usage:
bump-my-version [OPTIONS] COMMAND [ARGS]...\n
Options:
Name Type Description Default--version
boolean Show the version and exit. False
--help
boolean Show this message and exit. False
Subcommands
Change the version.
ARGS may contain any of the following:
VERSION_PART is the part of the version to increase, e.g. minor
. Valid values include those given in the --serialize
/ --parse
option.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
Usage:
bump-my-version bump [OPTIONS] [ARGS]...\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None -v
, --verbose
integer range (0
and above) Print verbose logging to stderr. Can specify several times for more verbosity. 0
--allow-dirty
/ --no-allow-dirty
boolean Don\u2019t abort if working directory is dirty, or explicitly abort if dirty. None --current-version
text Version that needs to be updated None --new-version
text New version that should be in the files None --parse
text Regex parsing the version string None --serialize
text How to format what is parsed back to a version None --search
text Template for complete string to search None --replace
text Template for complete string to replace None --regex
/ --no-regex
boolean Treat the search parameter as a regular expression or explicitly do not treat it as a regular expression. None --no-configured-files
boolean Only replace the version in files specified on the command line, ignoring the files from the configuration file. False
--ignore-missing-files
/ --no-ignore-missing-files
boolean Ignore any missing files when searching and replacing in files. None --ignore-missing-version
/ --no-ignore-missing-version
boolean Ignore any Version Not Found errors when searching and replacing in files. None --dry-run
, -n
boolean Don\u2019t write any files, just pretend. False
--commit
/ --no-commit
boolean Commit to version control None --tag
/ --no-tag
boolean Create a tag in version control None --sign-tags
/ --no-sign-tags
boolean Sign tags if created None --tag-name
text Tag name (only works with \u2013tag) None --tag-message
text Tag message None -m
, --message
text Commit message None --commit-args
text Extra arguments to commit command None --help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-replace","title":"bump-my-version replace","text":"Replace the version in files.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
Usage:
bump-my-version replace [OPTIONS] [FILES]...\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None -v
, --verbose
integer range (0
and above) Print verbose logging to stderr. Can specify several times for more verbosity. 0
--allow-dirty
/ --no-allow-dirty
boolean Don\u2019t abort if working directory is dirty, or explicitly abort if dirty. None --current-version
text Version that needs to be updated None --new-version
text New version that should be in the files. If not specified, it will be None. None --parse
text Regex parsing the version string None --serialize
text How to format what is parsed back to a version None --search
text Template for complete string to search None --replace
text Template for complete string to replace None --regex
/ --no-regex
boolean Treat the search parameter as a regular expression or explicitly do not treat it as a regular expression. False
--no-configured-files
boolean Only replace the version in files specified on the command line, ignoring the files from the configuration file. False
--ignore-missing-version
boolean Ignore any Version Not Found errors when searching and replacing in files. False
--ignore-missing-files
boolean Ignore any missing files when searching and replacing in files. False
--dry-run
, -n
boolean Don\u2019t write any files, just pretend. False
--help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-sample-config","title":"bump-my-version sample-config","text":"Print a sample configuration file.
Usage:
bump-my-version sample-config [OPTIONS]\n
Options:
Name Type Description Default--prompt
/ --no-prompt
boolean Ask the user questions about the configuration. True
--destination
choice (stdout
| .bumpversion.toml
| pyproject.toml
) Where to write the sample configuration. stdout
--help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-show","title":"bump-my-version show","text":"Show current configuration information.
ARGS may contain one or more configuration attributes. For example:
bump-my-version show current_version
bump-my-version show files.0.filename
bump-my-version show scm_info.branch_name
bump-my-version show current_version scm_info.distance_to_latest_tag
Usage:
bump-my-version show [OPTIONS] [ARGS]...\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None -f
, --format
choice (default
| yaml
| json
) Specify the output format. default
-i
, --increment
text Increment the version component and add new_version
to the configuration. None --help
boolean Show this message and exit. False
"},{"location":"reference/cli/#bump-my-version-show-bump","title":"bump-my-version show-bump","text":"Show the possible versions resulting from the bump subcommand.
Usage:
bump-my-version show-bump [OPTIONS] [VERSION]\n
Options:
Name Type Description Default--config-file
path Config file to read most of the variables from. None --ascii
boolean Use ASCII characters only. False
-v
, --verbose
integer range (0
and above) Print verbose logging to stderr. Can specify several times for more verbosity. 0
--help
boolean Show this message and exit. False
"},{"location":"reference/formatting-context/","title":"Formatting context","text":"These fields are available for
#
The literal hash or octothorpe character. ;
The literal semicolon character."},{"location":"reference/formatting-context/#date-and-time-fields","title":"Date and time fields","text":"now
A Python datetime object representing the current local time, without a time zone reference. utcnow
A Python datetime object representing the current local time in the UTC time zone. You can provide additional formatting guidance for datetime objects using formatting codes. Put the formatting codes after the field and a colon. For example, {now:%Y-%m-%d}
would output the current local time as 2023-04-20
.
These fields will only have values if the code is in a Git or Mercurial repository.
commit_sha
The latest commit reference. distance_to_latest_tag
The number of commits since the latest tag. dirty
A boolean indicating if the current repository has pending changes. branch_name
The current branch name. short_branch_name
The current branch name, converted to lowercase, with non-alphanumeric characters removed and truncated to 20 characters. For example, feature/MY-long_branch-name
would become featuremylongbranchn
."},{"location":"reference/formatting-context/#version-fields","title":"Version fields","text":"current_version
The current version serialized as a string current_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have current_major
, current_minor
, and current_patch
available. new_version
The new version serialized as a string new_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have new_major
, new_minor
, and new_patch
available. Note
The following fields are only available when serializing a version.
<version component>
Each version part defined by the version configuration parsing regular expression. The default configuration would have major
, minor
, and patch
available."},{"location":"reference/formatting-context/#environment-variables","title":"Environment variables","text":"Every environment variable available at runtime is included with a $
prefix. For example if USER
was in the environment, {$USER}
would render that value.
Tip
If you use environment variables in your version serialization, you might want to ensure they are set by executing export VAR=value
before running the bump-my-version
command.
A hook suite is a list of hooks to run sequentially. A hook is either an individual shell command or an executable script.
There are three hook suites: setup, pre-commit, and post-commit. During the version increment process this is the order of operations:
Note
Don\u2019t confuse the pre-commit and post-commit hook suites with Git pre- and post-commit hooks. Those hook suites are named for their adjacency to the commit and tag operation.
"},{"location":"reference/hooks/#configuration","title":"Configuration","text":"Configure each hook suite with the setup_hooks
, pre_commit_hooks
, or post_commit_hooks
keys.
Each suite takes a list of strings. The strings may be individual commands:
Calling individual commands[tool.bumpversion]\nsetup_hooks = [\n \"git config --global user.email \\\"bump-my-version@github.actions\\\"\",\n \"git config --global user.name \\\"Testing Git\\\"\",\n \"git --version\",\n \"git config --list\",\n]\npre_commit_hooks = [\"cat CHANGELOG.md\"]\npost_commit_hooks = [\"echo Done\"]\n
or the path to an executable script:
Calling a shell script[tool.bumpversion]\nsetup_hooks = [\"path/to/setup.sh\"]\npre_commit_hooks = [\"path/to/pre-commit.sh\"]\npost_commit_hooks = [\"path/to/post-commit.sh\"]\n
Note
You can make a script executable using the following steps:
#!/bin/bash
chmod u+x path/to/script.sh
to set the executable bitEach hook has these environment variables set when executed.
"},{"location":"reference/hooks/#inherited-environment","title":"Inherited environment","text":"All environment variables set before bump-my-version was run are available.
"},{"location":"reference/hooks/#date-and-time-fields","title":"Date and time fields","text":"BVHOOK_NOW
The ISO-8601-formatted current local time without a time zone reference. BVHOOK_UTCNOW
The ISO-8601-formatted current local time in the UTC time zone."},{"location":"reference/hooks/#source-code-management-fields","title":"Source code management fields","text":"Note
These fields will only have values if the code is in a Git or Mercurial repository.
BVHOOK_COMMIT_SHA
The latest commit reference. BHOOK_DISTANCE_TO_LATEST_TAG
The number of commits since the latest tag. BVHOOK_IS_DIRTY
A boolean indicating if the current repository has pending changes. BVHOOK_BRANCH_NAME
The current branch name. BVHOOK_SHORT_BRANCH_NAME
The current branch name, converted to lowercase, with non-alphanumeric characters removed and truncated to 20 characters. For example, feature/MY-long_branch-name
would become featuremylongbranchn
."},{"location":"reference/hooks/#current-version-fields","title":"Current version fields","text":"BVHOOK_CURRENT_VERSION
The current version serialized as a string BVHOOK_CURRENT_TAG
The current tag BVHOOK_CURRENT_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have BVHOOK_CURRENT_MAJOR
, BVHOOK_CURRENT_MINOR
, and BVHOOK_CURRENT_PATCH
available."},{"location":"reference/hooks/#new-version-fields","title":"New version fields","text":"Note
These are not available in the setup hook suite.
BVHOOK_NEW_VERSION
The new version serialized as a string BVHOOK_NEW_TAG
The new tag BVHOOK_NEW_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have BVHOOK_NEW_MAJOR
, BVHOOK_NEW_MINOR
, and BVHOOK_NEW_PATCH
available."},{"location":"reference/hooks/#outputs","title":"Outputs","text":"The stdout
and stderr
streams are echoed to the console if you pass the -vv
option.
Bump my version does not execute any hooks during a dry run. With the verbose output option it will state which hooks it would have run.
"},{"location":"reference/search-and-replace-config/","title":"Search and replace configuration","text":"Bump-my-version uses a combination of template strings using a formatting context and regular expressions to search the configured files for the old or current version and replace the text with the new version.
Bump My Version defaults to using a simple string search. If the search template is not a valid regular expression or if the no-regex
flag is True
. The search template is always rendered using the formatting context. The basic logic is:
no-regex
flag is True
, use the search string rendered with the unescaped context.Both the search and replace templates are rendered using the formatting context. However, only the search template is also treated as a regular expression. The replacement fields available in the formatting context are enclosed in curly braces {}
.
The search and replace templates can be multiple lines, like so:
[tool.bumpversion]\ncurrent_version = \"1.2.3\"\n\n[[tool.bumpversion.files]]\nfilename = \"config.ini\"\nsearch = \"[myproject]\\nversion={current_version}\"\nreplace = \"[myproject]\\nversion={new_version}\"\n
Alternatively, using TOML\u2019s multiline strings:
[tool.bumpversion]\ncurrent_version = \"1.2.3\"\n\n[[tool.bumpversion.files]]\nfilename = \"config.ini\"\nsearch = \"\"\"\n[myproject]\nversion={current_version}\"\"\"\n\nreplace = \"\"\"\n[myproject]\nversion={new_version}\"\"\"\n
"},{"location":"reference/search-and-replace-config/#using-regular-expressions","title":"Using regular expressions","text":"Only the search template will use Python\u2019s regular expression syntax with minor changes. The template string is rendered using the formatting context. The resulting string is treated as a regular expression for searching unless configured otherwise.
Curly braces ({}
) must be doubled in the regular expression to escape them from the string-formatting process.
If you are using a TOML-formatted configuration file, you must also escape backslashes (\\
) in the regular expression. The TOML parser will treat a single backslash as an escape character.
The following template:
TOMLCFGsearch = \"{current_version} date-released: \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\"\n
search = \"{current_version} date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}\"\n
Gets rendered to:
1\\.2\\.3 date-released: \\d{4}-\\d{2}-\\d{2}\n
This string is used as a regular expression pattern to search.
"},{"location":"reference/search-and-replace-config/#regular-expression-special-characters","title":"Regular expression special characters","text":"The .
, ^
, $
, *
, +
, ?
, ()
, []
, {}
, \\
, |
characters are special characters in regular expressions. If your search string contains these characters, you must escape them with a backslash (\\
) to treat them as literal characters or set the no-regex
flag to True
.
For example, if you are looking for this string in a file:
[Unreleased] 2023-07-17\n
and you use this search pattern:
[Unreleased] \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\n
Bump My Version will not find the string. While the rendered regular expression [Unreleased] \\d{4}-\\d{2}-\\d{2}
is valid, it is not searching for the literal [Unreleased]
. Instead, it matches a single character in the list U
, n
, r
, e
, l
, a
, s
, d
.
You must escape the [
and ]
to treat them as literal characters:
\\[Unreleased\\] \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\n
"},{"location":"reference/api/nav/","title":"Nav","text":"
aliases","text":"Utilities for handling command aliases.
"},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases.AliasedGroup","title":"AliasedGroup","text":" Bases: RichGroup
This following example implements a subclass of Group that accepts a prefix for a command.
If there were a command called push
, it would accept pus
as an alias (so long as it was unique)
get_command(\n ctx: Context, cmd_name: str\n) -> Optional[click.Command]\n
Given a context and a command name, this returns a Command object if it exists or returns None.
"},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases.AliasedGroup.resolve_command","title":"resolve_command","text":"resolve_command(ctx: Context, args: List[str]) -> tuple\n
Find the command and make sure the full command name is returned.
"},{"location":"reference/api/bumpversion/aliases/#bumpversion.aliases-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/autocast/","title":"
autocast","text":"Automatically detect the true Python type of a string and cast it to the correct type.
Based on https://github.com/cgreer/cgAutoCast/blob/master/cgAutoCast.py
Only used by Legacy configuration file parser.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.autocast_value","title":"autocast_value","text":"autocast_value(var: Any) -> Any\n
Guess the string representation of the variable\u2019s type.
Parameters:
var
Value to autocast.
TYPE: Any
Returns:
Any
The autocasted value.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.boolify","title":"boolify","text":"boolify(s: str) -> bool\n
Convert a string to a boolean.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.listify","title":"listify","text":"listify(s: str) -> list\n
Convert a string representation of a list into list of homogeneous basic types.
Type of elements in list is determined via first element. Successive elements are cast to that type.
Parameters:
s
String representation of a list.
TYPE: str
Raises:
ValueError
If string does not represent a list.
TypeError
If string does not represent a list of homogeneous basic types.
Returns:
list
List of homogeneous basic types.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.noneify","title":"noneify","text":"noneify(s: str) -> None\n
Convert a string to None.
"},{"location":"reference/api/bumpversion/bump/","title":"
bump","text":"Version changing methods.
"},{"location":"reference/api/bumpversion/bump/#bumpversion.bump-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/bump/#bumpversion.bump-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/bump/#bumpversion.bump.commit_and_tag","title":"commit_and_tag","text":"commit_and_tag(\n config: Config,\n config_file: Optional[Path],\n configured_files: List[ConfiguredFile],\n ctx: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Commit and tag the changes if a tool is configured.
Parameters:
config
The configuration
TYPE: Config
config_file
The configuration file to include in the commit, if it exists
TYPE: Optional[Path]
configured_files
A list of files to commit
TYPE: List[ConfiguredFile]
ctx
The context used to render the tag and tag message
TYPE: MutableMapping
dry_run
True if the operation should be a dry run
TYPE: bool
DEFAULT: False
do_bump(\n version_part: Optional[str],\n new_version: Optional[str],\n config: Config,\n config_file: Optional[Path] = None,\n dry_run: bool = False,\n) -> None\n
Bump the version_part to the next value or set the version to new_version.
Parameters:
version_part
The name of the version component to bump
TYPE: Optional[str]
new_version
The explicit version to set
TYPE: Optional[str]
config
The configuration to use
TYPE: Config
config_file
The configuration file to update
TYPE: Optional[Path]
DEFAULT: None
dry_run
True if the operation should be a dry run
TYPE: bool
DEFAULT: False
get_next_version(\n current_version: Version,\n config: Config,\n version_part: Optional[str],\n new_version: Optional[str],\n) -> Version\n
Bump the version_part to the next value.
Parameters:
current_version
The current version
TYPE: Version
config
The current configuration
TYPE: Config
version_part
Optional part of the version to bump
TYPE: Optional[str]
new_version
Optional specific version to bump to
TYPE: Optional[str]
Returns:
Version
The new version
Raises:
ConfigurationError
If it can\u2019t generate the next version.
"},{"location":"reference/api/bumpversion/cli/","title":"
cli","text":"bump-my-version Command line interface.
"},{"location":"reference/api/bumpversion/cli/#bumpversion.cli-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/cli/#bumpversion.cli-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/cli/#bumpversion.cli.bump","title":"bump","text":"bump(\n args: list,\n config_file: Optional[str],\n verbose: int,\n allow_dirty: Optional[bool],\n current_version: Optional[str],\n new_version: Optional[str],\n parse: Optional[str],\n serialize: Optional[List[str]],\n search: Optional[str],\n replace: Optional[str],\n regex: Optional[bool],\n no_configured_files: bool,\n ignore_missing_files: bool,\n ignore_missing_version: bool,\n dry_run: bool,\n commit: Optional[bool],\n tag: Optional[bool],\n sign_tags: Optional[bool],\n tag_name: Optional[str],\n tag_message: Optional[str],\n message: Optional[str],\n commit_args: Optional[str],\n) -> None\n
Change the version.
ARGS may contain any of the following:
VERSION_PART is the part of the version to increase, e.g. minor
. Valid values include those given in the --serialize
/ --parse
option.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
cli(ctx: Context) -> None\n
Version bump your Python project.
"},{"location":"reference/api/bumpversion/cli/#bumpversion.cli.replace","title":"replace","text":"replace(\n files: list,\n config_file: Optional[str],\n verbose: int,\n allow_dirty: Optional[bool],\n current_version: Optional[str],\n new_version: Optional[str],\n parse: Optional[str],\n serialize: Optional[List[str]],\n search: Optional[str],\n replace: Optional[str],\n regex: bool,\n no_configured_files: bool,\n ignore_missing_version: bool,\n ignore_missing_files: bool,\n dry_run: bool,\n) -> None\n
Replace the version in files.
FILES are additional file(s) to modify. If you want to rewrite only files specified on the command line, use with the --no-configured-files
option.
sample_config(prompt: bool, destination: str) -> None\n
Print a sample configuration file.
"},{"location":"reference/api/bumpversion/cli/#bumpversion.cli.show","title":"show","text":"show(\n args: List[str],\n config_file: Optional[str],\n format_: str,\n increment: Optional[str],\n) -> None\n
Show current configuration information.
ARGS may contain one or more configuration attributes. For example:
bump-my-version show current_version
bump-my-version show files.0.filename
bump-my-version show scm_info.branch_name
bump-my-version show current_version scm_info.distance_to_latest_tag
show_bump(\n version: str,\n config_file: Optional[str],\n ascii: bool,\n verbose: int,\n) -> None\n
Show the possible versions resulting from the bump subcommand.
"},{"location":"reference/api/bumpversion/context/","title":"
context","text":"Context for rendering messages and tags.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/context/#bumpversion.context-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/context/#bumpversion.context.base_context","title":"base_context","text":"base_context(\n scm_info: Optional[SCMInfo] = None,\n) -> ChainMap\n
The default context for rendering messages and tags.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.calver_string_to_regex","title":"calver_string_to_regex","text":"calver_string_to_regex(calver_format: str) -> str\n
Convert the calver format string to a regex pattern.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.get_context","title":"get_context","text":"get_context(\n config: Config,\n current_version: Optional[Version] = None,\n new_version: Optional[Version] = None,\n) -> ChainMap\n
Return the context for rendering messages and tags.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.get_datetime_info","title":"get_datetime_info","text":"get_datetime_info(current_dt: datetime.datetime) -> dict\n
Return the full structure of the given datetime for formatting.
"},{"location":"reference/api/bumpversion/context/#bumpversion.context.prefixed_environ","title":"prefixed_environ","text":"prefixed_environ() -> dict\n
Return a dict of the environment with keys wrapped in ${}
.
exceptions","text":"Custom exceptions for BumpVersion.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.BadInputError","title":"BadInputError","text":"BadInputError(message: str, ctx: Optional[Context] = None)\n
Bases: BumpVersionError
User input was bad.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.BumpVersionError","title":"BumpVersionError","text":"BumpVersionError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: UsageError
Custom base class for all BumpVersion exception types.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.ConfigurationError","title":"ConfigurationError","text":"ConfigurationError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
A configuration key-value is missing or in the wrong type.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.DirtyWorkingDirectoryError","title":"DirtyWorkingDirectoryError","text":"DirtyWorkingDirectoryError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
The working directory is dirty, and it is not allowed.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.FormattingError","title":"FormattingError","text":"FormattingError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
We are unable to represent a version required by a format.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.HookError","title":"HookError","text":"HookError(message: str, ctx: Optional[Context] = None)\n
Bases: BumpVersionError
A hook failed.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.InvalidVersionPartError","title":"InvalidVersionPartError","text":"InvalidVersionPartError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
The specified part (e.g. \u2018bugfix\u2019) was not found.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.MissingValueError","title":"MissingValueError","text":"MissingValueError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
A part required for a version format is empty.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.SignedTagsError","title":"SignedTagsError","text":"SignedTagsError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
The VCS does not support signed tags.
"},{"location":"reference/api/bumpversion/exceptions/#bumpversion.exceptions.VersionNotFoundError","title":"VersionNotFoundError","text":"VersionNotFoundError(\n message: str, ctx: Optional[Context] = None\n)\n
Bases: BumpVersionError
A version number was not found in a source file.
"},{"location":"reference/api/bumpversion/files/","title":"
files","text":"Methods for changing files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile","title":"ConfiguredFile","text":"ConfiguredFile(\n file_change: FileChange,\n version_config: VersionConfig,\n search: Optional[str] = None,\n replace: Optional[str] = None,\n)\n
A file to modify in a configured way.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile.get_file_contents","title":"get_file_contents","text":"get_file_contents() -> str\n
Return the contents of the file.
Raises:
FileNotFoundError
if the file doesn\u2019t exist
Returns:
str
The contents of the file
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile.make_file_change","title":"make_file_change","text":"make_file_change(\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Make the change to the file.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.ConfiguredFile.write_file_contents","title":"write_file_contents","text":"write_file_contents(contents: str) -> None\n
Write the contents of the file.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.DataFileUpdater","title":"DataFileUpdater","text":"DataFileUpdater(\n file_change: FileChange,\n version_part_configs: Dict[str, VersionComponentSpec],\n)\n
A class to handle updating files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.DataFileUpdater-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.DataFileUpdater.update_file","title":"update_file","text":"update_file(\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Update the files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.FileUpdater","title":"FileUpdater","text":"FileUpdater(\n file_change: FileChange,\n version_config: VersionConfig,\n search: Optional[str] = None,\n replace: Optional[str] = None,\n)\n
A class to handle updating files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.FileUpdater-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.FileUpdater.update_file","title":"update_file","text":"update_file(\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Update the files.
"},{"location":"reference/api/bumpversion/files/#bumpversion.files-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/files/#bumpversion.files.contains_pattern","title":"contains_pattern","text":"contains_pattern(search: re.Pattern, contents: str) -> bool\n
Does the search pattern match any part of the contents?
"},{"location":"reference/api/bumpversion/files/#bumpversion.files.log_changes","title":"log_changes","text":"log_changes(\n file_path: str,\n file_content_before: str,\n file_content_after: str,\n dry_run: bool = False,\n) -> None\n
Log the changes that would be made to the file.
Parameters:
file_path
The path to the file
TYPE: str
file_content_before
The file contents before the change
TYPE: str
file_content_after
The file contents after the change
TYPE: str
dry_run
True if this is a report-only job
TYPE: bool
DEFAULT: False
modify_files(\n files: List[ConfiguredFile],\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Modify the files, searching and replacing values according to the FileConfig.
Parameters:
files
The list of configured files
TYPE: List[ConfiguredFile]
current_version
The current version
TYPE: Version
new_version
The next version
TYPE: Version
context
The context used for rendering the version
TYPE: MutableMapping
dry_run
True if this should be a report-only job
TYPE: bool
DEFAULT: False
resolve_file_config(\n files: List[FileChange],\n version_config: VersionConfig,\n search: Optional[str] = None,\n replace: Optional[str] = None,\n) -> List[ConfiguredFile]\n
Resolve the files, searching and replacing values according to the FileConfig.
Parameters:
files
A list of file configurations
TYPE: List[FileChange]
version_config
How the version should be changed
TYPE: VersionConfig
search
The search pattern to use instead of any configured search pattern
TYPE: Optional[str]
DEFAULT: None
replace
The replace pattern to use instead of any configured replace pattern
TYPE: Optional[str]
DEFAULT: None
Returns:
List[ConfiguredFile]
A list of ConfiguredFiles
"},{"location":"reference/api/bumpversion/hooks/","title":"
hooks","text":"Implementation of the hook interface.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.base_env","title":"base_env","text":"base_env(config: Config) -> Dict[str, str]\n
Provide the base environment variables.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.get_post_commit_hook_env","title":"get_post_commit_hook_env","text":"get_post_commit_hook_env(\n config: Config,\n current_version: Version,\n new_version: Version,\n) -> Dict[str, str]\n
Provide the environment dictionary for post_commit_hook
s.
get_pre_commit_hook_env(\n config: Config,\n current_version: Version,\n new_version: Version,\n) -> Dict[str, str]\n
Provide the environment dictionary for pre_commit_hook
s.
get_setup_hook_env(\n config: Config, current_version: Version\n) -> Dict[str, str]\n
Provide the environment dictionary for setup_hook
s.
new_version_env(\n config: Config,\n current_version: Version,\n new_version: Version,\n) -> Dict[str, str]\n
Provide the environment dictionary for new_version serialized and tag name.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_command","title":"run_command","text":"run_command(\n script: str, environment: Optional[dict] = None\n) -> subprocess.CompletedProcess\n
Runs command-line programs using the shell.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_hooks","title":"run_hooks","text":"run_hooks(\n hooks: List[str],\n env: Dict[str, str],\n dry_run: bool = False,\n) -> None\n
Run a list of command-line programs using the shell.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_post_commit_hooks","title":"run_post_commit_hooks","text":"run_post_commit_hooks(\n config: Config,\n current_version: Version,\n new_version: Version,\n dry_run: bool = False,\n) -> None\n
Run the post-commit hooks.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_pre_commit_hooks","title":"run_pre_commit_hooks","text":"run_pre_commit_hooks(\n config: Config,\n current_version: Version,\n new_version: Version,\n dry_run: bool = False,\n) -> None\n
Run the pre-commit hooks.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.run_setup_hooks","title":"run_setup_hooks","text":"run_setup_hooks(\n config: Config,\n current_version: Version,\n dry_run: bool = False,\n) -> None\n
Run the setup hooks.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.scm_env","title":"scm_env","text":"scm_env(config: Config) -> Dict[str, str]\n
Provide the scm environment variables.
"},{"location":"reference/api/bumpversion/hooks/#bumpversion.hooks.version_env","title":"version_env","text":"version_env(\n version: Version, version_prefix: str\n) -> Dict[str, str]\n
Provide the environment variables for each version component with a prefix.
"},{"location":"reference/api/bumpversion/indented_logger/","title":"
indented_logger","text":"A logger adapter that adds an indent to the beginning of each message.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter","title":"IndentedLoggerAdapter","text":"IndentedLoggerAdapter(\n logger: logging.Logger,\n extra: Optional[dict] = None,\n depth: int = 2,\n indent_char: str = \" \",\n reset: bool = False,\n)\n
Bases: LoggerAdapter
Logger adapter that adds an indent to the beginning of each message.
Parameters:
logger
The logger to adapt.
TYPE: Logger
extra
Extra values to add to the logging context.
TYPE: Optional[dict]
DEFAULT: None
depth
The number of indent_char
to generate for each indent level.
TYPE: int
DEFAULT: 2
indent_char
The character or string to use for indenting.
TYPE: str
DEFAULT: ' '
reset
True
if the indent level should be reset to zero.
TYPE: bool
DEFAULT: False
property
","text":"current_indent: int\n
The current indent level.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.indent_str","title":"indent_strproperty
","text":"indent_str: str\n
The indent string.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.dedent","title":"dedent","text":"dedent(amount: int = 1) -> None\n
Decrease the indent level by amount
.
indent(amount: int = 1) -> None\n
Increase the indent level by amount
.
process(\n msg: str, kwargs: Optional[MutableMapping[str, Any]]\n) -> Tuple[str, MutableMapping[str, Any]]\n
Process the message and add the indent.
Parameters:
msg
The logging message.
TYPE: str
kwargs
Keyword arguments passed to the logger.
TYPE: Optional[MutableMapping[str, Any]]
Returns:
Tuple[str, MutableMapping[str, Any]]
A tuple containing the message and keyword arguments.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.reset","title":"reset","text":"reset() -> None\n
Reset the indent level to zero.
"},{"location":"reference/api/bumpversion/scm/","title":"
scm","text":"Version control system management.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git","title":"Git","text":" Bases: SourceCodeManager
Git implementation.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.add_path","title":"add_pathclassmethod
","text":"add_path(path: Union[str, Path]) -> None\n
Add a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.assert_nondirty","title":"assert_nondirtyclassmethod
","text":"assert_nondirty() -> None\n
Assert that the working directory is not dirty.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.latest_tag_info","title":"latest_tag_infoclassmethod
","text":"latest_tag_info(\n tag_name: str, parse_pattern: str\n) -> SCMInfo\n
Return information about the latest tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.tag","title":"tagclassmethod
","text":"tag(\n name: str,\n sign: bool = False,\n message: Optional[str] = None,\n) -> None\n
Create a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. Otherwise, it uses an annotated tag.
Parameters:
name
The name of the tag
TYPE: str
sign
True to sign the tag
TYPE: bool
DEFAULT: False
message
An optional message to annotate the tag.
TYPE: Optional[str]
DEFAULT: None
Bases: SourceCodeManager
Mercurial implementation.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.add_path","title":"add_pathclassmethod
","text":"add_path(path: Union[str, Path]) -> None\n
Add a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.assert_nondirty","title":"assert_nondirtyclassmethod
","text":"assert_nondirty() -> None\n
Assert that the working directory is clean.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.latest_tag_info","title":"latest_tag_infoclassmethod
","text":"latest_tag_info(\n tag_name: str, parse_pattern: str\n) -> SCMInfo\n
Return information about the latest tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.tag","title":"tagclassmethod
","text":"tag(\n name: str,\n sign: bool = False,\n message: Optional[str] = None,\n) -> None\n
Create a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. Otherwise, it uses an annotated tag.
Parameters:
name
The name of the tag
TYPE: str
sign
True to sign the tag
TYPE: bool
DEFAULT: False
message
A optional message to annotate the tag.
TYPE: Optional[str]
DEFAULT: None
Raises:
SignedTagsError
If sign
is True
dataclass
","text":"SCMInfo(\n tool: Optional[Type[SourceCodeManager]] = None,\n commit_sha: Optional[str] = None,\n distance_to_latest_tag: int = 0,\n current_version: Optional[str] = None,\n current_tag: Optional[str] = None,\n branch_name: Optional[str] = None,\n short_branch_name: Optional[str] = None,\n repository_root: Optional[Path] = None,\n dirty: Optional[bool] = None,\n)\n
Information about the current source code manager and state.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SCMInfo-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SCMInfo.path_in_repo","title":"path_in_repo","text":"path_in_repo(path: Union[Path, str]) -> bool\n
Return whether a path is inside this repository.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager","title":"SourceCodeManager","text":"Base class for version control systems.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.add_path","title":"add_pathclassmethod
","text":"add_path(path: Union[str, Path]) -> None\n
Add a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.assert_nondirty","title":"assert_nondirtyclassmethod
","text":"assert_nondirty() -> None\n
Assert that the working directory is not dirty.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.commit","title":"commitclassmethod
","text":"commit(\n message: str,\n current_version: str,\n new_version: str,\n extra_args: Optional[list] = None,\n) -> None\n
Commit the changes.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.commit_to_scm","title":"commit_to_scmclassmethod
","text":"commit_to_scm(\n files: List[Union[str, Path]],\n config: Config,\n context: MutableMapping,\n extra_args: Optional[List[str]] = None,\n dry_run: bool = False,\n) -> None\n
Commit the files to the source code management system.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.format_and_raise_error","title":"format_and_raise_errorclassmethod
","text":"format_and_raise_error(\n exc: Union[TypeError, subprocess.CalledProcessError]\n) -> None\n
Format the error message from an exception and re-raise it as a BumpVersionError.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.get_all_tags","title":"get_all_tagsclassmethod
","text":"get_all_tags() -> List[str]\n
Return all tags in VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.get_version_from_tag","title":"get_version_from_tagclassmethod
","text":"get_version_from_tag(\n tag: str, tag_name: str, parse_pattern: str\n) -> Optional[str]\n
Return the version from a tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.is_usable","title":"is_usableclassmethod
","text":"is_usable() -> bool\n
Is the VCS implementation usable.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.latest_tag_info","title":"latest_tag_infoclassmethod
","text":"latest_tag_info(\n tag_name: str, parse_pattern: str\n) -> SCMInfo\n
Return information about the latest tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.tag","title":"tagclassmethod
","text":"tag(\n name: str,\n sign: bool = False,\n message: Optional[str] = None,\n) -> None\n
Create a tag of the new_version in VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.tag_in_scm","title":"tag_in_scmclassmethod
","text":"tag_in_scm(\n config: Config,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Tag the current commit in the source code management system.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.get_scm_info","title":"get_scm_info","text":"get_scm_info(tag_name: str, parse_pattern: str) -> SCMInfo\n
Return a dict with the latest source code management info.
"},{"location":"reference/api/bumpversion/show/","title":"
show","text":"Functions for displaying information about the version.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/show/#bumpversion.show-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/show/#bumpversion.show.do_show","title":"do_show","text":"do_show(\n *args,\n config: Config,\n format_: str = \"default\",\n increment: Optional[str] = None\n) -> None\n
Show current version or configuration information.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_default","title":"output_default","text":"output_default(value: dict) -> None\n
Output the value with key=value or just value if there is only one item.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_json","title":"output_json","text":"output_json(value: dict) -> None\n
Output the value as json.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_yaml","title":"output_yaml","text":"output_yaml(value: dict) -> None\n
Output the value as yaml.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.resolve_name","title":"resolve_name","text":"resolve_name(\n obj: Any,\n name: str,\n default: Any = None,\n err_on_missing: bool = False,\n) -> Any\n
Get a key or attr name
from obj or default value.
Copied and modified from Django Template variable resolutions
Resolution methods:
Parameters:
obj
The object to access
TYPE: Any
name
A dotted name to the value, such as mykey.0.name
TYPE: str
default
If the name cannot be resolved from the object, return this value
TYPE: Any
DEFAULT: None
err_on_missing
Raise a BadInputError
if the name cannot be resolved
TYPE: bool
DEFAULT: False
Returns:
Any
The value at the resolved name or the default value.
Raises:
BadInputError
If we cannot resolve the name and err_on_missing
is True
AttributeError
If a @property decorator raised it
TypeError
If a @property decorator raised it
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.resolve_name--noqa-dar401","title":"noqa: DAR401","text":""},{"location":"reference/api/bumpversion/ui/","title":"
ui","text":"Utilities for user interface.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/ui/#bumpversion.ui-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.get_indented_logger","title":"get_indented_logger","text":"get_indented_logger(name: str) -> IndentedLoggerAdapter\n
Get a logger with indentation.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_error","title":"print_error","text":"print_error(msg: str) -> None\n
Raise an error and exit.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_info","title":"print_info","text":"print_info(msg: str) -> None\n
Echo a message to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_warning","title":"print_warning","text":"print_warning(msg: str) -> None\n
Echo a warning to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.setup_logging","title":"setup_logging","text":"setup_logging(verbose: int = 0) -> None\n
Configure the logging.
"},{"location":"reference/api/bumpversion/utils/","title":"
utils","text":"General utilities.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/utils/#bumpversion.utils-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.extract_regex_flags","title":"extract_regex_flags","text":"extract_regex_flags(regex_pattern: str) -> Tuple[str, str]\n
Extract the regex flags from the regex pattern.
Parameters:
regex_pattern
The pattern that might start with regex flags
TYPE: str
Returns:
Tuple[str, str]
A tuple of the regex pattern without the flag string and regex flag string
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.format_and_raise_error","title":"format_and_raise_error","text":"format_and_raise_error(\n exc: Union[TypeError, subprocess.CalledProcessError]\n) -> None\n
Format the error message from an exception and re-raise it as a BumpVersionError.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.get_nested_value","title":"get_nested_value","text":"get_nested_value(d: dict, path: str) -> Any\n
Retrieves the value of a nested key in a dictionary based on the given path.
Parameters:
d
The dictionary to search.
TYPE: dict
path
A string representing the path to the nested key, separated by periods.
TYPE: str
Returns:
Any
The value of the nested key.
Raises:
KeyError
If a key in the path does not exist.
ValueError
If an element in the path is not a dictionary.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.get_overrides","title":"get_overrides","text":"get_overrides(**kwargs) -> dict\n
Return a dictionary containing only the overridden key-values.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.key_val_string","title":"key_val_string","text":"key_val_string(d: dict) -> str\n
Render the dictionary as a comma-delimited key=value string.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.labels_for_format","title":"labels_for_format","text":"labels_for_format(serialize_format: str) -> List[str]\n
Return a list of labels for the given serialize_format.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.recursive_sort_dict","title":"recursive_sort_dict","text":"recursive_sort_dict(input_value: Any) -> Any\n
Sort a dictionary recursively.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.run_command","title":"run_command","text":"run_command(\n command: list, env: Optional[dict] = None\n) -> CompletedProcess\n
Run a shell command and return its output.
"},{"location":"reference/api/bumpversion/utils/#bumpversion.utils.set_nested_value","title":"set_nested_value","text":"set_nested_value(d: dict, value: Any, path: str) -> None\n
Sets the value of a nested key in a dictionary based on the given path.
Parameters:
d
The dictionary to search.
TYPE: dict
value
The value to set.
TYPE: Any
path
A string representing the path to the nested key, separated by periods.
TYPE: str
Raises:
ValueError
If an element in the path is not a dictionary.
KeyError
If a key in the path does not exist.
"},{"location":"reference/api/bumpversion/visualize/","title":"
visualize","text":"Visualize the bumpversion process.
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.Border","title":"Borderdataclass
","text":"Border(\n corner_bottom_right: str,\n corner_top_right: str,\n corner_top_left: str,\n corner_bottom_left: str,\n divider_left: str,\n divider_up: str,\n divider_down: str,\n divider_right: str,\n line: str,\n pipe: str,\n cross: str,\n)\n
A border definition.
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.connection_str","title":"connection_str","text":"connection_str(\n border: Border,\n has_next: bool = False,\n has_previous: bool = False,\n) -> str\n
Return the correct connection string based on the next and previous.
Parameters:
border
The border definition to draw the lines
TYPE: Border
has_next
If True
, there is a next line
TYPE: bool
DEFAULT: False
has_previous
If True
, there is a previous line
TYPE: bool
DEFAULT: False
Returns:
str
A string that connects left-to-right and top-to-bottom based on the next and previous
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.filter_version_parts","title":"filter_version_parts","text":"filter_version_parts(config: Config) -> List[str]\n
Return the version parts that are in the configuration.
Parameters:
config
The configuration to check against
TYPE: Config
Returns:
List[str]
The version parts that are in the configuration
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.labeled_line","title":"labeled_line","text":"labeled_line(\n label: str,\n border: Border,\n fit_length: Optional[int] = None,\n) -> str\n
Return the version part string with the correct padding.
Parameters:
label
The label to render
TYPE: str
border
The border definition to draw the lines
TYPE: Border
fit_length
The length to fit the label to
TYPE: Optional[int]
DEFAULT: None
Returns:
str
A labeled line with leading and trailing spaces
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.lead_string","title":"lead_string","text":"lead_string(\n version_str: str, border: Border, blank: bool = False\n) -> str\n
Return the first part of a string with the bump character or spaces of the correct amount.
Examples:
>>> lead_string(\"1.0.0\", Border(*BOX_CHARS[\"light\"]))\n'1.0.0 \u2500\u2500 bump \u2500'\n>>> lead_string(\"1.0.0\", Border(*BOX_CHARS[\"light\"]), blank=True)\n' '\n
Parameters:
version_str
The string to render as the starting point
TYPE: str
border
The border definition to draw the lines
TYPE: Border
blank
If True
, return a blank string the same length as the version bump string
TYPE: bool
DEFAULT: False
Returns:
str
The version bump string or a blank string
"},{"location":"reference/api/bumpversion/visualize/#bumpversion.visualize.visualize","title":"visualize","text":"visualize(\n config: Config,\n version_str: str,\n box_style: str = \"light\",\n) -> None\n
Output a visualization of the bump-my-version bump process.
"},{"location":"reference/api/bumpversion/yaml_dump/","title":"
yaml_dump","text":"A simple YAML dumper to avoid extra dependencies.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.YAMLDumpers","title":"YAMLDumpers","text":" Bases: UserDict
Registry of YAML dumpers.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.YAMLDumpers-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.YAMLDumpers.add_dumper","title":"add_dumper","text":"add_dumper(data_type: type, dumper: DumperFunc) -> None\n
Add a YAML dumper.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.dump","title":"dump","text":"dump(data: Any) -> str\n
Dump a value to a string buffer.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_bool","title":"format_bool","text":"format_bool(val: bool) -> str\n
Return a YAML representation of a bool.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_date","title":"format_date","text":"format_date(val: datetime.date) -> str\n
Return a YAML representation of a date.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_datetime","title":"format_datetime","text":"format_datetime(val: datetime.datetime) -> str\n
Return a string representation of a value.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_dict","title":"format_dict","text":"format_dict(val: dict) -> str\n
Return a YAML representation of a dict.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_float","title":"format_float","text":"format_float(data: float) -> str\n
Return a YAML representation of a float.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_int","title":"format_int","text":"format_int(val: int) -> str\n
Return a YAML representation of an int.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_none","title":"format_none","text":"format_none(_: None) -> str\n
Return a YAML representation of None.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_sequence","title":"format_sequence","text":"format_sequence(val: Union[list, tuple]) -> str\n
Return a string representation of a value.
"},{"location":"reference/api/bumpversion/yaml_dump/#bumpversion.yaml_dump.format_str","title":"format_str","text":"format_str(val: str) -> str\n
Return a YAML representation of a string.
"},{"location":"reference/api/bumpversion/config/","title":"Index","text":"Configuration management.
"},{"location":"reference/api/bumpversion/config/#bumpversion.config-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/#bumpversion.config-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/#bumpversion.config.check_current_version","title":"check_current_version","text":"check_current_version(config: Config) -> str\n
Returns the current version.
If the current version is not specified in the config file, command line or env variable, it attempts to retrieve it via a tag.
Parameters:
config
The current configuration dictionary.
TYPE: Config
Returns:
str
The version number
Raises:
ConfigurationError
If it can\u2019t find the current version
"},{"location":"reference/api/bumpversion/config/#bumpversion.config.get_configuration","title":"get_configuration","text":"get_configuration(\n config_file: Union[str, Path, None] = None,\n **overrides: Any\n) -> Config\n
Return the configuration based on any configuration files and overrides.
Parameters:
config_file
An explicit configuration file to use, otherwise search for one
TYPE: Union[str, Path, None]
DEFAULT: None
**overrides
Specific configuration key-values to override in the configuration
TYPE: Any
DEFAULT: {}
Returns:
Config
The configuration
"},{"location":"reference/api/bumpversion/config/#bumpversion.config.set_config_defaults","title":"set_config_defaults","text":"set_config_defaults(\n parsed_config: dict[str, Any], **overrides: Any\n) -> dict[str, Any]\n
Apply the defaults to the parsed config.
"},{"location":"reference/api/bumpversion/config/create/","title":"
create","text":"Module for creating a new config file.
"},{"location":"reference/api/bumpversion/config/create/#bumpversion.config.create-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/create/#bumpversion.config.create.create_configuration","title":"create_configuration","text":"create_configuration(\n destination: str, prompt: bool\n) -> TOMLDocument\n
Create a new configuration as a TOMLDocument.
Parameters:
destination
stdout
or a path to a new or existing file.
TYPE: str
prompt
True
if the user should be prompted for input.
TYPE: bool
Returns:
TOMLDocument
The TOMLDocument structure with the updated configuration.
"},{"location":"reference/api/bumpversion/config/create/#bumpversion.config.create.get_defaults_from_dest","title":"get_defaults_from_dest","text":"get_defaults_from_dest(\n destination: str,\n) -> Tuple[dict, TOMLDocument]\n
Get the default configuration and the configuration from the destination.
"},{"location":"reference/api/bumpversion/config/files/","title":"
files","text":"Contains methods for finding and reading configuration files.
"},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files.find_config_file","title":"find_config_file","text":"find_config_file(\n explicit_file: Union[str, Path, None] = None\n) -> Union[Path, None]\n
Find the configuration file, if it exists.
If no explicit configuration file is passed, it will search in several files to find its configuration.
Parameters:
explicit_file
The configuration file to explicitly use.
TYPE: Union[str, Path, None]
DEFAULT: None
Returns:
Union[Path, None]
The configuration file path
"},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files.read_config_file","title":"read_config_file","text":"read_config_file(\n config_file: Union[str, Path, None] = None\n) -> Dict[str, Any]\n
Read the configuration file, if it exists.
If no explicit configuration file is passed, it will search in several files to find its configuration.
Parameters:
config_file
The configuration file to explicitly use.
TYPE: Union[str, Path, None]
DEFAULT: None
Returns:
Dict[str, Any]
A dictionary of read key-values
"},{"location":"reference/api/bumpversion/config/files/#bumpversion.config.files.read_toml_file","title":"read_toml_file","text":"read_toml_file(file_path: Path) -> Dict[str, Any]\n
Parse a TOML file and return the bumpversion
section.
Parameters:
file_path
The path to the TOML file.
TYPE: Path
Returns:
dict
A dictionary of the bumpversion
section.
TYPE: Dict[str, Any]
update_config_file(\n config_file: Union[str, Path],\n config: Config,\n current_version: Version,\n new_version: Version,\n context: MutableMapping,\n dry_run: bool = False,\n) -> None\n
Update the current_version key in the configuration file.
Parameters:
config_file
The configuration file to explicitly use.
TYPE: Union[str, Path]
config
The configuration to use.
TYPE: Config
current_version
The current version.
TYPE: Version
new_version
The new version.
TYPE: Version
context
The context to use for serialization.
TYPE: MutableMapping
dry_run
True if the update should be a dry run.
TYPE: bool
DEFAULT: False
files_legacy","text":"This module handles the legacy config file format.
"},{"location":"reference/api/bumpversion/config/files_legacy/#bumpversion.config.files_legacy-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/files_legacy/#bumpversion.config.files_legacy.read_ini_file","title":"read_ini_file","text":"read_ini_file(file_path: Path) -> Dict[str, Any]\n
Parse an INI file and return a dictionary of sections and their options.
Parameters:
file_path
The path to the INI file.
TYPE: Path
Returns:
dict
A dictionary of sections and their options.
TYPE: Dict[str, Any]
update_ini_config_file(\n config_file: Union[str, Path],\n current_version: str,\n new_version: str,\n dry_run: bool = False,\n) -> None\n
Update the current_version key in the configuration file.
Instead of parsing and re-writing the config file with new information, it will use a regular expression to just replace the current_version value. The idea is it will avoid unintentional changes (like formatting) to the config file.
Parameters:
config_file
The configuration file to explicitly use.
TYPE: Union[str, Path]
current_version
The serialized current version.
TYPE: str
new_version
The serialized new version.
TYPE: str
dry_run
True if the update should be a dry run.
TYPE: bool
DEFAULT: False
models","text":"Bump My Version configuration models.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config","title":"Config","text":" Bases: BaseSettings
Bump Version configuration.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.files_to_modify","title":"files_to_modifyproperty
","text":"files_to_modify: List[FileChange]\n
Return a list of files to modify.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.resolved_filemap","title":"resolved_filemapproperty
","text":"resolved_filemap: Dict[str, List[FileChange]]\n
Return the cached resolved filemap.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.version_config","title":"version_configproperty
","text":"version_config: 'VersionConfig'\n
Return the version configuration.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.add_files","title":"add_files","text":"add_files(filename: Union[str, List[str]]) -> None\n
Add a filename to the list of files.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.version_spec","title":"version_spec","text":"version_spec(\n version: Optional[str] = None,\n) -> \"VersionSpec\"\n
Return the version specification.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange","title":"FileChange","text":" Bases: BaseModel
A change to make to a file.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange.__hash__","title":"__hash__","text":"__hash__()\n
Return a hash of the model.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.FileChange.get_search_pattern","title":"get_search_pattern","text":"get_search_pattern(\n context: MutableMapping,\n) -> Tuple[re.Pattern, str]\n
Render the search pattern and return the compiled regex pattern and the raw pattern.
Parameters:
context
The context to use for rendering the search pattern
TYPE: MutableMapping
Returns:
Tuple[Pattern, str]
A tuple of the compiled regex pattern and the raw pattern as a string.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/utils/","title":"
utils","text":"Helper functions for the config module.
"},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils.get_all_file_configs","title":"get_all_file_configs","text":"get_all_file_configs(config_dict: dict) -> List[FileChange]\n
Make sure all version components are included.
"},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils.get_all_part_configs","title":"get_all_part_configs","text":"get_all_part_configs(\n config_dict: dict,\n) -> Dict[str, VersionComponentSpec]\n
Make sure all version components are included.
"},{"location":"reference/api/bumpversion/config/utils/#bumpversion.config.utils.resolve_glob_files","title":"resolve_glob_files","text":"resolve_glob_files(\n file_cfg: FileChange,\n) -> List[FileChange]\n
Return a list of file configurations that match the glob pattern.
Parameters:
file_cfg
The file configuration containing the glob pattern
TYPE: FileChange
Returns:
List[FileChange]
A list of resolved file configurations according to the pattern.
"},{"location":"reference/api/bumpversion/versioning/","title":"Index","text":"Module for managing Versions and their internal parts.
"},{"location":"reference/api/bumpversion/versioning/conventions/","title":"
conventions","text":"Standard version conventions.
"},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions.pep440_version_spec","title":"pep440_version_spec","text":"pep440_version_spec() -> VersionSpec\n
Return a VersionSpec for PEP 440.
"},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions.semver_spec","title":"semver_spec","text":"semver_spec() -> VersionSpec\n
Return a VersionSpec for SEMVER.
"},{"location":"reference/api/bumpversion/versioning/functions/","title":"
functions","text":"Generators for version parts.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.CalVerFunction","title":"CalVerFunction","text":"CalVerFunction(calver_format: str)\n
Bases: PartFunction
This is a class that provides a CalVer function for version parts.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.CalVerFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.CalVerFunction.bump","title":"bump","text":"bump(value: Optional[str] = None) -> str\n
Return the optional value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.IndependentFunction","title":"IndependentFunction","text":"IndependentFunction(value: Union[str, int, None] = None)\n
Bases: PartFunction
This is a class that provides an independent function for version parts.
It simply returns the optional value, which is equal to the first value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.IndependentFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.IndependentFunction.bump","title":"bump","text":"bump(value: Optional[str] = None) -> str\n
Return the optional value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.NumericFunction","title":"NumericFunction","text":"NumericFunction(\n optional_value: Union[str, int, None] = None,\n first_value: Union[str, int, None] = None,\n)\n
Bases: PartFunction
This is a class that provides a numeric function for version parts.
It simply starts with the provided first_value (0 by default) and increases it following the sequence of integer numbers.
The optional value of this function is equal to the first value.
This function also supports alphanumeric parts, altering just the numeric part (e.g. \u2018r3\u2019 \u2013> \u2018r4\u2019). Only the first numeric group found in the part is considered (e.g. \u2018r3-001\u2019 \u2013> \u2018r4-001\u2019).
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.NumericFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.NumericFunction.bump","title":"bump","text":"bump(value: Union[str, int]) -> str\n
Increase the first numerical value by one.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.PartFunction","title":"PartFunction","text":"Base class for a version part function.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.PartFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.PartFunction.bump","title":"bump","text":"bump(value: str) -> str\n
Increase the value.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.ValuesFunction","title":"ValuesFunction","text":"ValuesFunction(\n values: List[str],\n optional_value: Optional[str] = None,\n first_value: Optional[str] = None,\n)\n
Bases: PartFunction
This is a class that provides a values list based function for version parts.
It is initialized with a list of values and iterates through them when bumping the part.
The default optional value of this function is equal to the first value, but may be otherwise specified.
When trying to bump a part which has already the maximum value in the list you get a ValueError exception.
"},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.ValuesFunction-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/functions/#bumpversion.versioning.functions.ValuesFunction.bump","title":"bump","text":"bump(value: str) -> str\n
Return the item after value
in the list.
models","text":"Models for managing versioning of software projects.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version","title":"Version","text":"Version(\n version_spec: VersionSpec,\n components: Dict[str, VersionComponent],\n original: Optional[str] = None,\n)\n
The specification of a version and its parts.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version.bump","title":"bump","text":"bump(component_name: str) -> 'Version'\n
Increase the value of the specified component, reset its dependents, and return a new Version.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version.required_components","title":"required_components","text":"required_components() -> List[str]\n
Return the names of the parts that are required.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.Version.values","title":"values","text":"values() -> Dict[str, VersionComponent]\n
Return the values of the parts.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent","title":"VersionComponent","text":"VersionComponent(\n values: Optional[list] = None,\n optional_value: Optional[str] = None,\n first_value: Union[str, int, None] = None,\n independent: bool = False,\n always_increment: bool = False,\n calver_format: Optional[str] = None,\n source: Optional[str] = None,\n value: Union[str, int, None] = None,\n)\n
Represent part of a version number.
Determines the PartFunction that rules how the part behaves when increased or reset based on the configuration given.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.is_independent","title":"is_independentproperty
","text":"is_independent: bool\n
Is the part independent of the other parts?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.is_optional","title":"is_optionalproperty
","text":"is_optional: bool\n
Is the part optional?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.value","title":"valueproperty
","text":"value: str\n
Return the value of the part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.bump","title":"bump","text":"bump() -> 'VersionComponent'\n
Return a part with bumped value.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.copy","title":"copy","text":"copy() -> 'VersionComponent'\n
Return a copy of the part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.null","title":"null","text":"null() -> 'VersionComponent'\n
Return a part with first value.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec","title":"VersionComponentSpec","text":" Bases: BaseModel
Configuration of a version component.
This is used to read in the configuration from the bumpversion config file.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.always_increment","title":"always_incrementclass-attribute
instance-attribute
","text":"always_increment: bool = False\n
Should the component always increment, even if it is not necessary?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.calver_format","title":"calver_formatclass-attribute
instance-attribute
","text":"calver_format: Optional[str] = None\n
The format string for a CalVer component.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.depends_on","title":"depends_onclass-attribute
instance-attribute
","text":"depends_on: Optional[str] = None\n
The name of the component this component depends on.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.first_value","title":"first_valueclass-attribute
instance-attribute
","text":"first_value: Union[str, int, None] = None\n
The first value to increment from.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.independent","title":"independentclass-attribute
instance-attribute
","text":"independent: bool = False\n
Is the component independent of the other components?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.optional_value","title":"optional_valueclass-attribute
instance-attribute
","text":"optional_value: Optional[str] = None\n
The value that is optional to include in the version.
class-attribute
instance-attribute
","text":"values: Optional[list] = None\n
The possible values for the component. If it and calver_format
is None, the component is numeric.
create_component(\n value: Union[str, int, None] = None\n) -> VersionComponent\n
Generate a version component from the configuration.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponentSpec.set_always_increment_with_calver","title":"set_always_increment_with_calverclassmethod
","text":"set_always_increment_with_calver(data: Any) -> Any\n
Set always_increment to True if calver_format is present.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec","title":"VersionSpec","text":"VersionSpec(\n components: Dict[str, VersionComponentSpec],\n order: Optional[List[str]] = None,\n)\n
The specification of a version\u2019s components and their relationships.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec.create_version","title":"create_version","text":"create_version(values: Dict[str, str]) -> 'Version'\n
Generate a version from the given values.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionSpec.get_dependents","title":"get_dependents","text":"get_dependents(component_name: str) -> List[str]\n
Return the parts that depend on the given part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/serialization/","title":"
serialization","text":"Functions for serializing and deserializing version objects.
"},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization.multisort","title":"multisort","text":"multisort(xs: list, specs: tuple) -> list\n
Sort a list of dictionaries by multiple keys.
From https://docs.python.org/3/howto/sorting.html#sort-stability-and-complex-sorts
Parameters:
xs
The list of dictionaries to sort
TYPE: list
specs
A tuple of (key, reverse) pairs
TYPE: tuple
Returns:
list
The sorted list
"},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization.parse_version","title":"parse_version","text":"parse_version(\n version_string: str, parse_pattern: str\n) -> Dict[str, str]\n
Parse a version string into a dictionary of the parts and values using a regular expression.
Parameters:
version_string
Version string to parse
TYPE: str
parse_pattern
The regular expression pattern to use for parsing
TYPE: str
Returns:
Dict[str, str]
A dictionary of version part labels and their values, or an empty dictionary
Dict[str, str]
if the version string doesn\u2019t match.
Raises:
BumpVersionError
If the parse_pattern is not a valid regular expression
"},{"location":"reference/api/bumpversion/versioning/serialization/#bumpversion.versioning.serialization.serialize","title":"serialize","text":"serialize(\n version: Version,\n serialize_patterns: List[str],\n context: MutableMapping,\n) -> str\n
Attempts to serialize a version with the given serialization format.
Parameters:
version
The version to serialize
TYPE: Version
serialize_patterns
The serialization format to use, using Python\u2019s format string syntax
TYPE: List[str]
context
The context to use when serializing the version
TYPE: MutableMapping
Raises:
FormattingError
if a serialization pattern
Returns:
str
The serialized version as a string
"},{"location":"reference/api/bumpversion/versioning/version_config/","title":"
version_config","text":"Module for managing Versions and their internal parts.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig","title":"VersionConfig","text":"VersionConfig(\n parse: str,\n serialize: Tuple[str],\n search: str,\n replace: str,\n part_configs: Optional[\n Dict[str, VersionComponentSpec]\n ] = None,\n)\n
Hold a complete representation of a version string.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig.order","title":"orderproperty
","text":"order: List[str]\n
Return the order of the labels in a serialization format.
Currently, order depends on the first given serialization format. This seems like a good idea because this should be the most complete format.
Returns:
List[str]
A list of version part labels in the order they should be rendered.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig.parse","title":"parse","text":"parse(\n version_string: Optional[str] = None,\n raise_error: bool = False,\n) -> Optional[Version]\n
Parse a version string into a Version object.
Parameters:
version_string
Version string to parse
TYPE: Optional[str]
DEFAULT: None
raise_error
Raise an exception if a version string is invalid
TYPE: bool
DEFAULT: False
Returns:
Optional[Version]
A Version object representing the string.
Raises:
BumpVersionError
If a version string is invalid and raise_error is True.
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config.VersionConfig.serialize","title":"serialize","text":"serialize(version: Version, context: MutableMapping) -> str\n
Serialize a version to a string.
Parameters:
version
The version to serialize
TYPE: Version
context
The context to use when serializing the version
TYPE: MutableMapping
Returns:
str
The serialized version as a string
"},{"location":"reference/api/bumpversion/versioning/version_config/#bumpversion.versioning.version_config-functions","title":"Functions","text":""},{"location":"reference/configuration/","title":"Configuration","text":"Bump My Version looks in three places for configuration information (in order of precedence):
Bump My Version looks in four places for the configuration file to parse (in order of precedence):
--config-file <FILE>
(command line argument)BUMPVERSION_CONFIG_FILE=file
(environment variable).bumpversion.cfg
(legacy).bumpversion.toml
setup.cfg
(legacy)pyproject.toml
.toml
files are recommended. We will likely drop support for ini
-style formats in the future. You should add your configuration file to your source code management system.
By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified.
"},{"location":"reference/configuration/#configuration-sections","title":"Configuration sections","text":"This section configures which files Bump My Version should update by replacing their current version with the newly bumped version.
"},{"location":"reference/configuration/file/#filename","title":"filename","text":"required Yes\u2021 default empty type stringThe name of the file to modify.
Note
\u2021 This is only used with TOML configuration and is only required if glob
is not specified. INI-style configuration files specify the file name as part of the grouping.
The glob pattern specifying the files to modify.
Note
\u2021 This is only used with TOML configuration, and is only required if filename
is not specified. INI-style configuration files specify the glob pattern as part of the grouping.
A list of glob patterns to exclude from the files found via the glob
parameter. Does nothing if filename
is specified.
parse
field type string This is an override to the default pattern to parse the version number from this file.
"},{"location":"reference/configuration/file/#serialize","title":"serialize","text":"required No default the value configured in the globalserialize
field type an array of strings This is an override to the default templates to serialize the new version number in this file.
"},{"location":"reference/configuration/file/#search","title":"search","text":"required No default the value configured in the globalsearch
field type string This is an override to the default template string how to search for the string to be replaced in the file.
"},{"location":"reference/configuration/file/#regex","title":"regex","text":"required No default the value configured in the globalregex
field type boolean If True
, treat the search
parameter as a regular expression.
replace
field type string This is an override to the template to create the string that will replace the current version number in the file.
"},{"location":"reference/configuration/file/#ignore_missing_version","title":"ignore_missing_version","text":"required No default The value configured in the globalignore_missing_version
field type boolean If True
, don\u2019t fail if the version string to be replaced is not found in the file.
ignore_missing_file
field type boolean if True
, don\u2019t fail if the configured file is missing.
The include_bumps
file configuration allows you to control when bump-my-version includes this file for changes. Its alternative is the exclude_bumps
configuration. When a bump <version component>
command is issued, this file is changed only if the version component is in this list and not in exclude_bumps
. The parse configuration defines version components.
The default value, or an empty list, includes all version components.
"},{"location":"reference/configuration/file/#exclude_bumps","title":"exclude_bumps","text":"required No default[]
type list of strings The exclude_bumps
file configuration allows you to control when bump-my-version excludes this file for changes. Its alternative is the include_bumps
configuration. When a bump <version component>
command is issued, this file is only changed if the version component is not in this list. The parse configuration defines version components.
The default value does not exclude anything.
"},{"location":"reference/configuration/file/#examples","title":"Examples","text":"TOMLCFGTOML allows us to specify the files using an array of tables. TOML configuration adds two fields to each file configuration: filename
and glob
. These fields are mutually exclusive: if you specify a value for both, only the glob
value is used.
For example, to change coolapp/__init__.py
with the defaults and alter CHANGELOG.md
twice:
[[tool.bumpversion.files]]\nfilename = \"coolapp/__init__.py\"\n\n[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"Unreleased\"\n\n[[tool.bumpversion.files]]\nfilename = \"CHANGELOG.md\"\nsearch = \"{current_version}...HEAD\"\nreplace = \"{current_version}...{new_version}\"\n
INI-style configuration is in the section: [bumpversion:file:<filename>]
or [bumpversion:glob:<glob pattern>]
.
Both, file:
and glob:
are configured the same. Their difference is that file will match file names directly like requirements.txt
. While glob also matches multiple files via wildcards like **/pom.xml
.
Note
The configuration file format requires each section header to be unique. If you want to process a certain file multiple times, you may append a description between parens to the file
keyword: [bumpversion:file (special one):\u2026]
.
For example, to change coolapp/__init__.py
with the defaults and alter CHANGELOG.md
twice:
[bumpversion:file:coolapp/__init__.py]\n\n[bumpversion:file(version heading):CHANGELOG.md]\nsearch = Unreleased\n\n[bumpversion:file(previous version):CHANGELOG.md]\nsearch = {current_version}...HEAD\nreplace = {current_version}...{new_version}\n
"},{"location":"reference/configuration/global/","title":"Global Configuration","text":"The general configuration is grouped in a [tool.bumpversion]
or [bumpversion]
section, depending on if it is a TOML or INI file, respectfully.
False
type boolean command line option --allow-dirty | --no-allow-dirty
environment var BUMPVERSION_ALLOW_DIRTY
Bump-my-version\u2019s default behavior is to abort if the working directory has uncommitted changes. This protects you from releasing unversioned files and overwriting unsaved changes.
"},{"location":"reference/configuration/global/#commit","title":"commit","text":"required No defaultFalse
(Don\u2019t create a commit) type boolean command line option --commit | --no-commit
environment var BUMPVERSION_COMMIT
Whether to create a commit using git or Mercurial.
If you have pre-commit hooks, add an option to commit_args
to turn off your pre-commit hooks. For Git, use --no-verify
and use --config hooks.pre-commit=
for Mercurial.
\"\"
type string command line option --commit-args
environment var BUMPVERSION_COMMIT_ARGS
Extra arguments to pass to commit command. This is only used when the commit
option is set to True
.
If you have pre-commit hooks, add an option to turn off your pre-commit hooks. For Git, use --no-verify
and use --config hooks.pre-commit=
for Mercurial.
\"\"
type string command line option --current-version
environment var BUMPVERSION_CURRENT_VERSION
The current version of the software package before bumping. A value for this is required.
"},{"location":"reference/configuration/global/#ignore_missing_files","title":"ignore_missing_files","text":"required No defaultFalse
type boolean command line option --ignore-missing-files
environment var BUMPVERSION_IGNORE_MISSING_FILES
If True
, don\u2019t fail if the configured file is missing.
False
type boolean command line option --ignore-missing-version
environment var BUMPVERSION_IGNORE_MISSING_VERSION
If True
, don\u2019t fail if the version string to be replaced is not found in the file.
Bump version: {current_version} \u2192 {new_version}
type string command line option --message
environment var BUMPVERSION_MESSAGE
The commit message template to use when creating a commit. This is only used when the commit
option is set to True
.
This string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
"},{"location":"reference/configuration/global/#parse","title":"parse","text":"required No default(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)
type string command line option --parse
environment var BUMPVERSION_PARSE
This is the default regular expression (Python regular expression syntax) for finding and parsing the version string into its components. Individual part or file configurations may override this.
The regular expression must be able to parse all strings produced by the configured serialize
value. Named matching groups (\u201c(?P<name>...)
\u201d) indicate the version part the matched value belongs to.
False
type boolean command line option --regex | --no-regex
environment var BUMPVERSION_REGEX
Treat the search
string as a regular expression.
{new_version}
type string command line option --replace
environment var BUMPVERSION_REPLACE
This is the template to create the string that will replace the current version number in the file.
"},{"location":"reference/configuration/global/#search","title":"search","text":"required No default{current_version}
type string command line option --search
environment var BUMPVERSION_SEARCH
This is the template string for searching. It is rendered using the formatting context for searching in the file. Individual file configurations may override this. This can span multiple lines and is templated using Python Format String Syntax. The formatting context reference describes the available variables.
This is useful if there is the remotest possibility that the current version number might be present multiple times in the file and you mean to bump only one of the occurrences.
"},{"location":"reference/configuration/global/#serialize","title":"serialize","text":"required No default[\"{major}.{minor}.{patch}\"]
type an array of strings command line option --serialize
environment var BUMPVERSION_SERIALIZE
This is the default list of templates specifying how to serialize the version parts back to a version string. Individual part or file configurations may override this.
Since version parts can be optional, bumpversion will try the serialization formats beginning with the first and choose the last one where all values can all non-optional values are represented.
In this example (in TOML):
serialize = [\n \"{major}.{minor}.{patch}\",\n \"{major}.{minor}\",\n \"{major}\"\n]\n
Since 0
is optional by default, Version 1.8.9
will serialize to 1.8.9
, 1.9.0
will serialize to 1.9
, and version 2.0.0
will serialize as 2
.
Each string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
"},{"location":"reference/configuration/global/#sign_tags","title":"sign_tags","text":"required No defaultFalse
(Don\u2019t sign tags) type boolean command line option --sign-tags | --no-sign-tags
environment var BUMPVERSION_SIGN_TAGS
If True
, sign the created tag, when tag
is True
.
False
(Don\u2019t create a tag) type boolean command line option --tag | --no-tag
environment var BUMPVERSION_TAG
If True
, create a tag after committing the changes. The tag is named using the tag_name
option.
If you are using git
, don\u2019t forget to git-push
with the --tags
flag when you are done.
Bump version: {current_version} \u2192 {new_version}
type string command line option --tag-message
environment var BUMPVERSION_TAG_MESSAGE
The tag message template to use when creating a tag when tag
is True
This string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
Bump My Version creates an annotated tag in Git by default. To turn this off and create a lightweight tag, you must explicitly set an empty tag_message
value.
v{new_version}
type string command line option --tag-name
environment var BUMPVERSION_TAG_NAME
The template used to render the tag when tag
is True
.
This string is templated using the Python Format String Syntax. The formatting context reference describes the available variables.
"},{"location":"reference/configuration/global/#examples","title":"Examples","text":"TOMLCFG[tool.bumpversion]\nallow_dirty = false\ncommit = false\nmessage = \"Bump version: {current_version} \u2192 {new_version}\"\ncommit_args = \"\"\ntag = false\nsign_tags = false\ntag_name = \"v{new_version}\"\ntag_message = \"Bump version: {current_version} \u2192 {new_version}\"\ncurrent_version = \"1.0.0\"\nparse = \"(?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)\"\nserialize = [\n \"{major}.{minor}.{patch}\"\n]\nsearch = \"{current_version}\"\nreplace = \"{new_version}\"\n
[bumpversion]\nallow_dirty = False\ncommit = False\nmessage = Bump version: {current_version} \u2192 {new_version}\ncommit_args = \ntag = False\nsign_tags = False\ntag_name = v{new_version}\ntag_message = Bump version: {current_version} \u2192 {new_version}\ncurrent_version = 1.0.0\nparse = (?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)\nserialize =\n {major}.{minor}.{patch}\nsearch = {current_version}\nreplace = {new_version}\n
"},{"location":"reference/configuration/version-component/","title":"Version component-specific configuration","text":"Version component configuration is grouped in a [tool.bumpversion.parts.<partname>]
or [bumpversion:part:<partname>]
section, depending on if it is a TOML or INI file, respectfully.
You only need to configure version parts if they deviate from the default, and then you only need to specify the overridden options.
"},{"location":"reference/configuration/version-component/#values","title":"values","text":"required No default numeric (i.e.0
, 1
, 2
, \u2026) type array of strings An explicit list of all values to iterate through when bumping this part. An empty array is treated as indicating numeric
values.
values
, 0
when using numeric values type string When the version part matches this value, it is considered optional when serializing the final version string.
Note
Numeric values are still treated as strings internally, so when specifying an optional value, you must use a string.
"},{"location":"reference/configuration/version-component/#first_value","title":"first_value","text":"required No default The first entry invalues
, 0
when using numeric values type string When the part is reset, the value will be set to the value specified here.
Note
Numeric values are still treated as strings internally, so when specifying a first value, you must use a string.
"},{"location":"reference/configuration/version-component/#independent","title":"independent","text":"required No defaultFalse
type boolean When this value is set to True
, the part is not reset when other parts are incremented. Its incrementation is independent of the other parts. It is useful when you have a build number in your version that is incremented independently of the actual version.
False
(True
if calver_format
is set) type boolean When this value is set to True
, the part is always incremented when the version is bumped, regardless of the target part.
The calver_format
is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the CalVer reference.
[tool.bumpversion.parts.release]\nvalues = [\n \"alpha\",\n \"beta\",\n \"gamma\"\n]\noptional_value = \"gamma\"\n
[bumpversion:part:release]\noptional_value = gamma\nvalues =\n alpha\n beta\n gamma\n
"},{"location":"tutorials/getting-started/","title":"Getting Started","text":""},{"location":"tutorials/getting-started/#installation","title":"Installation","text":"You can download and install the latest version of this software from the Python package index (PyPI) as follows:
pip install --upgrade bump-my-version\n
"},{"location":"tutorials/getting-started/#create-a-default-configuration","title":"Create a default configuration","text":"The default configuration uses a simplified version of semantic versioning.
Note
Python projects can use pyproject.toml
as the --destination
of the sample config.
$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml\n$ cat .bumpversion.toml\n[tool.bumpversion]\ncurrent_version = \"0.1.0\"\nparse = \"(?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)\"\nserialize = [\"{major}.{minor}.{patch}\"]\nsearch = \"{current_version}\"\nreplace = \"{new_version}\"\nregex = false\nignore_missing_version = false\ntag = false\nsign_tags = false\ntag_name = \"v{new_version}\"\ntag_message = \"Bump version: {current_version} \u2192 {new_version}\"\nallow_dirty = false\ncommit = false\nmessage = \"Bump version: {current_version} \u2192 {new_version}\"\ncommit_args = \"\"\n
"},{"location":"tutorials/getting-started/#visualize-the-versioning-path","title":"Visualize the versioning path","text":"You can see the potential versioning paths with the show-bump
subcommand. This visualization will help debug any versioning logic you implement.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0\n \u251c\u2500 minor \u2500 0.2.0\n \u2570\u2500 patch \u2500 0.1.1\n
You can also pass in a specific version to see how bumping that version would work.
Showing the potential versioning path from a specific version$ bump-my-version show-bump 1.2.3\n1.2.3 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0\n \u251c\u2500 minor \u2500 1.3.0\n \u2570\u2500 patch \u2500 1.2.4\n
"},{"location":"tutorials/getting-started/#configure-a-file-to-modify-when-bumping","title":"Configure a file to modify when bumping","text":"Let\u2019s say your version is stored in a file named VERSION
. Every time you bump your version, that file needs to change.
Create the VERSION
file with the current version 0.1.0
:
$ echo \"0.1.0\" >> VERSION\n
Add the following to the .bumpversion.toml
file.
[[tool.bumpversion.files]]\nfilename = \"VERSION\"\n
Now bump-my-version will look in the VERSION
file for the current version in that file and replace it with the new version on each bump-my-version bump
command.
You will increment the version using the bump
subcommand. You \u201cbump\u201d a specific segment of the version. These segments are defined in the parse
configuration. In this configuration ((?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)
) the segments are major
, minor
, patch
.
The --dry-run
option will explain all the steps it performs without permanent changes. Use the -vv
option to get the full description for debugging later.
Note
If you are in a Git or Mercurial repository, you may see additional messages.
Incrementing the minor segment$ bump-my-version bump minor --dry-run -vv\nStarting BumpVersion 0.25.1\nReading configuration\n Reading config file: /users/gettingstarted/.bumpversion.toml\n Parsing current version '0.1.0'\n Parsing version '0.1.0' using regexp '(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)'\n Parsed the following values: major=0, minor=1, patch=0\n Attempting to increment part 'minor'\n Values are now: major=0, minor=2, patch=0\n Serializing version '<bumpversion.Version:major=0, minor=2, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.2.0'\n New version will be '0.2.0'\nDry run active, won't touch any files.\n\nFile VERSION: replace `{current_version}` with `{new_version}`\n Serializing the current version\n Serializing version '<bumpversion.Version:major=0, minor=1, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.1.0'\n Serializing the new version\n Serializing version '<bumpversion.Version:major=0, minor=2, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.2.0'\n Rendering search pattern with context\n No RegEx flag detected. Searching for the default pattern: '0\\.1\\.0'\n Found '0\\.1\\.0' at line 1: 0.1.0\n Would change file VERSION:\n *** before VERSION\n --- after VERSION\n ***************\n *** 1 ****\n ! 0.1.0\n --- 1 ----\n ! 0.2.0\n\nProcessing config file: /users/gettingstarted/.bumpversion.toml\n Serializing version '<bumpversion.Version:major=0, minor=1, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.1.0'\n Serializing version '<bumpversion.Version:major=0, minor=2, patch=0>'\n Using serialization format '{major}.{minor}.{patch}'\n Serialized to '0.2.0'\n Rendering search pattern with context\n No RegEx flag detected. Searching for the default pattern: '0\\.1\\.0'\n Found '0\\.1\\.0' at line 1: 0.1.0\n Would change file /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version:\n *** before /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version\n --- after /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version\n ***************\n *** 1 ****\n ! 0.1.0\n --- 1 ----\n ! 0.2.0\nDone.\n
"},{"location":"tutorials/nav/","title":"Nav","text":"The default configuration uses a simplified version of semantic versioning.
Generating a default configuration$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml\n$ cat .bumpversion.toml\n[tool.bumpversion]\ncurrent_version = \"0.1.0\"\nparse = \"(?P<major>\\\\d+)\\\\.(?P<minor>\\\\d+)\\\\.(?P<patch>\\\\d+)\"\nserialize = [\"{major}.{minor}.{patch}\"]\nsearch = \"{current_version}\"\nreplace = \"{new_version}\"\nregex = false\nignore_missing_version = false\ntag = false\nsign_tags = false\ntag_name = \"v{new_version}\"\ntag_message = \"Bump version: {current_version} \u2192 {new_version}\"\nallow_dirty = false\ncommit = false\nmessage = \"Bump version: {current_version} \u2192 {new_version}\"\ncommit_args = \"\"\n
"},{"location":"tutorials/semantic-versioning-example/#visualize-the-versioning-path","title":"Visualize the versioning path","text":"You can see the potential versioning paths with the show-bump
subcommand.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0\n \u251c\u2500 minor \u2500 0.2.0\n \u2570\u2500 patch \u2500 0.1.1\n$ bump-my-version show-bump 1.2.3\n1.2.3 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0\n \u251c\u2500 minor \u2500 1.3.0\n \u2570\u2500 patch \u2500 1.2.4\n
The default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?
"},{"location":"tutorials/semantic-versioning-example/#add-support-for-pre-release-versions","title":"Add support for pre-release versions","text":"Alter the parse
configuration to support pre-release versions. This parse
option uses an extended (or verbose) regular expression to extract the version components from the current version.
parse = \"\"\"(?x)\n (?P<major>0|[1-9]\\\\d*)\\\\.\n (?P<minor>0|[1-9]\\\\d*)\\\\.\n (?P<patch>0|[1-9]\\\\d*)\n (?:\n - # dash separator for pre-release section\n (?P<pre_l>[a-zA-Z-]+) # pre-release label\n (?P<pre_n>0|[1-9]\\\\d*) # pre-release version number\n )? # pre-release section is optional\n\"\"\"\n
Alter the serialize
configuration to support pre-release versions.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\n
Add a new configuration section for the pre_l
part.
[tool.bumpversion.parts.pre_l]\nvalues = [\"dev\", \"rc\", \"final\"]\noptional_value = \"final\"\n
"},{"location":"tutorials/semantic-versioning-example/#visualize-the-new-versioning-path","title":"Visualize the new versioning path","text":"Now when you run bump-my-version show-bump
, you can see the new pre-release versioning path.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0-dev0\n \u251c\u2500 minor \u2500 0.2.0-dev0\n \u251c\u2500 patch \u2500 0.1.1-dev0\n \u251c\u2500 pre_l \u2500 invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.\n \u2570\u2500 pre_n \u2500 0.1.0-final1\n
The pre_l
is not bump-able because it is already at the maximum value. The pre_n
is bump-able because it is not at the maximum value.
If we run bump-my-version show-bump 1.0.0-dev0
, we can see the new versioning path for a dev
starting version.
$ bump-my-version show-bump 1.0.0-dev0\n1.0.0-dev0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u251c\u2500 pre_l \u2500 1.0.0-rc0\n \u2570\u2500 pre_n \u2500 1.0.0-dev1\n
Finally, we can see the new versioning path for a rc
starting version.
$ bump-my-version show-bump 1.0.0-rc0 \n1.0.0-rc0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u251c\u2500 pre_l \u2500 1.0.0\n \u2570\u2500 pre_n \u2500 1.0.0-rc1\n
The full development and release path is:
1.0.0
bump patch
\u2192 1.0.1-dev0
bump pre_n
\u2192 1.0.1-dev1
bump pre_l
\u2192 1.0.1-rc0
bump pre_n
\u2192 1.0.1-rc1
bump pre_l
\u2192 1.0.1
bump-my-version bump pre_n
.bump-my-version bump pre_l
.bump-my-version bump pre_n
.bump-my-version bump pre_l
.The pre_n
or pre-release number is a number that increases with each pre-release. You can automate this by changing the serialization configuration.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}\",\n \"{major}.{minor}.{patch}\",\n]\n
The distance_to_latest_tag
is a special value that is replaced with the number of commits since the last tag. This is a good value to use for the pre_n
because it will always increase with each commit.
Now when you run bump-my-version show-bump
, you can see the new pre-release versioning path.
$ bump-my-version show-bump\n0.1.0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 1.0.0-dev0\n \u251c\u2500 minor \u2500 0.2.0-dev0\n \u251c\u2500 patch \u2500 0.1.1-dev0\n \u2570\u2500 pre_l \u2500 invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.\n$ bump-my-version show-bump 1.0.0-dev0\n1.0.0-dev0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u2570\u2500 pre_l \u2500 1.0.0-rc0\n$ bump-my-version show-bump 1.0.0-rc0 \n1.0.0-rc0 \u2500\u2500 bump \u2500\u252c\u2500 major \u2500 2.0.0-dev0\n \u251c\u2500 minor \u2500 1.1.0-dev0\n \u251c\u2500 patch \u2500 1.0.1-dev0\n \u2570\u2500 pre_l \u2500 1.0.0\n
The pre_n
path is now missing because it is automated.
The full development and release path now is:
1.0.0
bump patch
\u2192 1.0.1-dev0
1.0.1-dev1
bump pre_l
\u2192 1.0.1-rc0
1.0.1-rc1
bump pre_l
\u2192 1.0.1
bump-my-version bump pre_l
.bump-my-version bump pre_l
.