Lightweight version number utility
MIT License
vsntool
- Lean-and-mean version bumping toolThe vsntool
maintains git tags and a text file, VERSION, which
tracks the current software's version number. It provides an easy
method of bumping the major, mnior and patch versions of the software.
The authoritative version of a project is in the VERSION file. vsntool
also
automagically synchronizes this version number in several other auto-detected
files in the repository for various frameworks and languages:
package.json
app.json
version and versionCode attributesconfig.xml
; both version=
and android:versionCode
attributes; plugin.xml
versionsrc/*.app.src
build.gradle
version and versionCodeBy using the vsntool
commands, the version numbers are automatically patched in these files.
Install Elixir, then execute the following in a terminal:
mix escript.install hex vsntool
▶ vsntool
0.1.2-1-g88547df
Running vsntool
without arguments runs git describe --tags
, which
retrieves the last version number, but appended with a unique
identifier which describes the current commit. This is handy in CI
systems and development setups where you often want to build or
release snapshots which contain no official version.
To retrieve the last released version, run:
▶ vsntool last
0.1.2
(which is equivalent to cat VERSION
).
The default branch on which the releases are being tagged is
master
or main
. To change this, change the environment variable
VSN_BRANCH
.
When vsntool is run on a non-release branch, the branch name is added to the version:
▶ git checkout develop
▶ vsntool
0.1.2-1-develop.1-g88547df
vsntool init
initializes a VERSION file in a directory and ensures
it has a git repository:
▶ mkdir ~/new-project; cd ~/new-project
▶ vsntool init
Initialized git repository
Version bump to 0.0.1 OK.
Once a repo has been initialized, you can use the bump_major
,
bump_minor
and bump_patch
commands to increase the version number:
▶ vsntool bump_patch
Version bump to 0.1.2 OK.
Note that vsntool will refuse to tag a commit twice:
▶ vsntool bump_patch
Current commit is already tagged (0.1.2)
To release a new version, do another commit before doing another version bump,
or use the FORCE=true
environment variable to force the version.
Usually after a release you want to set the current project version to a dev
prefix to indicate that this is the current working version. You do this by
specifying --dev
as a flag:
▶ vsntool bump_minor --dev
Version bump to 0.1.0-dev OK.
A
--dev
bump will not create a git tag.
Once you are happy with your project, bump it to a release candidate:
▶ vsntool bump_rc
Version bump to 0.1.0-rc.0 OK.
And create as many release candidates after that as you want:
▶ vsntool bump_rc
Version bump to 0.1.0-rc.1 OK.
To promote an dev
or rc
version to a release, call vsntool release
:
▶ vsntool release
Version bump to 0.1.0 OK.
Tracking your Elixir project's version number is easy; in your
mix.exs
file, you don't hardcode the version number but instead read
it from the VERSION file:
def project do
[
app: :myproject,
version: File.read!("VERSION")
...
This file is evaluated at compile time, so there is no runtime dependency on the existence of the VERSION file.
When releasing your library as dependency, do not forget to add the VERSION file to the list of to-be-packaged files:
defp package do
%{
files: ["lib", "mix.exs", "*.md", "LICENSE", "VERSION"],
...
Build the current project and tag it with the correct version:
▶ docker build . -t organisation/projectname:$(vsntool)
vsntool "knows" about a few common places where version numbers are stored, and will detect these automatically, using a plugin system. The currently supported and shipped plugins are:
package.json
filesapp.json
, both version and versionCodebuild.gradle
, both versionName and versionCodeconfig.xml
, both version and versionCodeplugin.xml
To enable command completion, add the following to your ~/.zshrc
or ~/.bashrc
:
complete -W "init bump_major bump_minor bump_patch last" vsntool
vsntool is an Elixir project, but builds as an escript, a self-contained binary. To build it, you need to have Elixir installed, then run:
▶ make
This produces a fresh version of the vsntool
binary in the root of the repository. Happy versioning!
:os.cmd
)