TYPE:
- ChainMap
+ MutableMapping
dry_runCreate a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. -Otherwise, it utilizes an annotated tag.
+Otherwise, it uses an annotated tag. @@ -2412,7 +2412,7 @@Create a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. -Otherwise, it utilizes an annotated tag.
+Otherwise, it uses an annotated tag. @@ -2499,6 +2499,7 @@path_in_repo(path: Union[Path, str]) -> bool
+Return whether a path is inside this repository.
+ +format_and_raise_error(
+ exc: Union[TypeError, subprocess.CalledProcessError]
+) -> None
+Format the error message from an exception and re-raise it as a BumpVersionError.
+ +run_command(
+ command: list, env: Optional[dict] = None
+) -> CompletedProcess
+Run a shell command and return its output.
+ +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\nPlease find the changelog here: CHANGELOG.md
"},{"location":"#semantic-versioning-example","title":"Semantic versioning example","text":""},{"location":"#create-a-default-configuration","title":"Create a default configuration","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 = \"\"\nYou 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\nThe default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?
"},{"location":"#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 parts 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\"\"\"\nAlter the serialize configuration to support pre-release versions.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\nAdd a new configuration section for the pre_l part.
[tool.bumpversion.parts.pre_l]\nvalues = [\"dev\", \"rc\", \"final\"]\noptional_value = \"final\"\nNow 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\nThe 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\nFinally, 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\nThe full development and release path is:
1.0.0bump patch \u2192 1.0.1-dev0bump pre_n \u2192 1.0.1-dev1bump pre_l \u2192 1.0.1-rc0bump pre_n \u2192 1.0.1-rc1bump pre_l \u2192 1.0.1bump-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 my changing the serialization configuration.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}\",\n \"{major}.{minor}.{patch}\",\n]\nThe 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\nThe pre_n path is now missing because it is automated.
The full development and release path now is:
1.0.0bump patch \u2192 1.0.1-dev01.0.1-dev1bump pre_l \u2192 1.0.1-rc01.0.1-rc1bump pre_l \u2192 1.0.1bump-my-version bump pre_l.bump-my-version bump pre_l.Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors
See also our CONTRIBUTING.md
Development of this happens on GitHub, patches including tests, and documentation are very welcome, as well as bug reports! Please open an issue if this tool does not support every aspect of bumping versions in your development workflow, as it is intended to be very versatile.
"},{"location":"#license","title":"License","text":"Bump My Version is licensed under the MIT License - see the LICENSE file for details
"},{"location":"CHANGELOG/","title":"Changelog","text":""},{"location":"CHANGELOG/#changelog","title":"Changelog","text":""},{"location":"CHANGELOG/#0243-2024-07-17","title":"0.24.3 (2024-07-17)","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes","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_1","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_2","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","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_3","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_2","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_4","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_4","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_5","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_6","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_7","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_8","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_9","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_10","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_11","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_12","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_13","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_14","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_15","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_7","title":"New","text":"--ignore-missing-files option to bump. fcfaac7ignore_missing_files. b473a19Compare the full difference.
"},{"location":"CHANGELOG/#fixes_16","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_17","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_18","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_19","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_20","title":"Fixes","text":"Refactored the create subcommand. f529d28
Added show-bump subcommand. 0bbd814
bump commandCompare the full difference.
"},{"location":"CHANGELOG/#fixes_21","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_22","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_10","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_23","title":"Fixes","text":"Fixed testing automation. 19215f1
--no-tag flagCompare the full difference.
"},{"location":"CHANGELOG/#fixes_24","title":"Fixes","text":"Fix miscast of current_version. b8ea252
Fixes #99
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_25","title":"Fixes","text":"Fixed regression in config update. 2bbbd74
Fixes #108
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_26","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_27","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_28","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_29","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_30","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_20","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_15","title":"Updates","text":"Refactored file resolution, inclusion, and exclusion. 646af54
resolved_filemap propertyfiles_to_modify propertyCompare the full difference.
"},{"location":"CHANGELOG/#fixes_31","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_32","title":"Fixes","text":"Fixed modified context when committing. 130bbe0
Compare the full difference.
"},{"location":"CHANGELOG/#other_22","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_16","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_17","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_33","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_34","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_35","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 dictbranch_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--helpCompare the full difference.
"},{"location":"CHANGELOG/#fixes_36","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_37","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_38","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_39","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_40","title":"Fixes","text":"Fixes issue when new version equals current version. 64b0de3
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_41","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\nOnce setup, you should be able to run tests:
pytest\nPre-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\nPlease, 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!wipIf 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":"Explanation","text":""},{"location":"explanation/mental-model/","title":"The mental model used by Bump My Version","text":""},{"location":"explanation/mental-model/#overview","title":"Overview","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.
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\nThe 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\nProviding 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}\"\nIf 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\"\nThen 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}\\\"\"\nCalendar 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}\"\nYou can look up the regular expressions for the CalVer format in the CalVer reference.
"},{"location":"howtos/calver/#expected-behavior","title":"Expected behavior","text":"You can find out more about the logic behind the CalVer incrementing in the CalVer reference.
"},{"location":"howtos/calver/#bumping-the-release-resets-the-patch-part","title":"Bumping the release resets the patch part","text":"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\nThe 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\nCalendar 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\nHowever, 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\nYou 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)\nrelease-channels.yaml file:
stable: \"v2.21.4\"\nYou 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\"\nWhile 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\nTo 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}\"\nMany 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'\nThe 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'\nWe 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'\nThe 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}\"\nUsing 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\"\"\"\nalways_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.Version bump your Python project.
Usage:
bump-my-version [OPTIONS] COMMAND [ARGS]...\nOptions:
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]...\nOptions:
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]...\nOptions:
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]\nOptions:
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_versionbump-my-version show files.0.filenamebump-my-version show scm_info.branch_namebump-my-version show current_version scm_info.distance_to_latest_tagUsage:
bump-my-version show [OPTIONS] [ARGS]...\nOptions:
Name Type Description Default--config-file path Config file to read most of the variables from. None -f, --format choice (default | yaml | json) Config file to read most of the variables from. default -i, --increment text Increment the version part 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]\nOptions:
Name Type Description Default--config-file path Config file to read most of the variables from. None --ascii boolean Use ASCII characters only. False --help boolean Show this message and exit. False"},{"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.tomlsetup.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/#global-configuration","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/#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/#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/#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/#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/#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]\nSince 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/#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/#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}\nVersion part 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/#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/#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/#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\nThis section configures which files Bump My Version should update by replacing their current version with the newly bumped version.
"},{"location":"reference/configuration/#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/#serialize_1","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/#search_1","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/#regex_1","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/#ignore_missing_version_1","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/#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/#examples_2","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}\"\nINI-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}\nThese 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 part> Each version part 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 part> Each version part 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 part> 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.
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}\"\nAlternatively, 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}\"\"\"\nOnly 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}}\"\nsearch = \"{current_version} date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}\"\nGets rendered to:
1\\.2\\.3 date-released: \\d{4}-\\d{2}-\\d{2}\nThis 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\nand you use this search pattern:
[Unreleased] \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\nBump 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}}\nA 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]\nBump-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]\nBy 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]\nVersion 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]\nBumping 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\"\nBumping 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\nUtilities 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]\nGiven 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\nFind 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":"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\nGuess 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\nConvert a string to a boolean.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.listify","title":"listify","text":"listify(s: str) -> list\nConvert 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\nConvert a string to None.
"},{"location":"reference/api/bumpversion/bump/","title":"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: ChainMap,\n dry_run: bool = False,\n) -> None\nCommit 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: ChainMap
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\nBump the version_part to the next value or set the version to new_version.
Parameters:
version_part The version part 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\nBump 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":"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\nChange 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\nVersion 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\nReplace 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\nPrint 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\nShow current configuration information.
ARGS may contain one or more configuration attributes. For example:
bump-my-version show current_versionbump-my-version show files.0.filenamebump-my-version show scm_info.branch_namebump-my-version show current_version scm_info.distance_to_latest_tagshow_bump(\n version: str, config_file: Optional[str], ascii: bool\n) -> None\nShow the possible versions resulting from the bump subcommand.
"},{"location":"reference/api/bumpversion/context/","title":"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\nThe 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\nConvert 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\nReturn 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\nReturn 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\nReturn a dict of the environment with keys wrapped in ${}.
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.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":"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)\nA 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\nReturn 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\nMake 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\nWrite 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)\nA 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\nUpdate 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)\nA 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\nUpdate 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\nDoes 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\nLog 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\nModify 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]\nResolve 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/indented_logger/","title":"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\nThe current indent level.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.indent_str","title":"indent_strproperty","text":"indent_str: str\nThe 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\nDecrease the indent level by amount.
indent(amount: int = 1) -> None\nIncrease the indent level by amount.
process(\n msg: str, kwargs: Optional[MutableMapping[str, Any]]\n) -> Tuple[str, MutableMapping[str, Any]]\nProcess 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\nReset the indent level to zero.
"},{"location":"reference/api/bumpversion/scm/","title":"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\nAdd a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.assert_nondirty","title":"assert_nondirtyclassmethod","text":"assert_nondirty() -> None\nAssert 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\nReturn 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\nCreate a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. Otherwise, it utilizes 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\nAdd a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.assert_nondirty","title":"assert_nondirtyclassmethod","text":"assert_nondirty() -> None\nAssert 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\nReturn 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\nCreate a tag of the new_version in VCS.
If only name is given, bumpversion uses a lightweight tag. Otherwise, it utilizes 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 branch_name: Optional[str] = None,\n short_branch_name: Optional[str] = None,\n dirty: Optional[bool] = None,\n)\nInformation about the current source code manager and state.
"},{"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\nAdd a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.assert_nondirty","title":"assert_nondirtyclassmethod","text":"assert_nondirty() -> None\nAssert 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\nCommit 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\nCommit 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\nFormat 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]\nReturn 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]\nReturn the version from a tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.is_usable","title":"is_usableclassmethod","text":"is_usable() -> bool\nIs 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\nReturn 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\nCreate 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\nTag 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\nReturn a dict with the latest source code management info.
"},{"location":"reference/api/bumpversion/show/","title":"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\nShow current version or configuration information.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_default","title":"output_default","text":"output_default(value: dict) -> None\nOutput 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\nOutput the value as json.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_yaml","title":"output_yaml","text":"output_yaml(value: dict) -> None\nOutput 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\nGet 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
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\nGet a logger with indentation.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_error","title":"print_error","text":"print_error(msg: str) -> None\nRaise an error and exit.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_info","title":"print_info","text":"print_info(msg: str) -> None\nEcho a message to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_warning","title":"print_warning","text":"print_warning(msg: str) -> None\nEcho a warning to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.setup_logging","title":"setup_logging","text":"setup_logging(verbose: int = 0) -> None\nConfigure the logging.
"},{"location":"reference/api/bumpversion/utils/","title":"General utilities.
"},{"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]\nExtract 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.get_nested_value","title":"get_nested_value","text":"get_nested_value(d: dict, path: str) -> Any\nRetrieves 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\nReturn 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\nRender 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]\nReturn 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\nSort a dictionary recursively.
"},{"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\nSets 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.
"},{"location":"reference/api/bumpversion/version_part/","title":"Module for managing Versions and their internal parts.
"},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.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)\nHold a complete representation of a version string.
"},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig.order","title":"orderproperty","text":"order: List[str]\nReturn 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/version_part/#bumpversion.version_part.VersionConfig-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig.parse","title":"parse","text":"parse(\n version_string: Optional[str] = None,\n) -> Optional[Version]\nParse a version string into a Version object.
Parameters:
version_string Version string to parse
TYPE: Optional[str]
DEFAULT: None
Returns:
Optional[Version] A Version object representing the string.
"},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig.serialize","title":"serialize","text":"serialize(version: Version, context: MutableMapping) -> str\nSerialize 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/version_part/#bumpversion.version_part-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/visualize/","title":"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)\nA 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\nReturn 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]\nReturn 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\nReturn 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\nReturn 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' '\nParameters:
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\nOutput a visualization of the bump-my-version bump process.
"},{"location":"reference/api/bumpversion/yaml_dump/","title":"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\nAdd 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\nDump 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturns 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\nReturn 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]\nApply the defaults to the parsed config.
"},{"location":"reference/api/bumpversion/config/create/","title":"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\nCreate 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]\nGet the default configuration and the configuration from the destination.
"},{"location":"reference/api/bumpversion/config/files/","title":"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]\nFind 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]\nRead 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]\nParse 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\nUpdate 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
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]\nParse 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\nUpdate 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
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]\nReturn 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]]\nReturn the cached resolved filemap.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.version_config","title":"version_configproperty","text":"version_config: 'VersionConfig'\nReturn 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\nAdd 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\"\nReturn 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__()\nReturn 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]\nRender 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":"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]\nMake sure all version parts 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]\nMake sure all version parts 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]\nReturn 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":"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\nReturn a VersionSpec for PEP 440.
"},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions.semver_spec","title":"semver_spec","text":"semver_spec() -> VersionSpec\nReturn a VersionSpec for SEMVER.
"},{"location":"reference/api/bumpversion/versioning/functions/","title":"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\nReturn 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\nReturn 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\nIncrease 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\nIncrease 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\nReturn the item after value in the list.
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)\nThe 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'\nIncrease 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]\nReturn 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]\nReturn 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)\nRepresent 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\nIs 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\nIs the part optional?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.value","title":"valueproperty","text":"value: str\nReturn 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'\nReturn a part with bumped value.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.copy","title":"copy","text":"copy() -> 'VersionComponent'\nReturn a copy of the part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.null","title":"null","text":"null() -> 'VersionComponent'\nReturn 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\nShould 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\nThe 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\nThe 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\nThe 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\nIs 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\nThe value that is optional to include in the version.
class-attribute instance-attribute","text":"values: Optional[list] = None\nThe 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\nGenerate 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\nSet 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)\nThe 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'\nGenerate 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]\nReturn 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":"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\nSort 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]\nParse 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\nAttempts 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/subcommands/","title":"Subcommand reference","text":"Bump-my-version uses subcommands to focus its functionality.
bump triggers the version incrementing workflowreplace replaces the version in files without triggering a version increment.sample-config helps new users configure bumpy-my-version by printing a sample configuration file.show provides access to current configuration information.show-bump helps developers understand the current versioning convention by showing the possible versions resulting from the bump subcommand.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\nYou 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}\nYour 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\nThe 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 = \"\"\nYou 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\nThe 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 parts 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\"\"\"\nAlter the serialize configuration to support pre-release versions.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\nAdd a new configuration section for the pre_l part.
[tool.bumpversion.parts.pre_l]\nvalues = [\"dev\", \"rc\", \"final\"]\noptional_value = \"final\"\nNow 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\nThe 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\nFinally, 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\nThe full development and release path is:
1.0.0bump patch \u2192 1.0.1-dev0bump pre_n \u2192 1.0.1-dev1bump pre_l \u2192 1.0.1-rc0bump pre_n \u2192 1.0.1-rc1bump pre_l \u2192 1.0.1bump-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 my changing the serialization configuration.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}\",\n \"{major}.{minor}.{patch}\",\n]\nThe 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\nThe pre_n path is now missing because it is automated.
The full development and release path now is:
1.0.0bump patch \u2192 1.0.1-dev01.0.1-dev1bump pre_l \u2192 1.0.1-rc01.0.1-rc1bump pre_l \u2192 1.0.1bump-my-version bump pre_l.bump-my-version bump pre_l.There are two modes of operation: On the command line for single-file operation and using a configuration file (pyproject.toml or .bumpversion.toml) for more complex multi-file processes. We recommend using a configuration file for all but the simplest of projects.
Warning
The invocation of bump-my-version changed in version 0.6.0. It splits functionality into sub-commands. It remains backward-compatible with previous versions. Previous usage is discouraged and may be removed in a 1.0 release.
bump-my-version bump [OPTIONS] [ARGS]...\nThe bump sub-command triggers a version increment. The complete list of options is available. The ARGS may contain a VERSION_PART or FILES
VERSION_PART","text":"[optional]
The part of the version to increase, e.g., minor.
Valid values include those given in the --serialize / --parse option.
For example, if the current version is 0.5.1 and you want to bump it to 0.6.0:
bump-my-version bump minor\nFILES","text":"[optional] default: None
The additional file(s) to modify.
This file is added to the list of files specified in the configuration file. If you want to rewrite only files specified on the command line, use --no-configured-files.
For example, if the current version is 1.1.9 and you want to bump the version to 2.0.0 and also change the version in the _version.txt file:
bump-my-version bump major _version.txt\nIf you want to bump the current version of 1.1.9 to 2.0.0\u00a0and only change the _version.txt file:
bump-my-version bump --no-configured-files major _version.txt\nbump-my-version show [OPTIONS] [ARGS]\nThe show subcommand allows you to output the entire or parts of the configuration to the console. The default invocation will output in the default format. The default format changes if one or more than one item is requested. If more than one item is asked for, it outputs the result of Python\u2019s pprint function. If only one thing is asked for, it outputs that value only.
$ bump-my-version show current_version\n1.0.0\n$ bump-my-version show current_version commit\n{'current_version': '1.0.0', 'commit': False}\nYou can use the --increment option to enable a new_version key.
$ bump-my-version show --increment minor current_version new_version\n{'current_version': '1.0.0', 'new_version': '1.1.0'}\nYou can also specify the output to be in JSON or YAML format:
$ bump-my-version show --format yaml current_version\ncurrent_version: \"1.0.0\"\n$ bump-my-version show --format yaml current_version commit\ncurrent_version: \"1.0.0\"\ncommit: false\n$ bump-my-version show --format json current_version\n{\n \"current_version\": \"1.0.0\"\n}\n$ bump-my-version show --format json current_version commit\n{\n \"current_version\": \"1.0.0\",\n \"commit\": false,\n}\nMore complex workflows may require you to change one or more files without changing the current_version in the configuration file.
The replace sub-command works identically to the bump sub-command except for the following:
Note
If you do not include the --new-version option, the new_version context variable will be None.
One way of providing the --new-version option is to use the bump-my-version show subcommand with an environment variable:
$ export BUMPVERSION_NEW_VERSION=$(bump-my-version show new_version --increment <versionpart>)\n$ bump-my-version replace\nBump 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\nPlease find the changelog here: CHANGELOG.md
"},{"location":"#semantic-versioning-example","title":"Semantic versioning example","text":""},{"location":"#create-a-default-configuration","title":"Create a default configuration","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 = \"\"\nYou 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\nThe default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?
"},{"location":"#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 parts 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\"\"\"\nAlter the serialize configuration to support pre-release versions.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\nAdd a new configuration section for the pre_l part.
[tool.bumpversion.parts.pre_l]\nvalues = [\"dev\", \"rc\", \"final\"]\noptional_value = \"final\"\nNow 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\nThe 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\nFinally, 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\nThe full development and release path is:
1.0.0bump patch \u2192 1.0.1-dev0bump pre_n \u2192 1.0.1-dev1bump pre_l \u2192 1.0.1-rc0bump pre_n \u2192 1.0.1-rc1bump pre_l \u2192 1.0.1bump-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 my changing the serialization configuration.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}\",\n \"{major}.{minor}.{patch}\",\n]\nThe 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\nThe pre_n path is now missing because it is automated.
The full development and release path now is:
1.0.0bump patch \u2192 1.0.1-dev01.0.1-dev1bump pre_l \u2192 1.0.1-rc01.0.1-rc1bump pre_l \u2192 1.0.1bump-my-version bump pre_l.bump-my-version bump pre_l.Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors
See also our CONTRIBUTING.md
Development of this happens on GitHub, patches including tests, and documentation are very welcome, as well as bug reports! Please open an issue if this tool does not support every aspect of bumping versions in your development workflow, as it is intended to be very versatile.
"},{"location":"#license","title":"License","text":"Bump My Version is licensed under the MIT License - see the LICENSE file for details
"},{"location":"CHANGELOG/","title":"Changelog","text":""},{"location":"CHANGELOG/#changelog","title":"Changelog","text":""},{"location":"CHANGELOG/#0243-2024-07-17","title":"0.24.3 (2024-07-17)","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes","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_1","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_2","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","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_3","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_2","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_4","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_4","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_5","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_6","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_7","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_8","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_9","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_10","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_11","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_12","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_13","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_14","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_15","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_7","title":"New","text":"--ignore-missing-files option to bump. fcfaac7ignore_missing_files. b473a19Compare the full difference.
"},{"location":"CHANGELOG/#fixes_16","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_17","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_18","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_19","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_20","title":"Fixes","text":"Refactored the create subcommand. f529d28
Added show-bump subcommand. 0bbd814
bump commandCompare the full difference.
"},{"location":"CHANGELOG/#fixes_21","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_22","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_10","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_23","title":"Fixes","text":"Fixed testing automation. 19215f1
--no-tag flagCompare the full difference.
"},{"location":"CHANGELOG/#fixes_24","title":"Fixes","text":"Fix miscast of current_version. b8ea252
Fixes #99
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_25","title":"Fixes","text":"Fixed regression in config update. 2bbbd74
Fixes #108
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_26","title":"Fixes","text":"Compare the full difference.
"},{"location":"CHANGELOG/#fixes_27","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_28","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_29","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_30","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_20","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_15","title":"Updates","text":"Refactored file resolution, inclusion, and exclusion. 646af54
resolved_filemap propertyfiles_to_modify propertyCompare the full difference.
"},{"location":"CHANGELOG/#fixes_31","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_32","title":"Fixes","text":"Fixed modified context when committing. 130bbe0
Compare the full difference.
"},{"location":"CHANGELOG/#other_22","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_16","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_17","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_33","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_34","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_35","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 dictbranch_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--helpCompare the full difference.
"},{"location":"CHANGELOG/#fixes_36","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_37","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_38","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_39","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_40","title":"Fixes","text":"Fixes issue when new version equals current version. 64b0de3
Compare the full difference.
"},{"location":"CHANGELOG/#fixes_41","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\nOnce setup, you should be able to run tests:
pytest\nPre-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\nPlease, 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!wipIf 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":"Explanation","text":""},{"location":"explanation/mental-model/","title":"The mental model used by Bump My Version","text":""},{"location":"explanation/mental-model/#overview","title":"Overview","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.
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\nThe 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\nProviding 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}\"\nIf 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\"\nThen 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}\\\"\"\nCalendar 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}\"\nYou can look up the regular expressions for the CalVer format in the CalVer reference.
"},{"location":"howtos/calver/#expected-behavior","title":"Expected behavior","text":"You can find out more about the logic behind the CalVer incrementing in the CalVer reference.
"},{"location":"howtos/calver/#bumping-the-release-resets-the-patch-part","title":"Bumping the release resets the patch part","text":"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\nThe 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\nCalendar 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\nHowever, 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\nYou 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)\nrelease-channels.yaml file:
stable: \"v2.21.4\"\nYou 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\"\nWhile 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\nTo 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}\"\nMany 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'\nThe 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'\nWe 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'\nThe 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}\"\nUsing 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\"\"\"\nalways_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.Version bump your Python project.
Usage:
bump-my-version [OPTIONS] COMMAND [ARGS]...\nOptions:
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]...\nOptions:
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]...\nOptions:
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]\nOptions:
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_versionbump-my-version show files.0.filenamebump-my-version show scm_info.branch_namebump-my-version show current_version scm_info.distance_to_latest_tagUsage:
bump-my-version show [OPTIONS] [ARGS]...\nOptions:
Name Type Description Default--config-file path Config file to read most of the variables from. None -f, --format choice (default | yaml | json) Config file to read most of the variables from. default -i, --increment text Increment the version part 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]\nOptions:
Name Type Description Default--config-file path Config file to read most of the variables from. None --ascii boolean Use ASCII characters only. False --help boolean Show this message and exit. False"},{"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.tomlsetup.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/#global-configuration","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/#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/#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/#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/#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/#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]\nSince 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/#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/#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}\nVersion part 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/#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/#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/#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\nThis section configures which files Bump My Version should update by replacing their current version with the newly bumped version.
"},{"location":"reference/configuration/#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/#serialize_1","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/#search_1","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/#regex_1","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/#ignore_missing_version_1","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/#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/#examples_2","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}\"\nINI-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}\nThese 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 part> Each version part 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 part> Each version part 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 part> 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.
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}\"\nAlternatively, 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}\"\"\"\nOnly 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}}\"\nsearch = \"{current_version} date-released: \\d{{4}}-\\d{{2}}-\\d{{2}}\"\nGets rendered to:
1\\.2\\.3 date-released: \\d{4}-\\d{2}-\\d{2}\nThis 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\nand you use this search pattern:
[Unreleased] \\\\d{{4}}-\\\\d{{2}}-\\\\d{{2}}\nBump 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}}\nA 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]\nBump-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]\nBy 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]\nVersion 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]\nBumping 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\"\nBumping 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\nUtilities 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]\nGiven 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\nFind 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":"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\nGuess 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\nConvert a string to a boolean.
"},{"location":"reference/api/bumpversion/autocast/#bumpversion.autocast.listify","title":"listify","text":"listify(s: str) -> list\nConvert 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\nConvert a string to None.
"},{"location":"reference/api/bumpversion/bump/","title":"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\nCommit 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\nBump the version_part to the next value or set the version to new_version.
Parameters:
version_part The version part 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\nBump 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":"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\nChange 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\nVersion 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\nReplace 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\nPrint 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\nShow current configuration information.
ARGS may contain one or more configuration attributes. For example:
bump-my-version show current_versionbump-my-version show files.0.filenamebump-my-version show scm_info.branch_namebump-my-version show current_version scm_info.distance_to_latest_tagshow_bump(\n version: str, config_file: Optional[str], ascii: bool\n) -> None\nShow the possible versions resulting from the bump subcommand.
"},{"location":"reference/api/bumpversion/context/","title":"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\nThe 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\nConvert 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\nReturn 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\nReturn 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\nReturn a dict of the environment with keys wrapped in ${}.
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.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":"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)\nA 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\nReturn 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\nMake 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\nWrite 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)\nA 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\nUpdate 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)\nA 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\nUpdate 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\nDoes 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\nLog 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\nModify 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]\nResolve 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/indented_logger/","title":"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\nThe current indent level.
"},{"location":"reference/api/bumpversion/indented_logger/#bumpversion.indented_logger.IndentedLoggerAdapter.indent_str","title":"indent_strproperty","text":"indent_str: str\nThe 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\nDecrease the indent level by amount.
indent(amount: int = 1) -> None\nIncrease the indent level by amount.
process(\n msg: str, kwargs: Optional[MutableMapping[str, Any]]\n) -> Tuple[str, MutableMapping[str, Any]]\nProcess 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\nReset the indent level to zero.
"},{"location":"reference/api/bumpversion/scm/","title":"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\nAdd a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Git.assert_nondirty","title":"assert_nondirtyclassmethod","text":"assert_nondirty() -> None\nAssert 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\nReturn 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\nCreate 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\nAdd a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.Mercurial.assert_nondirty","title":"assert_nondirtyclassmethod","text":"assert_nondirty() -> None\nAssert 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\nReturn 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\nCreate 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 branch_name: Optional[str] = None,\n short_branch_name: Optional[str] = None,\n repository_root: Optional[Path] = None,\n dirty: Optional[bool] = None,\n)\nInformation 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\nReturn 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\nAdd a path to the VCS.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.assert_nondirty","title":"assert_nondirtyclassmethod","text":"assert_nondirty() -> None\nAssert 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\nCommit 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\nCommit 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\nFormat 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]\nReturn 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]\nReturn the version from a tag.
"},{"location":"reference/api/bumpversion/scm/#bumpversion.scm.SourceCodeManager.is_usable","title":"is_usableclassmethod","text":"is_usable() -> bool\nIs 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\nReturn 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\nCreate 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\nTag 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\nReturn a dict with the latest source code management info.
"},{"location":"reference/api/bumpversion/show/","title":"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\nShow current version or configuration information.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_default","title":"output_default","text":"output_default(value: dict) -> None\nOutput 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\nOutput the value as json.
"},{"location":"reference/api/bumpversion/show/#bumpversion.show.output_yaml","title":"output_yaml","text":"output_yaml(value: dict) -> None\nOutput 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\nGet 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
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\nGet a logger with indentation.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_error","title":"print_error","text":"print_error(msg: str) -> None\nRaise an error and exit.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_info","title":"print_info","text":"print_info(msg: str) -> None\nEcho a message to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.print_warning","title":"print_warning","text":"print_warning(msg: str) -> None\nEcho a warning to the console.
"},{"location":"reference/api/bumpversion/ui/#bumpversion.ui.setup_logging","title":"setup_logging","text":"setup_logging(verbose: int = 0) -> None\nConfigure the logging.
"},{"location":"reference/api/bumpversion/utils/","title":"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]\nExtract 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\nFormat 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\nRetrieves 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\nReturn 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\nRender 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]\nReturn 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\nSort 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\nRun 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\nSets 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.
"},{"location":"reference/api/bumpversion/version_part/","title":"Module for managing Versions and their internal parts.
"},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part-classes","title":"Classes","text":""},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.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)\nHold a complete representation of a version string.
"},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig-attributes","title":"Attributes","text":""},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig.order","title":"orderproperty","text":"order: List[str]\nReturn 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/version_part/#bumpversion.version_part.VersionConfig-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig.parse","title":"parse","text":"parse(\n version_string: Optional[str] = None,\n) -> Optional[Version]\nParse a version string into a Version object.
Parameters:
version_string Version string to parse
TYPE: Optional[str]
DEFAULT: None
Returns:
Optional[Version] A Version object representing the string.
"},{"location":"reference/api/bumpversion/version_part/#bumpversion.version_part.VersionConfig.serialize","title":"serialize","text":"serialize(version: Version, context: MutableMapping) -> str\nSerialize 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/version_part/#bumpversion.version_part-functions","title":"Functions","text":""},{"location":"reference/api/bumpversion/visualize/","title":"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)\nA 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\nReturn 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]\nReturn 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\nReturn 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\nReturn 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' '\nParameters:
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\nOutput a visualization of the bump-my-version bump process.
"},{"location":"reference/api/bumpversion/yaml_dump/","title":"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\nAdd 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\nDump 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturn 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\nReturns 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\nReturn 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]\nApply the defaults to the parsed config.
"},{"location":"reference/api/bumpversion/config/create/","title":"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\nCreate 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]\nGet the default configuration and the configuration from the destination.
"},{"location":"reference/api/bumpversion/config/files/","title":"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]\nFind 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]\nRead 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]\nParse 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\nUpdate 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
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]\nParse 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\nUpdate 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
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]\nReturn 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]]\nReturn the cached resolved filemap.
"},{"location":"reference/api/bumpversion/config/models/#bumpversion.config.models.Config.version_config","title":"version_configproperty","text":"version_config: 'VersionConfig'\nReturn 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\nAdd 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\"\nReturn 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__()\nReturn 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]\nRender 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":"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]\nMake sure all version parts 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]\nMake sure all version parts 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]\nReturn 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":"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\nReturn a VersionSpec for PEP 440.
"},{"location":"reference/api/bumpversion/versioning/conventions/#bumpversion.versioning.conventions.semver_spec","title":"semver_spec","text":"semver_spec() -> VersionSpec\nReturn a VersionSpec for SEMVER.
"},{"location":"reference/api/bumpversion/versioning/functions/","title":"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\nReturn 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\nReturn 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\nIncrease 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\nIncrease 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\nReturn the item after value in the list.
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)\nThe 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'\nIncrease 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]\nReturn 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]\nReturn 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)\nRepresent 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\nIs 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\nIs the part optional?
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.value","title":"valueproperty","text":"value: str\nReturn 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'\nReturn a part with bumped value.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.copy","title":"copy","text":"copy() -> 'VersionComponent'\nReturn a copy of the part.
"},{"location":"reference/api/bumpversion/versioning/models/#bumpversion.versioning.models.VersionComponent.null","title":"null","text":"null() -> 'VersionComponent'\nReturn 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\nShould 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\nThe 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\nThe 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\nThe 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\nIs 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\nThe value that is optional to include in the version.
class-attribute instance-attribute","text":"values: Optional[list] = None\nThe 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\nGenerate 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\nSet 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)\nThe 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'\nGenerate 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]\nReturn 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":"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\nSort 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]\nParse 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\nAttempts 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/subcommands/","title":"Subcommand reference","text":"Bump-my-version uses subcommands to focus its functionality.
bump triggers the version incrementing workflowreplace replaces the version in files without triggering a version increment.sample-config helps new users configure bumpy-my-version by printing a sample configuration file.show provides access to current configuration information.show-bump helps developers understand the current versioning convention by showing the possible versions resulting from the bump subcommand.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\nYou 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}\nYour 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\nThe 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 = \"\"\nYou 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\nThe 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 parts 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\"\"\"\nAlter the serialize configuration to support pre-release versions.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{pre_n}\",\n \"{major}.{minor}.{patch}\",\n]\nAdd a new configuration section for the pre_l part.
[tool.bumpversion.parts.pre_l]\nvalues = [\"dev\", \"rc\", \"final\"]\noptional_value = \"final\"\nNow 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\nThe 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\nFinally, 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\nThe full development and release path is:
1.0.0bump patch \u2192 1.0.1-dev0bump pre_n \u2192 1.0.1-dev1bump pre_l \u2192 1.0.1-rc0bump pre_n \u2192 1.0.1-rc1bump pre_l \u2192 1.0.1bump-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 my changing the serialization configuration.
serialize = [\n \"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}\",\n \"{major}.{minor}.{patch}\",\n]\nThe 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\nThe pre_n path is now missing because it is automated.
The full development and release path now is:
1.0.0bump patch \u2192 1.0.1-dev01.0.1-dev1bump pre_l \u2192 1.0.1-rc01.0.1-rc1bump pre_l \u2192 1.0.1bump-my-version bump pre_l.bump-my-version bump pre_l.There are two modes of operation: On the command line for single-file operation and using a configuration file (pyproject.toml or .bumpversion.toml) for more complex multi-file processes. We recommend using a configuration file for all but the simplest of projects.
Warning
The invocation of bump-my-version changed in version 0.6.0. It splits functionality into sub-commands. It remains backward-compatible with previous versions. Previous usage is discouraged and may be removed in a 1.0 release.
bump-my-version bump [OPTIONS] [ARGS]...\nThe bump sub-command triggers a version increment. The complete list of options is available. The ARGS may contain a VERSION_PART or FILES
VERSION_PART","text":"[optional]
The part of the version to increase, e.g., minor.
Valid values include those given in the --serialize / --parse option.
For example, if the current version is 0.5.1 and you want to bump it to 0.6.0:
bump-my-version bump minor\nFILES","text":"[optional] default: None
The additional file(s) to modify.
This file is added to the list of files specified in the configuration file. If you want to rewrite only files specified on the command line, use --no-configured-files.
For example, if the current version is 1.1.9 and you want to bump the version to 2.0.0 and also change the version in the _version.txt file:
bump-my-version bump major _version.txt\nIf you want to bump the current version of 1.1.9 to 2.0.0\u00a0and only change the _version.txt file:
bump-my-version bump --no-configured-files major _version.txt\nbump-my-version show [OPTIONS] [ARGS]\nThe show subcommand allows you to output the entire or parts of the configuration to the console. The default invocation will output in the default format. The default format changes if one or more than one item is requested. If more than one item is asked for, it outputs the result of Python\u2019s pprint function. If only one thing is asked for, it outputs that value only.
$ bump-my-version show current_version\n1.0.0\n$ bump-my-version show current_version commit\n{'current_version': '1.0.0', 'commit': False}\nYou can use the --increment option to enable a new_version key.
$ bump-my-version show --increment minor current_version new_version\n{'current_version': '1.0.0', 'new_version': '1.1.0'}\nYou can also specify the output to be in JSON or YAML format:
$ bump-my-version show --format yaml current_version\ncurrent_version: \"1.0.0\"\n$ bump-my-version show --format yaml current_version commit\ncurrent_version: \"1.0.0\"\ncommit: false\n$ bump-my-version show --format json current_version\n{\n \"current_version\": \"1.0.0\"\n}\n$ bump-my-version show --format json current_version commit\n{\n \"current_version\": \"1.0.0\",\n \"commit\": false,\n}\nMore complex workflows may require you to change one or more files without changing the current_version in the configuration file.
The replace sub-command works identically to the bump sub-command except for the following:
Note
If you do not include the --new-version option, the new_version context variable will be None.
One way of providing the --new-version option is to use the bump-my-version show subcommand with an environment variable:
$ export BUMPVERSION_NEW_VERSION=$(bump-my-version show new_version --increment <versionpart>)\n$ bump-my-version replace\n