dotnet tool install --global TurnerSoftware.BuildVersioning.Tool --version 0.4.0
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local TurnerSoftware.BuildVersioning.Tool --version 0.4.0
nuke :add-package TurnerSoftware.BuildVersioning.Tool --version 0.4.0
Simple build versioning for .NET, powered by Git tags.
Inspired by MinVer, Build Versioning is a different attempt at the same problem - to make versioning simple. The simplicity comes from how the version strings are generated and the built-in integrations.
🤝 Licensing and Support
Build Versioning is licensed under the MIT license. It is free to use in personal and commercial projects.
There are support plans available that cover all active Turner Software OSS projects. Support plans provide private email support, expert usage advice for our projects, priority bug fixes and more. These support plans help fund our OSS commitments to provide better software for everyone.
📖 Table of Contents
- Getting Started
- CI Versioning Integrations
- Customizing Version Strings
- Additional Settings
<a id="requirements" /> 📋 Requirements
- Your project must be using a modern SDK-style project file
- One of the following .NET runtimes must be installed:
- .NET 5
- .NET 6
The runtime requirement is so that Build Versioning itself can run. Your project though can target whatever version of .NET you want (Framework/Standard/Core etc).
<a id="getting-started" /> ⭐ Getting Started
PM> Install-Package TurnerSoftware.BuildVersioning
- There is no second step - you're done!
The version information is extracted from the current state of the Git repository. From a tag that is SemVer v2.0 compliant, it can extract the major, minor, patch, pre-release and build metadata information. This information is then fed through a formatting system to generate specific version strings.
Additional information is provided from Git directly including the commit height (number of commits since the last tag) and the commit hash itself.
These examples use the default configuration after installing Build Versioning.
|Example||Git Tag||Commit Height||Full Version||File Version||Assembly Version|
|Main Branch / Active Development||1.2.4||4||1.2.4-dev.4+a4f31ea||184.108.40.206||220.127.116.11|
|Non-PR Commit via GitHub Actions||1.2.4||4||1.2.4-dev.4+a4f31ea-github.432515||18.104.22.168||22.214.171.124|
|PR Commit via GitHub Actions||1.2.4||4||1.2.4-pr.17+a4f31ea-github.432515||126.96.36.199||188.8.131.52|
<a id="integrations" /> 🛠 CI Versioning Integrations
By default, Build Versioning provides rich pre-release and build metadata from the current CI environment.
For pull requests, this will automatically have a pre-release defined which will include the PR number (eg.
For all commits, the build metadata will include the CI environment and a relevant build identifier (eg.
||Will perform a
||Will update the AppVeyor build name to match the build version. This specific behaviour can be disabled by setting
Disabling an Integration
Each integration can be individually disabled through configuration. For example, include the following in your project file to disable the GitHub Actions integration:
<a id="customizing-version-strings" /> ✏ Customizing Version Strings
These are formatting tags available for you to use for customizing your version strings.
||The major version retrieved from the Git tag. If there are no tags available, defaults to
||The major version retrieved from the Git tag incremented by 1. If this is a tagged release, the value will return the major version without increment.|
||The minor version retrieved from the Git tag. If there are no tags available, defaults to
||The minor version retrieved from the Git tag incremented by 1. If this is a tagged release, the value will return the minor version without increment.|
||The patch version retrieved from the Git tag. If there are no tags available, defaults to
||The patch version retrieved from the Git tag incremented by 1. If this is a tagged release, the value will return the patch version without increment.|
||The number of commits since the last tag. If there are no tags available, defaults to
||The first 7 characters of the most recent commit hash.|
Additionally, the full version string supports two additional formatting tags.
|Tag||Default Value||Configuration Tag||Description|
||The pre-release portion of the version. This will include the leading dash (
||The build metadata portion of the version. This will include the leading plus (
|Name||Configuration Tag||Default Value|
|📦 Full Version<br>aka. the "package" or "product" version, it is used for versioning the package itself and displayed in NuGet.||
|📄 File Version<br>A superficial version number, displayed by the OS. This is not used by the .NET runtime.||
|⚙ Assembly Version<br>Used by .NET for referencing the assembly when strong-named signing is enabled. Updating this by major version is advised.||
For more information on file version vs assembly version, see the MSDN docs.
<a id="additional-settings" /> 🎛 Additonal Settings
Disabling Build Versioning
You can disable build versioning by setting
<SkipBuildVersioning> in your project file to
Enable Output Logging
You can enable output logging for Build Versioning by specifying
normal (for basic logging) or
high (for detailed logging).
|.NET||net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows|
This package has no dependencies.