TurnerSoftware.BuildVersioning 0.5.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
This package has a SemVer 2.0.0 package version: 0.5.0+g8991ba7-github.8880715784.
dotnet add package TurnerSoftware.BuildVersioning --version 0.5.0
NuGet\Install-Package TurnerSoftware.BuildVersioning -Version 0.5.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="TurnerSoftware.BuildVersioning" Version="0.5.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add TurnerSoftware.BuildVersioning --version 0.5.0
#r "nuget: TurnerSoftware.BuildVersioning, 0.5.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install TurnerSoftware.BuildVersioning as a Cake Addin
#addin nuget:?package=TurnerSoftware.BuildVersioning&version=0.5.0

// Install TurnerSoftware.BuildVersioning as a Cake Tool
#tool nuget:?package=TurnerSoftware.BuildVersioning&version=0.5.0

<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

  • Your project must be using a modern SDK-style project file
  • One of the following .NET runtimes must be installed:
    • .NET 6
    • .NET 8

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.

Example Git Tag Commit Height Full Version File Version Assembly Version
New Release 1.2.4 0 1.2.4+a4f31ea 1.2.4.0 1.0.0.0
New Pre-Release 1.2.4-alpha 0 1.2.4-alpha+a4f31ea 1.2.4.0 1.0.0.0
Main Branch / Active Development 1.2.4 4 1.2.4-dev.4+a4f31ea 1.2.4.0 1.0.0.0
Non-PR Commit via GitHub Actions 1.2.4 4 1.2.4-dev.4+a4f31ea-github.432515 1.2.4.0 1.0.0.0
PR Commit via GitHub Actions 1.2.4 4 1.2.4-pr.17+a4f31ea-github.432515 1.2.4.0 1.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

Integration Configuration Tag Notes
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.

Tag Notes
{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.

Tag Default Value Configuration Tag Description
{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

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

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (4)

Showing the top 4 popular GitHub repositories that depend on TurnerSoftware.BuildVersioning:

Repository Stars
TurnerSoftware/CacheTower
An efficient multi-layered caching system for .NET
TurnerSoftware/MongoFramework
An "Entity Framework"-like interface for MongoDB
Turnerj/Quickenshtein
Making the quickest and most memory efficient implementation of Levenshtein Distance with SIMD and Threading support
TurnerSoftware/InfinityCrawler
A simple but powerful web crawler library for .NET
Version Downloads Last updated
0.5.0 85 4/29/2024
0.4.0 6,413 11/29/2021
0.3.0 941 8/10/2021
0.2.2 135 6/21/2021
0.2.1 948 3/13/2021
0.2.0 245 3/13/2021
0.1.2 140 3/12/2021
0.1.1 173 3/11/2021
0.1.0 164 3/11/2021