Update the patch part of the version in file VERSION. The current version is specified explicitly
on the command line.
VERSION:
1.2.0
The following command line bumpversion patch --current-version 1.2.0 VERSION update the version inside the file:
VERSION:
1.2.1
Update the patch part of the version in file VERSION. The current and new version are specified explicitly
in a configuration file.
VERSION:
1.2.0
mybumpconfig.cfg:
[bumpversion] current_version: 1.2.0 files: VERSION
bumpversion patch --config-file mybumpconfig.cfg
VERSION:
1.2.1
files is deprecated. It is better to use [bumpversion:file:...] sections instead.
mybumpconfig.cfg:
[bumpversion] current_version: 1.2.0 [bumpversion:file:VERSION]
If not specified on the command line, ADVbumpversion will use the configuration file .bumpversion.cfg in the
current directory.
.bumpversion.cfg:
[bumpversion] current_version: 1.2.0 [bumpversion:file:VERSION]
bumpversion patch
The default configuration format is major.minor.patch and is parsed with the regular expression
(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+). You can specify your own format with parse and serialize.
For example, you may want to append a build part to the version as in 2.1.0-5123.
.bumpconfig.cfg:
[bumpversion]
current_version: 2.1.0-5123
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\-(?P<build>\d+)
serialize = {major}.{minor}.{patch}-{build}
[bumpversion:file:VERSION]
The following command:
bumpversion build
produces the version: 2.1.0-5124. The command:
bumpversion major
produces the version: 3.0.0-0.
In the previous example, the build part is reset like the other parts because the major part was incremented.
This is sometimes not what you want. You may want to keep this part independent of the other parts. To do so,
configure explicitly this part:
.bumpconfig.cfg:
[bumpversion]
current_version: 2.1.0-5123
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\-(?P<build>\d+)
serialize = {major}.{minor}.{patch}-{build}
[bumpversion:file:VERSION]
[bumpversion:part:build]
independent = True
In this case, the command:
bumpversion major
produces the version: 3.0.0-5123 with the build part untouched.
By default, version parts are numerical but you can customize them and give a list of textual values.
VERSION.txt:
2.1.0-alpha
.bumpconfig.cfg:
[bumpversion]
current_version: 2.1.0-alpha
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\-(?P<release>[a-z]+)
serialize = {major}.{minor}.{patch}-{release}
[bumpversion:file:VERSION.txt]
[bumpversion:part:release]
values =
alpha
beta
gamma
The command bumpversion release produces the version 2.1.0-beta.
In the previous example, the release part is mandatory. You can make it optional.
VERSION.txt:
2.1.0-alpha
.bumpconfig.cfg:
[bumpversion]
current_version: 2.1.0-alpha
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+))?
serialize =
{major}.{minor}.{patch}-{release}
{major}.{minor}.{patch}
[bumpversion:file:VERSION.txt]
[bumpversion:part:release]
optional_value = gamma
values =
alpha
beta
gamma
parse has been adapted to make the parsing of release optional (with (...)?, serialize has now two
possible values: {major}.{minor}.{patch}-{release} or {major}.{minor}.{patch}, and gamma is explicitly
marked as optional for the release par.
The command bumpversion release produces the version 2.1.0-beta. A second bumpversion release produces the
version 2.1.0.
PEP 440 describes a scheme for identifying versions of Python software distributions, and declaring dependencies on particular versions.
Canonical public version identifiers must comply with the following scheme:
[N!]N(.N)*[{a|b|rc}N][.postN][.devN]
The scheme is very generic and includes elements that are not often used (like the epoch eleement at the beginning). A less compless (and compliant) format is the following:
N.N[{a|b|rc}N][.postN][.devN]
Examples of versions:
1.0 1.0a1 # 1.0 alpha 1 1.0b2 # 1.0 beta 2 1.0b2.dev1 # Development release 1 of version 1.0 beta 2 1.0.post1 # Post-release 1 of version 1.0 (i.e. minor correction) 1.0.post1.dev2 # Development release 2 of post-release 1 of version 1.0 5.9rc3.dev1 # Development release 1 of Release candidate 3 of version 5.9
To use this scheme, you can define the following configuration:
[bumpversion]
current_version = 1.0a1
parse =
(?P<major>\d+)\.(?P<minor>\d+) # major and minor
(?:(?P<pre>(?:[ab]|rc))(?P<prenum>\d+))? # 'a' = alpha, 'b' = beta, 'rc' = release candidate
(?:\.post(?P<post>\d+))? # post-release
(?:\.dev(?P<dev>\d+))? # development
serialize =
{major}.{minor}{pre}{prenum}.post{post}.dev{dev}
{major}.{minor}.post{post}.dev{dev}
{major}.{minor}{pre}{prenum}.post{post}
{major}.{minor}.post{post}
{major}.{minor}{pre}{prenum}.dev{dev}
{major}.{minor}.dev{dev}
{major}.{minor}{pre}{prenum}
{major}.{minor}
[bumpversion:part:pre]
optional_value = stable
values =
a
b
rc
stable
[bumpversion:part:prenum]
first_value = 1
[bumpversion:file:VERSION.txt]
The following commands bump successively the version:
| Command | Version |
|---|---|
bumpversion prenum |
1.0a2 |
bumpversion pre |
1.0b1 |
bumpversion pre |
1.0rc1 |
bumpversion pre |
1.0 |
bumpversion post |
1.0.post1 |
bumpversion dev |
1.0.post1.dev1 |
bumpversion minor |
1.1a1 |
bumpversion dev |
1.1a1.dev1 |
bumpversion pre |
1.1b1 |
bumpversion pre |
1.1rc1 |
bumpversion pre |
1.1 |
bumpversion dev |
1.1.dev1 |
Semantic Versioning (SemVer) is a simple set of rules and requirements that dictate how version numbers are assigned and incremented. SemVer versions have the following format:
X.Y.Z[-{a-zA-Z-}+(.{a-zA-Z-})*][+{a-zA-Z-}+(.{a-zA-Z-})*]
Note: this is a simplified expression.
Examples of SemVer versions:
1.0.0 1.0.0-alpha.1 # 1.0.0 alpha 1 1.0.0-beta.2 # 1.0.0 beta 2 1.0.0-dev.1 # Development release 1 of version 1.0.0 1.0.1 # Patch 1 of version 1.0.0 1.0.0-post.1.dev.2 # Development release 2 of post-release 1 of version 1.0.0 1.0.0-beta.2+5664 # 1.0.0 beta 2 build number 5664
The following configuration file can be used to implement SemVer (again, simplified):
[bumpversion]
current_version = 1.0.0
parse =
(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+) # major, minor and patch
(?:\-(?P<pre>(?:dev|alpha|beta|rc))\.(?P<prenum>\d+))? # pre-release
(?:\+(?P<build>\d+))? # build metadata
serialize =
{major}.{minor}.{patch}-{pre}.{prenum}+{build}
{major}.{minor}.{patch}-{pre}.{prenum}
{major}.{minor}.{patch}+{build}
{major}.{minor}.{patch}
[bumpversion:part:pre]
optional_value = stable
values =
dev
alpha
beta
rc
stable
[bumpversion:part:prenum]
first_value = 1
[bumpversion:part:build]
independent = True
[bumpversion:file:VERSION.txt]
Note: This configuration defines 5 values for pre-release part and assumes that the build part is numerical.
SemVer permits more complex parts such as x.7.z.92-beta.1.2+exp.sha.5114f85.
The following commands bump successively the version:
| Command | Version |
|---|---|
bumpversion prenum |
1.0.1-dev1.1 |
bumpversion pre |
1.0.1-alpha.1 |
bumpversion pre |
1.0.1-beta.1 |
bumpversion pre |
1.0.1-rc.1 |
bumpversion premnum |
1.0.1-rc.2 |
bumpversion pre |
1.0.1 |
bumpversion build |
1.0.1+1 |
bumpversion build |
1.0.1+2 |
bumpversion build --new-version 1.0.1+5134 |
1.0.1-rc+5134 |
bumpversion patch |
1.0.2-dev.1+5134 |
bumpversion pre |
1.0.2-alpha.1+5134 |
bumpversion pre |
1.0.2-beta.1+5134 |
bumpversion pre |
1.0.2-rc.1+5134 |
bumpversion pre |
1.0.2+5134 |
In the previous examples, versions are identified by their values. It is versatile but it may confound texts with
version numbers. With search and replace, you can be more specific. For example:
[bumpversion]
current_version: 1.2.0
[bumpversion:file:VERSION]
search = VERSION = {current_version}
replace = VERSION = {new_version}
Search and replace values can have multiple lines. It can be useful for CHANGELOG files:
[bumpversion]
current_version: 1.2.0
[bumpversion:file:CHANGELOG.rst]
search =
Unreleased
----------
replace =
Unreleased
----------
Version v{new_version} ({now:%Y-%m-%d})
---------------------------
`erialize, search and replace can use values from the current context. This context contains the different
parts of the version (as parsed by parse regular expression), environment variables (with a $ before their
names) and two time values: now (that corresponds to datetime.now()) and utcnow (that corresponds to
datetime.utcnow()).
For example, if the environ variable USER is defined, it can be part of the version number:
[bumpversion]
current_version: 1.2.0
[bumpversion:file:VERSION.txt]
serialize =
{major}.{minor}.{patch}+{$USER}
now and utcnow can be used to change the build date with the version number. For example, if you have the
following configuration file:
.bumpconfig.cfg:
[bumpversion]
current_version = 2.1.0 2017-12-04
serialize = {major}.{minor}.{patch} {now:%Y-%m-%d}
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)\s(?P<date>\d{4}-\d{2}-\d{2})
[bumpversion:file:VERSION.h:0]
serialize = {major}.{minor}.{patch}
[bumpversion:file:VERSION.h:1]
serialize = {date}
The following file:
VERSION.h:
#define BUILD_VERSION 2.1.0 #define BUILD_DATE 2017-12-04 12:00 #define BUILD_DESCRIPTION 2.1.0 (2017-12-04 12:00)
is transformed into:
#define BUILD_VERSION 2.2.0 #define BUILD_DATE 2018-02-09 12:00 #define BUILD_DESCRIPTION 2.2.0 (2018-02-09 12:00)
by the command: bumpversion minor.
ADVbumpversion is able to interact with source controls such as Git and Mercurial. It can create automatically tags and commits. The name of the tags and the message of the commits are configurable. it is also possible to sign tags.
The following command:
bumèversion patch --current-version 47.1.1 --commit VERSION
creates a commit with the message Bump version: 47.1.1 -> 47.1.2.
The following configuration:
[bumpversion] current_version = 47.1.1 commit = True tag = True [bumpversion:file:VERSION]
and the command:
bumpversion patch
creates a commit with the message Bump version: 48.1.1 -> 48.1.2 and a tag named v48.1.2.
Tag name can be customized with tag_name:
[bumpversion]
current_version = 47.1.1
commit = True
tag = True
tag_name: from-{current_version}-to-{new_version}
[bumpversion:file:VERSION]
The tag will be named from-47.1.1-to-47.1.2.
Annotated tags are created with --tag-message in commands such as:
bumpversion patch --current-version 42.5.1 --commit --tag --tag-message 'test {new_version}-tag' VERSION
In a similar way, it is possible to sign tags:
[bumpversion]
current_version = 47.1.1
commit = True
tag = True
tag_name: from-{current_version}-to-{new_version}
sign_tags = True
[bumpversion:file:VERSION]
In a similar way, it is possible to csutomize commit messages:
bumpversion --message '[{now:%Y-%m-%d}] Jenkins Build {$BUILD_NUMBER}: {new_version}' patch