MinVer

MinVer is a minimalist .NET build package, developed by humans, for versioning .NET SDK-style projects using Git tags.

Platform support: all platforms supported by .NET SDK-style projects.

minver-cli is a minimalist .NET tool, developed by humans, for versioning any kind of software or content using Git tags.

• Prerequisites
• Quick start
• Usage
• How it works
• Version numbers
• Options
• FAQ

Prerequisites

• .NET SDK 8.0 or later
• Git

Quick start

• Install MinVer.
• Build your project.

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.

Usage

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 on the commit you want to release with a name which is a valid SemVer 2.x version. For example:

git tag 1.2.3
git push --tags

When you build your software from the commit with that tag, MinVer will apply the version to the assemblies and packages. (If you like to prefix your tag names, see the FAQ.)

Bear in mind that MinVer is unaware of the branches which contain the commit, nor your release process, so it is compatible with any branching or release strategy you choose.

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.

How it works

• If the current commit has a version tag:
  • The version is used as-is.
• If the current commit does not have a version tag:
  • The commit history is searched for the latest commit with a version tag.
    • If a commit with a version tag is found:
      • If the version is a pre-release:
        • The version is used as-is, with height added.
      • If the version is RTM (not pre-release):
        • The patch number is incremented, but this can be customised.
        • Default pre-release identifiers are added. The default identifiers are alpha.0, but this can be customised.
        • For example, if the latest version tag is 1.0.0, the current version is 1.0.1-alpha.0.
        • Height is added.
    • If no commit with a version tag is found:
      • The default version 0.0.0-alpha.0 is used, with height added.

Height

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 1.0.0-beta.1.42.

This behaviour can be disabled.

For information, see What is height for?

Version numbers

MinVer sets the following custom properties:

• MinVerVersion
• MinVerMajor
• MinVerMinor
• MinVerPatch
• MinVerPreRelease
• MinVerBuildMetadata

Those properties are used to set the following .NET SDK properties, satisfying the official open-source library guidance for version numbers:

| Property | Value | |------------------------|-----------------------------------------------------------------------------------------------------------------| | AssemblyVersion | {MinVerMajor}.0.0.0 | | FileVersion | {MinVerMajor}.{MinVerMinor}.{MinVerPatch}.0 | | InformationalVersion | {MinVerVersion} | | PackageVersion | {MinVerMajor}.{MinVerMinor}.{MinVerPatch} (or {MinVerMajor}.{MinVerMinor}.{MinVerPatch}-{MinVerPreRelease}) | | Version | {MinVerMajor}.{MinVerMinor}.{MinVerPatch} (or {MinVerMajor}.{MinVerMinor}.{MinVerPatch}-{MinVerPreRelease}) |

This behaviour can be customised.

Options

Options may be specified as either MSBuild properties (for the MinVer package), command-line options (for the minver-cli package), or environment variables (for both the MinVer and minver-cli packages).

| MSBuild property or environment variable | Command-line option | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | MinVerAutoIncrement | -a\|--auto-increment | | MinVerBuildMetadata | -b\|--build-metadata | | MinVerDefaultPreReleaseIdentifiers | -p\|--default-pre-release-identifiers | | MinVerIgnoreHeight | -i\|--ignore-height | | MinVerMinimumMajorMinor | -m\|--minimum-major-minor | | MinVerSkip | n/a (environment variable not supported) | | MinVerTagPrefix | -t\|--tag-prefix | | MinVerVerbosity | -v\|--verbosity | | MinVerVersionOverride | n/a (environment variable supported)