Home

Awesome

<div align="center">

Icon

Build Versioning

Simple build versioning for .NET, powered by Git tags.

Build Codecov NuGet

</div>

Overview

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

<a id="requirements" /> 📋 Requirements

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

  1. Install Build Versioning<br>
PM> Install-Package TurnerSoftware.BuildVersioning
  1. 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.

Example Versions

These examples use the default configuration after installing Build Versioning.

ExampleGit TagCommit HeightFull VersionFile VersionAssembly Version
New Release1.2.401.2.4+a4f31ea1.2.4.01.0.0.0
New Pre-Release1.2.4-alpha01.2.4-alpha+a4f31ea1.2.4.01.0.0.0
Main Branch / Active Development1.2.441.2.4-dev.4+a4f31ea1.2.4.01.0.0.0
Non-PR Commit via GitHub Actions1.2.441.2.4-dev.4+a4f31ea-github.4325151.2.4.01.0.0.0
PR Commit via GitHub Actions1.2.441.2.4-pr.17+a4f31ea-github.4325151.2.4.01.0.0.0

<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. 1.2.4-pr.17). For all commits, the build metadata will include the CI environment and a relevant build identifier (eg. 1.2.4+a4f31ea-github.432515).

Default Integrations

IntegrationConfiguration TagNotes
GitHub Actions<BuildVersioningWithGitHub>Will perform a git fetch for tags that are missing by default for GitHub Actions. This specific behaviour can be disabled by setting <GitHubAutoFetchTags> to false.
Azure DevOps<BuildVersioningWithAzureDevOps>
AppVeyor<BuildVersioningWithAppVeyor>Will update the AppVeyor build name to match the build version. This specific behaviour can be disabled by setting <AppVeyorAutoBuildNaming> to false.

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:

<BuildVersioningWithGitHub>false</BuildVersioningWithGitHub>

<a id="customizing-version-strings" /> ✏ Customizing Version Strings

Formatting Tags

These are formatting tags available for you to use for customizing your version strings.

TagNotes
{Major}The major version retrieved from the Git tag. If there are no tags available, defaults to 0.
{Major++}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.
{Minor}The minor version retrieved from the Git tag. If there are no tags available, defaults to 0.
{Minor++}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.
{Patch}The patch version retrieved from the Git tag. If there are no tags available, defaults to 0.
{Patch++}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.
{CommitHeight}The number of commits since the last tag. If there are no tags available, defaults to 0.
{CommitHash}The first 7 characters of the most recent commit hash.

Additionally, the full version string supports two additional formatting tags.

TagDefault ValueConfiguration TagDescription
{PreRelease}dev.{CommitHeight}<BuildPreReleaseFormat>The pre-release portion of the version. This will include the leading dash (-) if a pre-release is defined, otherwise blank. The value is overridden by the Git tag if this is a tagged release.
{BuildMetadata}{CommitHash}<BuildMetadataFormat>The build metadata portion of the version. This will include the leading plus (+) if build metadata is defined, otherwise blank. The value is overridden by the Git tag if this is a tagged release and is defined in the tag.

Version Strings

NameConfiguration TagDefault Value
📦 Full Version<br>aka. the "package" or "product" version, it is used for versioning the package itself and displayed in NuGet.<BuildFullVersionFormat>{Major}.{Minor}.{Patch}{PreRelease}{BuildMetadata}
📄 File Version<br>A superficial version number, displayed by the OS. This is not used by the .NET runtime.<BuildFileVersionFormat>{Major}.{Minor}.{Patch}.0
Assembly Version<br>Used by .NET for referencing the assembly when strong-named signing is enabled. Updating this by major version is advised.<BuildAssemblyVersionFormat>{Major}.0.0.0

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 true.

Enable Output Logging

You can enable output logging for Build Versioning by specifying <BuildVersioningLogLevel> as normal (for basic logging) or high (for detailed logging).