🏷 Minimalistic versioning using Git tags.
The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:
A minimalistic .NET package for versioning .NET SDK-style projects using Git tags.
Platform support: all platforms supported by .NET SDK-style projects.
Also available as a command line tool for use in any Git repository.
Your project will be versioned according to the latest tag found in the commit history.
To build with GitHub Actions, set the fetch depth appropriately.
When you want to release a version of your software, whether it's a pre-release, RTM, patch, or anything else, simply create a tag with a name which is a valid SemVer 2.x version and build your projects. MinVer will apply the version to the assemblies and packages. (If you like to prefix your tag names, see the FAQ.)
NOTE: The MinVer package reference should normally include
PrivateAssets="All". See NuGet docs for more info. If you install MinVer using an IDE or tool, this should be done for you automatically.
1.0.0, the current version is
0.0.0-alpha.0is used, with height added.
If the current commit does not have a version tag, another number is added to the pre-release identifiers. This is the number of commits since the latest commit with a version tag or, if no commits have a version tag, since the root commit. This is known as "height". For example, if the latest version tag found is
1.0.0-beta.1, at a height of 42 commits, the calculated version is
MinVer sets the following custom properties:
Those properties are used to set the following .NET SDK properties, satisfying the official open-source library guidance for version numbers:
| Property | Value | |-------------------|-----------------------------------------------| |
This behaviour can be customised.
Options can be specified as either MSBuild properties or environment variables.
Note that the option names are case-insensitive.
(With TL;DR answers inline.)
The TL;DR is that MinVer is simpler. "How it works" pretty much captures everything.
To some degree, MinVer is a subset of what GitVersion is. It's much simpler and doesn't do nearly as much. Some of the differences:
MinVer is a different approach and, again, simpler. Some of the differences are already listed under the comparison with GitVersion above.
Essentially, Nerdbank.GitVersioning encapsulates the injection of the version into the build process from a config file. That means versions are controlled by commits to that config file. MinVer works purely on tags. That means MinVer doesn't need some of the types of things that come with Nerdbank.GitVersioning such as the config file bootstrapper, and it means the version is controlled independently of the commits. For example, you can tag a commit as a release candidate, build it, and release it. After some time, if the release candidate has no bugs, you can tag the same commit as RTM, build it, and release it.
Also, Nerdbank.GitVersioning uses the git height for the patch version, which is undesirable. Either every patch commit has to be released, or there will be gaps in the patch versions released.
Yes! You probably want to do this because at a point in time, on a given branch, you are working on a specific
2.0. The branch could be
develop, a special release branch, a support branch, or anything else.
Before you create the first version tag on your branch, interim builds will use the latest version tag found in the commit history, which may not match the
MAJOR.MINORrange you are working on. Or if no version tag is found in the commit history, interim builds will have the default version
0.0.0-alpha.0. If you prefer those interim builds to have a version in the range you are working on, you have two options:
Tag a commit in your branch with a version matching your
MAJOR.MINORrange, using your preferred default pre-release phase and a pre-release ordinal of 0. For example:
git tag 1.0.0-alpha.0
This is not a version you will release, since the first "alpha" version will be
1.0.0-alpha.1. The only purpose of this tag is to force MinVer to start versioning commits in your branch in the
If you begin to release versions in the
1.0range from another branch (e.g. a special release branch), tag a commit in your branch with
2.0.0-alpha.0, or whatever
MAJOR.MINORrange your branch now represents.
MinVer will now use a default version of
If you begin to release versions in the
1.0range from another branch (e.g. a special release branch), set MinVerMinimumMajorMinor to
2.0, or whatever
MAJOR.MINORrange your branch now represents.
MinVerMinimumMajorMinorwill be redundant after you create the first tag in your branch with same
MAJOR.MINOR. If you don't care that the versions of interim builds before that first tag will have a lower
MAJOR.MINOR, then simply don't specify
Also note that if the latest version tag found in the commit history has a higher
MinVerMinimumMajorMinorwill be ignored.
Yes! MinVer doesn't care what your pre-release versioning scheme is. The default pre-release identifiers are
alpha.0, but you can use whatever you like in your tags. If your versioning scheme is valid SemVer 2.x, it will work with MinVer.
For example, all these versions work with MinVer:
For example, if you prefix your tag names with "v", e.g.
Yes! MinVer doesn't care about branches. It's all about the tags!
Yes! Specify build metadata with
environment: MINVERBUILDMETADATA: build.%APPVEYOR_BUILD_NUMBER%
You can also specify build metadata in a version tag. If the tag is on the current commit, its build metadata will be used. If the tag is on an older commit, its build metadata will be ignored. Build metadata in
MinVerBuildMetadatawill be appended to build metadata in the tag.
Yes! Specify which part of the version to auto-increment with
MinVerAutoIncrement. By default, MinVer will auto-increment the patch version, but you can specify
majorto increment the minor or major version instead.
Yes! Specify the default pre-release phase with
MinVerDefaultPreReleasePhase. For example, if you prefer to name your pre-releases as "preview":
This will result in a post-RTM version of
Yes! You can use any of the properties set by MinVer, or override their values, in a target which runs after MinVer.
For example, for pull requests, you may want to inject the pull request number and a variable which uniquely identifies the build into the version. E.g. using Appveyor:
$(MinVerMajor).$(MinVerMinor).$(MinVerPatch)-pr.$(APPVEYOR_PULL_REQUEST_NUMBER).build-id.$(APPVEYOR_BUILD_ID).$(MinVerPreRelease) $(PackageVersion)+$(MinVerBuildMetadata) $(PackageVersion)
Or for projects which do not create NuGet packages, you may want to populate all four parts of
AssemblyVersion. E.g. using Appveyor:
Or for projects which do create NuGet packages, you may want to adjust the assembly file version to include the build number, as recommended in the official guidance. E.g. when using Appveyor:
Yes! You can do this by using a specific tag prefix for each project. For example, if you have a "main" project and an "extension" project, you could specify
main-in the main project and
ext-in the extension project. To release version
1.0.0of the main project you'd tag the repo with
main-1.0.0. To release version
1.1.0of the extension project you'd tag the repo with
diagnostic. These verbosity levels match those in MSBuild and therefore
dotnet pack, etc. The default is
minimal, which matches the default in MSBuild. At the
minimallevels, you will see only warnings and errors. At the
normallevel you will see which commit is being used to calculate the version, and the calculated version. At the
detailedlevel you will see how many commits were examined, which version tags were found but ignored, which version was calculated, etc. At the
diagnosticlevel you will see how MinVer walks the commit history, in excruciating detail.
In a future version of MinVer, the verbosity level may be inherited from MSBuild, in which case
MinVerVerbositywill be deprecated.
Yes! MinVer is also available as a command line tool. Run
minver --helpfor usage. The calculated version is printed to standard output (stdout).
Sometimes you may want to version both .NET projects and other outputs, such as non-.NET projects, or a container image, in the same build. In those scenarios, you should use both the command line tool and the regular MinVer package. Before building any .NET projects, your build script should run the command line tool and set the
true. For example, MinVer can be disabled for debug builds:
MinVer will use the tag with the higher version, or the tag or root commit on the first path followed where the history diverges. The paths are followed in the same order that the parents of the commit are stored in git. The first parent is the commit on the branch that was the current branch when the merge was performed. The remaining parents are stored in the order that their branches were specified in the merge command.
MinVer will use the height on the first path followed where the history diverges. The paths are followed in the same order that the parents of the commit are stored in git. The first parent is the commit on the branch that was the current branch when the merge was performed. The remaining parents are stored in the order that their branches were specified in the merge command.
By default, GitHub Actions and Travis CI use shallow clones. The GitHub Actions checkout action clones with a depth of only a single commit, and Travis CI clones with a depth of 50 commits. In GitHub Actions, if the latest version tag in the history is not on the current commit, it will not be found. In Travis CI, if the latest version tag in the history is at a height of more than 50 commits, it will not be found.
To build in GitHub Actions or Travis CI, configure them to fetch a sufficient number of commits.
For GitHub Actions, set the
fetch-depthof the checkout action to an appropriate number, or to zero for all commits. For example:
- uses: actions/[email protected] with: fetch-depth: 0flag to an appropriate number, or to
falsefor all commits:
git: depth: false