vm 2021.6.1
Updates versions across multiple files.
Install
pip install vm
Usage
You need a versions.yml
, or a versions.json
where you can specify for what
you’re tracking the versions, and what files to be updated using glob patterns:
germanium: # (1)
version: 1.10.3 # (2)
files: # (3)
README.*: "^(germanium )(.*?)$"
setup.py: "version='**VERSION**',"
doc/usage/index.adoc: "^(= Germanium v)(.*?)$"
germanium/version.py: "current = \"**VERSION**\""
-
The name of the variable we want to update
-
The value of the variable (can also use shell commands to be computed)
-
The files, and corresponding expressions we want to use for patching the files
Help:
usage: version-manager [-h] [--display NAME] [--all]
[--set NAME=VAL [NAME=VAL ...]] [--load FILE] [-t]
[--ignore-missing-parents] [--version] [-st TAG]
Versions processor
optional arguments:
-h, --help show this help message and exit
--display NAME, -d NAME
Display the version of a single tracked version.
--all, -a, --list Display all the tracked versions and their values.
--set NAME=VAL [NAME=VAL ...], -s NAME=VAL [NAME=VAL ...]
Set values overriding what's in the yml files.
--load FILE, -l FILE Override versions from the given yml file.
-t, --tag-name, --tag
Get the current name to use in general tags. If the
branch name can't be detected from the git repo, the
$BRANCH_NAME environment variable will be used.
--ignore-missing-parents
Ignore missing parents, and simply don't patch the
values. Upstream values are still being patched if
existing.
--version Show the program version (2021.4.2)
-st TAG, --set-tag TAG
Override the current tag returned by nested calls of
`vm -t`. This works by setting the VERSION_MANAGER_TAG
in the environment of the current process.
Specifying Versions Values
When we’ll patch some value in some file, we need first to obtain the actual value we want to write.
The first most obvious answer is that static values are kept as they are:
description:
version: Awesome code
The version value will be expanded using the shell if it contains a '$' or a '’, so you can have a version such as:
description:
version: Built at $(date) on $(uname -n)
Versions can also refer to other version files, and extract properties from
there, using the parent:
notation in the version:
germaniumdrivers:
version: "parent:../germanium/@germaniumdrivers"
The path will point to the versions.json/yml
file, or to the folder that
contains the versions.json/yml
file, and after that fill will be read and
interpreted the germaniumdrivers
version will be used.
Versions can be also manually overriden from the command line, using the
--set
or -s
flag, for example:
version-manager -s germanium=2.0.8
This will ignore the value specified in the versions.yml file, and use the specified one.
After we obtained that value we wanted to write, we need to patch the files somehow. For this we use experssions.
File Expressions
File expressions are what describes what needs to be patched and where.
They belong as value entries inside the files
mapping. There are
currently only two file expression types (maven is deprecated in favor of
custom expressions in custom settings):
RegExp File
It is a RegExp that has two or three groups, and it will have the second group replaced to the matched version.
For example:
README: "(This installs version )(.+?)( of the product\\.)"
Whatever it’s in group one and three gets kept, and the second group gets replaced with the actual value that got resolved.
VERSION File
This will construct a RegExp that will match exactly the given text, with
the VERSION
being the second group.
So having a matcher such as:
README: "This installs version **VERSION** of the product."
or yaml
README: This installs version **VERSION** of the product.
is equivalent with the following Regex expression:
README: "(This installs version )(.+?)( of the product\\.)"
If the **`s are replaced with `^^
at the beginning, or ` at the end, they
will act as RegExp anchors, equivalent to `^` and `$`. In case in the
expression there is content before the `^^`, or after the `
, the content is
ignored.
Custom Expressions
Another way to specify the expressions is through the custom settings section, where complex RegEx expressions can be externalized:
custom:
pip: pip_library\(\s*name\s*=\s*"$1"\s*,\s*version\s*=\s*"$value"\s*,?\s*\)
---
pyyaml:
version: 3.0
files:
build/thirdparty/python/BUILD: pip:PyYAML
build/thirdparty/gepython/BUILD: pip:PyYAML
The value for matching are expected to have multiple :
separated values, and
can be referred in the regex as {var1}
, {var2}
etc. The actual values for
var*
variables will be regex escaped, so they’ll match as they are.
maven Expressions (deprecated)
Maven expressions tries to match using GAV identifiers. These will construct a RegExp that will match:
"(<groupId>group_id</groupId>\\s*"
"<artifactId>artifact_id</artifactId>\\s*"
"<version>)(.*?)(</version>)"
In order to specify the matcher, just use the maven:
prefix:
pom.xml: "maven:com.germaniumhq:germanium"
Matcher Constraints
In order to make sure that the expressions are not replacing in too many places, constraints can be added to limit, or extend the matches.
Matcher constraints are always active, and in case no constraint is specified then the maximum replacement count is set to 1.
Match Count
{
"product" : {
"version": "1.0",
"files": {
"README.md": {
"match": "^(= Germanium v)(.*?)$",
"count": 2
}
}
}
}
or yaml
product:
version: "1.0"
files:
README.md:
match: ^(= Germanium v)(.*?)$
count: 2
The count can be also 0
for no matches, or negative to indicate
any number of matches is allowed.
Multiple Matchers
In a single file, we can have multiple matchers as well, for example:
{
"product" : {
"version": "1.0",
"files": {
"README.md": [
"^(= Germanium v)(.*?)$",
"(Germanium )(\\d+\\.\\d+)()"
]
}
}
}
For each matcher that is added, if there is no match count specified, it’s assumed that it will only match once in the file.
Of course, constraints can be applied for both the full set of matchers:
{
"product" : {
"version": "1.0",
"files": {
"README.md": {
"match": [
"^(= Germanium v)(.*?)$",
"(Germanium )(\\d+\\.\\d+)()"
],
"count": 3
}
}
}
}
or even individual expressions:
{
"product" : {
"version": "1.0",
"files": {
"README.md": {
"match": [
"^(= Germanium v)(.*?)$",
{
"match": "(Germanium )(\\d+\\.\\d+)()",
"count": 2
}
],
"count": 3
}
}
}
}
Notes
-
Files are actually
glob
patterns, so you can match*/.js
for example. -
The configuration files can be yml.
-
vm
will output the following error codes: 0 when no files are changed, 0 when files are changed successfuly, or a non zero error code in case of error.