MinVer Documentation

When the current commit does not have a version tag, MinVer adds a number called "height" to the pre-release identifiers.

Height is the number of commits since the latest commit with a version tag (or since the root commit if no tags exist).

Example: If the latest version tag is 1.0.0-beta.1 and there are 42 commits since that tag, the calculated version will be 1.0.0-beta.1.42.

MinVer determines the version based on the current commit's relationship to Git tags:

1. Current commit has a version tag: The version is used exactly as specified in the tag.
2. Current commit does not have a tag:
   • MinVer searches the history for the latest commit with a version tag.
   • If a pre-release tag is found (e.g., 1.0.0-beta.1): The version is used as-is, and the height (number of commits since that tag) is appended to the pre-release identifiers (e.g., 1.0.0-beta.1.42).
   • If an RTM (non-pre-release) tag is found (e.g., 1.0.0): The patch number is incremented, default pre-release identifiers (default: alpha.0) are added, and the height is appended (e.g., 1.0.1-alpha.0.42).
   • If no version tag is found in history: The default version 0.0.0-alpha.0 is used, with the height appended.

To release a specific version of your software, create a Git tag on the desired commit using a valid SemVer 2.x name. MinVer will detect this tag during the build process and apply the version to your assemblies and packages.

Example:

git tag 1.2.3
git push --tags

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

Prerequisites

• .NET SDK 8.0 or later
• Git

Installation

1. Install the MinVer NuGet package.
2. When adding the package reference, it is recommended to include PrivateAssets="All" to prevent it from being a dependency of your project's consumers. If you install via an IDE or tool, this is usually handled automatically.

Quick Start

Once installed, simply build your project. MinVer will automatically version your project based on the latest Git tag found in your commit history.

<PackageReference Include="MinVer" Version="7.0.0" PrivateAssets="All" />

If you are working on a specific MAJOR.MINOR range (e.g., 1.1) on a branch, you can force MinVer to use that range for interim builds instead of the default 0.0.0-alpha.0 or the latest tag in history.

There are two ways to accomplish this:

1. Tag a commit: Create a tag on your branch matching your target range using a pre-release identifier. This forces MinVer to start versioning in that range. Example: git tag 1.0.0-alpha.0.
2. Use MinVerMinimumMajorMinor: Set this property in your project file to specify the minimum range. MinVer will use a default version of {MinVerMinimumMajorMinor}.0.0-alpha.0 for interim builds.

<!-- Option 1: Tagging a commit -->
```shell
git tag 1.0.0-alpha.0

<!-- Option 2: Using MinVerMinimumMajorMinor in MSBuild -->

<PropertyGroup>
  <MinVerMinimumMajorMinor>1.0</MinVerMinimumMajorMinor>
</PropertyGroup>

MinVer is available as a command-line tool (minver-cli) for versioning non-.NET software (like container images or other languages).

To ensure consistency between a .NET build and other components in the same pipeline, run the CLI tool first, then set the MINVERVERSIONOVERRIDE environment variable to the output of the CLI. The MinVer NuGet package will then use this overridden value instead of recalculating it.

# Run the CLI to get the version
minver

# Use the output to set the override for subsequent .NET builds
export MINVERVERSIONOVERRIDE=$(minver)

By default, MinVer looks for standard SemVer tags. If your repository uses prefixes (e.g., v1.2.3 or main-1.2.3), you must specify the prefix using MinVerTagPrefix. The prefix is case-insensitive.

This is particularly useful for versioning multiple projects in a single repository independently. For example, a project named ext could use <MinVerTagPrefix>ext-</MinVerTagPrefix> to only respond to tags like ext-1.0.0.

<PropertyGroup>
  <MinVerTagPrefix>v</MinVerTagPrefix>
</PropertyGroup>

If MinVer is not producing the expected version, check the following:

1. Is MinVer running? Check if MinVerSkip is set to true.
2. Is the tag correctly placed? The tag must be on the current commit or an ancestor of the current commit.
3. Is the version superseded? Check if there is a newer version tag on a later ancestor or a higher version on the same commit. Also check if MinVerVersionOverride or MinVerMinimumMajorMinor are interfering.
4. Is the prefix correct? Ensure the tag matches MinVerTagPrefix.
5. Is the version valid SemVer 2.0? Ensure no leading zeros in numeric identifiers and that identifiers only contain [0-9A-Za-z-].

Pro-tip: Increase MinVerVerbosity to detailed to see exactly which tags MinVer found and why it ignored them.

MinVer sets several custom properties that are used to populate standard .NET SDK version properties. This ensures compliance with official .NET library versioning guidance.

Custom MinVer Properties

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

.NET SDK Property Mappings