DashDashVersion creates predictable and opinionated SemVer 2.0.0 version numbers for git flow repositories.
It consists of an executable that can be installed as a dotnet
global tool and a reusable library NET Standard 2.0 that can be used in other applications or .NET based build scripts.
DashDashVersion is an application to generate a version number for a git repository that follows git-flow. Ideal if you are using Continuous Integration. The version number can be used for packages or to simply tag your commits.
DashDashVersion provides automated versioning during development, while leaving control over release versions to the user. It complies with SemVer 2.0. DashDashVersion only supports repositories that strictly follow the git flow conventions, this may seem overly restrictive but we believe strongly in simplicity and convention over configuration.
DashDashVersion can be installed as a dotnet
global tool by using the following command:
$ dotnet tool install --global git-flow-version
or the library part can be added as a package using:
$ dotnet add package DashDashVersion
To use DashDashVersion run the command git-flow-version
inside a git repository.
It will return a JSON string with the following properties:
AssemblyVersion
= anAssemblyVersionAttribute
compatible version with the format<major>.<minor>.<patch>.<revison>
,FullSemVer
= a SemVer 2.0.0 compliant version number with build metadata,SemVer
= a SemVer 2.0.0 compliant version number without build metadata.
For example:
$ git-flow-version
{
"AssemblyVersion":"0.2.0.128",
"FullSemVer":"0.2.0-dev.1+8af6c6d",
"SemVer":"0.2.0-dev.1"
}
If your Continuous Integration (CI) environment uses detached heads git-flow-version
cannot determine what the type (master
, release/*
, feature/
, hotfix/
, support/*
) of the branch is for which it should generate the version number. In these cases the branch name can be specified via a command-line parameter:
$ git-flow-version --branch develop
Matching of the branch name is performed using the following strategy:
- if there is a branch with the exact same name, use that branch, otherwise,
- find all branches that end with the same string as the provided parameter:
- if all of these branches have the same type use that type, otherwise,
- if all of these branches have more than one different type generate an error.
The number of command-line parameters and/or options supported by git-flow-version
is very limited, however below you find them explained in detail:
To show the help information, use any of the following command-line switches:
$ git-flow-version -?
$ git-flow-version -h
$ git-flow-version --help
To use the branch in the repository with the name that matches the supplied value to determine the type of the branch, add either the ‑b
or the ‑‑branch
command-line parameter followed by the name of the branch.
$ git-flow-version -b develop
$ git-flow-version --branch feature/issue-1234-improve-error-handling
To list the version of git‑flow‑version
use either the ‑v
or ‑‑version
command-line switches.
$ git-flow-version -v
$ git-flow-version --version
DashDashVersion only supports repositories that strictly follow the git flow conventions with the branch names:
master
ormain
develop
release/<major>.<minor>.<patch>
feature/<feature name>
bugfix/<bugfix name>
hotfix/<major>.<minor>.<patch>
support/<support branch name>
this may seem overly restrictive but we believe strongly in simplicity and convention over configuration.
- A tag on
master
with a SemVer 2.0.0 compliant name for the latest release, without a pre-release label and without build metadata, if not it will assume 0.0.0 as the current version at the first commit on the repository and count from there. - On any active
release/
orhotfix/
branch add a tag using the<major>.<minor>.<patch>-rc.<number>
format if having consecutiverc
versions is required.
There is nothing to configure 🙌, you have already done the necessary configuration by adhering to git flow 😜.
- Only
release/
,hotfix/
,develop
andfeature/
branches are supported, for other branches a human has to decide on a version number. - Make sure to tag
release/
andhotfix/
branches after generating a version number, the next version number is solely reliant upon that tag. - For unsupported branches if a tag is already present in the correct format, that version number will be returned, to facilitate rebuilds on
master
for example.
The number of commits since the last release version <major>.<minor>.<patch>
is used for the numeric part of the pre-release label. Since the content of develop
will be in the next version of your project, the <minor>
version number will be 1
higher than the <minor>
number of the last release version.
For example if there are 3 commits on develop
and the last tag on master
is 0.0.0
the version number will be 0.1.0-dev.3
.
After performing:
$ git flow release start 0.1.0
$ git flow release finish
the output of git-flow-version
will be:
$ git-flow-version
{
"AssemblyVersion":"0.2.0.128",
"FullSemVer":"0.2.0-dev.1+8af6c6d",
"SemVer":"0.2.0-dev.1"
}
For a feature branch a version number will be calculated for the branch-off point from origin/develop
or develop
if there is no origin/develop
. The number of commits on the feature branch is counted and these pieces are glued together.
For example with a feature named featureA
with 5 commits since branching from origin/develop
with version number 0.1.0-dev.12
the calculated version number would be 0.1.0-dev.12.featureA.5
.
If a second feature is started from the feature/featureA
branch named featureB
the number of commits since branching from origin/develop
will be used, so the version number would be 0.1.0-dev.12-featureB.6
, if only a single commit is made on branch featureB
.
Release candidates use a simple +1
strategy, if the release/0.2.0
branch has just been created and has no commits yet, the version number will be 0.2.0-rc.1
.
If there exists a tag on the release branch that has the form 0.2.0-rc.<a=highest rc number>
the calculated version number will be 0.2.0-rc.<a+1>
.
So if the last tag was 0.2.0-rc.4
the next version number would be 0.2.0-rc.5
.
The version number of the tag on HEAD
will be returned if it can be found and parsed otherwise an error is generated.
If you want to contribute to DashDashVersion you are more than welcome.
Read more about contributing here.
This work is licensed under the LGPL license, refer to the COPYING.md and COPYING.LESSER.md files for details.
The source code of this project can be found on github.