minver

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:

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

Note that the names of the MSBuild properties and environment variables are case-insensitive.

FAQ

(With TL;DR answers inline.)

• Why not use GitVersion, Nerdbank.GitVersioning, or some other tool? (simplicity)
• What is height for? (not for versioning)
• Can I bump the major or minor version? (yes)
• Can I use my own pre-release versioning scheme? (yes)
• Can I prefix my tag names? (yes)
• Can I use my own branching strategy? (yes)
• Can I include build metadata in the version? (yes)
• Can I auto-increment the minor or major version after an RTM tag instead of the patch version? (yes)
• Can I change the default pre-release identifiers from alpha.0 to something else? (yes)
• Can I use the version calculated by MinVer for other purposes? (yes)
• Can I version multiple projects in a single repository independently? (yes)
• Can I ignore the height of the latest tag or root commit? (yes)
• Can I get log output to see how MinVer calculates the version? (yes)
• Can I use MinVer to version software which is not built using a .NET SDK style project? (yes)
• Can I disable MinVer? (yes)
• What if the history diverges, and more than one tag or root commit is found? (nothing bad)
• What if the history diverges, and then converges again, before the latest tag (or root commit) is found? (nothing bad)
• Why is the default version sometimes used in GitHub Actions, Azure Pipelines, and Travis CI when a version tag exists in the history? (shallow clones)
• Why is my version tag ignored? (MinVer is not running, the tag is misplaced, the version is superseded, the prefix is wrong, or the version is not valid SemVer 2.0)

Why not use