Automating .NET Library Versioning with MinVer

TLDR

• MinVer automatically infers version numbers via Git tags, solving issues with manual maintenance or complex tools (like GitVersion) such as configuration failures and branch version confusion.
• If the current commit has a tag, that version is used directly; if not, it automatically increments the patch or pre-release identifier based on the most recent historical tag.
• The default version is 0.0.0-alpha.0, which is automatically appended with the commit height (the number of commits since the tag).
• You must ensure Git is installed and present in the system PATH; otherwise, compilation errors will occur.
• It is recommended to avoid overly complex tag formats (e.g., 0.0.1-alpha.0.0) to prevent confusion in the increment logic.

---

MinVer Versioning Rules

Basic Operating Principle

MinVer's core logic relies entirely on Git history:

• Current commit has a version tag: The version is taken directly from that tag.
• Current commit has no version tag:
  • If a "pre-release" tag is found in history: Use that version directly and append the height (number of commits since the tag).
  • If a "release" tag is found in history: Automatically increment the patch number and append the default pre-release identifier (default is alpha.0) and the height.
  • If no tags are found at all: Use the default version 0.0.0-alpha.0 and append the height.

Property Mapping

MinVer automatically maps the inferred version number to the following .NET properties:

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}

Common Configuration Examples

In the .csproj file, you can customize settings via PropertyGroup:

• Set tag prefix (e.g., if you prefer using v1.0.0):

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

• Custom pre-release identifier (e.g., change to preview):

<PropertyGroup>
  <MinVerDefaultPreReleaseIdentifiers>preview.0</MinVerDefaultPreReleaseIdentifiers>
</PropertyGroup>

---

Implementation Examples and FAQs

When does version number confusion occur?

When the tag naming format is too complex (e.g., 0.0.1-alpha.0.0), MinVer may produce results like 0.0.1-alpha.0.0.1 during incrementing, making the versioning logic difficult to maintain.

TIP

It is recommended to keep tag formats simple and avoid using multi-level pre-release identifiers.

When do compilation errors occur?

If you encounter a git is not present in PATH. error while building the project, it means the system environment variable does not include the Git path.

TIP

Please ensure that Git is correctly installed and that running git --version in the command line works as expected.

Verification of Implementation Results

Depending on the Git state, the version numbers produced by MinVer are as follows:

• No tag state: Produces 0.0.0-alpha.0.1.nupkg.
• Previous commit is release tag 0.1.0: Automatically increments to 0.1.1-alpha.0.1.nupkg.
• Previous commit is pre-release tag 0.0.1-alpha.0: Produces 0.0.1-alpha.0.1.nupkg.
• Latest commit is release tag 0.1.2: Uses the tag version 0.1.2.nupkg directly.

---

Changelog

1. 2025-03-29

   • Initial documentation created.