Bump semver for git repos with a single command.
Project description
bumpsemver
Current version: 1.0.4
A utility to simplify the version bumping for git repos.
This application is a rework of the famous bumpversion
tool. The
original repo seems like abandoned. Several fundamental changes are
introduced, which make the fork-and-extend approach infeasible:
- dropped Python 2 support
- boosted the test coverage to 95%+
- dropped many irrelevant features to reduce complexity. (e.g. customized version component support)
- introduced JSON support to make it work for package-lock.json, YAML support to make it work for Ansible plays
- narrowed the versioning scheme to semver-only
Installation
pip3 install bumpsemver
Usage
This application supports both the CLI mode and config file mode.
Command Line Interface
bumpsemver [options] part [file]
options
(optional)
Most of the configuration values described below can also be given as an option on the command-line. Additionally, the following options are available:
--dry-run
Don't touch any files, just pretend. Best used with --verbose
.
--allow-dirty
Normally, bumpsemver will abort if the working directory is dirty to protect
yourself from releasing unversioned files and/or overwriting unsaved changes.
Use this option to override this check.
--verbose
Print useful information to stderr
-h, --help
Print help and exit
part
required
The part of the version to increase. As we support semver only, the valid values include: major
, minor
, and patch
.
For example, bumping file src/VERSION
from 0.5.1 to 0.6.0:
bumpsemver --current-version 0.5.1 minor src/VERSION
file
(optional)
default: none
The file that will be modified.
If not given, the list of [bumpsemver:file:…]
sections from the configuration file will be used. If no files are
mentioned on the configuration file either, then no files will be modified.
For example, bumping file setup.py
from 1.1.9 to 2.0.0:
bumpsemver --current-version 1.1.9 major setup.py
Configuration file
Options on the command line take precedence over those from the config file, which take precedence over those from the defaults.
Example .bumpsemver.cfg
:
[bumpsemver]
current_version = 0.2.9
commit = True
tag = True
[bumpsemver:file:README]
.bumpsemver.cfg
-- Global configuration
General configuration is grouped in a [bumpsemver]
section.
current_version
required
default: none
The current version of the software package before bumping.
Also available as CLI argument --current-version
(e.g. bumpsemver --current-version 0.5.1 patch
)
tag = (True | False)
(optional)
default: False (Don't create a git tag)
Whether to create a git tag, that is the new version, prefixed with the character "r
". Don't forget to git-push
with the --tags
flag.
Also available as CLI argument --tag
or --no-tag
.
sign_tags = (True | False)
(optional)
default: False (Don't sign tags)
Whether to sign tags.
Also available as CLI argument --sign-tags
or --no-sign-tags
.
tag_name =
(optional)
default: v{new_version}
The name of the tag that will be created. Only valid when tag = True
.
It can be a template using the Python Format String Syntax.
Available in the template context are current_version
and new_version
as well as current_[part]
and new_[part]
(e.g. 'current_major
' or 'new_patch
'). You can also use the variables now
or utcnow
to get a current timestamp.
Both accept datetime formatting (when used like as in {now:%d.%m.%Y}
).
Also available as CLI argument --tag-name
, for example: bumpsemver --tag-name 'release-{new_version}' patch
In addition, it is also possible to provide a tag message by using CLI --tag-message TAG_MESSAGE
. Example usage:
bumpsemver --tag-name 'release-{new_version}' --tag-message "Release {new_version}" patch
If neither tag message or sign tag is provided, we use a lightweight
tag in git. Otherwise, we utilize an annotated
git tag. Read more about Git tagging here.
commit = (True | False)
(optional)
default: False (Don't create a commit)
Create a commit using git when true.
Also available as CLI argument --commit
or --no-commit
.
message =
(optional)
default: [OPS] bumped version: {current_version} → {new_version}
The commit message to use when creating a commit. Only valid when using --commit
/ commit = True
.
It can be a template using the Python Format String Syntax.
Available in the template context are current_version
and new_version
as well as current_[part]
and new_[part]
(e.g. 'current_major
' or 'new_patch
'). You can also use the variables now
or utcnow
to get a current timestamp.
Both accept datetime formatting (when used like as in {now:%d.%m.%Y}
).
Also available as CLI argument --message
, for example: bumpsemver --tag-name 'release-{new_version}' patch
In addition, it is also possible to provide a tag message by using CLI --tag-message TAG_MESSAGE
. Example usage:
bumpsemver --message '[{now:%Y-%m-%d}] Jenkins Build {$BUILD_NUMBER}: {new_version}' patch
.bumpsemver.cfg
-- File specific configuration
This configuration is in the section: [bumpsemver:file:…]
or [bumpsemver:json:…]
Note: The configuration file format requires each section header to be unique. If you want to process a certain file
multiple times (e.g. multiple location to be replaced separately), you may append a description between parens to the
file
keyword: [bumpsemver:file (special one):…]
. It does not matter what inside the parens, just make it unique.
e.g.
[bumpsemver:file(1):README.md]
search = current version: {current_version}
replace = current version: {new_version}
[bumpsemver:file(2):README.md]
search = **Version: {current_version}**
replace = current version: {new_version}
search =
default: {current_version}
Template string how to search for the string to be replaced in the file. Useful if the remotest possibility exists that the current version number might be present multiple times in the file and you mean to only bump one of the occurrences.
replace =
default: {new_version}
Template to create the string that will replace the current version number in the file.
Given this requirements.txt
:
Django>=1.5.6,<1.6
MyProject==1.5.6
using the following .bumpsemver.cfg
will ensure only the line containing MyProject
will be changed:
[bumpsemver]
current_version = 1.5.6
[bumpsemver:file:requirements.txt]
search = MyProject=={current_version}
replace = MyProject=={new_version}
With [bumpsemver:file:…]
, the specified file is processed as plain text file, which in fact makes this application
programming language neutral. However, it will be very error prone for complex file for example package-lock.json
.
For randomly sampled 30 projects written in node.js/TypeScript, the classical bumpversion
or the renovated bump2version
both made
100% mistakes which changed something shouldn't be changed. A typical and relatively complex React projects contains 1000+ npm packages
indirectly. There are too many "version": "1.2.3" in that file. To address this issue, bumpsemver
added the support of json file.
To use it:
[bumpsemver:json:package-lock.json]
jsonpath = version
Value of the parameter jsonpath
is a JSONPath string. For the typical
package.json
or package-lock.json
, using version
or its jQuery-style alternative $.version
is sufficient.
Otherwise, anything can be selected with JSONPath is support, so, nothing we can't do. The underlying JSONPath processor
is jsonpath-ng. Checkout their document for some examples and hints.
The suffix is also supported for json file:
[bumpsemver:json(1):example.json]
jsonpath = version
[bumpsemver:json( same file):example.json]
jsonpath = dependencies[2].*.version
[bumpsemver:json (once again):example.json]
jsonpath = dependencies[0].*.lodash.dependencies[1].version
Comparably, YAML is supported for the same reason that we should support native JSON, like
[bumpsemver:yaml:playbook.yml]
yamlpath = version
OR
[bumpsemver:yaml(1):playbook.yml]
yamlpath = *.vars.project_version
[bumpsemver:yaml( same file):playbook.yaml]
yamlpath = *.vars.version
[bumpsemver:yaml (once again):playbook.yaml]
yamlpath = *.vars.app_version
Please note that we use yamlpath instead of
jsonpath
here. yamlpath
is not a popular "standard" widely adopted. For complex scenarios, it makes sense to test the expression with
yamlpath cli before putting anything in the config file.
Test
Test in Docker container (recommended):
make test
Local test in the working environment (not recommended):
tox
To test the compatibility with a specific version of Python, put the version(s) into ./python-versions.txt
one version
per line. Then run:
make test
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for bumpsemver-1.0.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 02c4a78de3485594482eee53a69973319be69afe02e7c87b4fbfda97f1613905 |
|
MD5 | 3a5bf896c1ef1ba0410dbd03a057c1f4 |
|
BLAKE2b-256 | da2c121b748f4848cfe8a81ee24a9349d5569193258de06e021c3c69700bea08 |