Automating .NET Class Library Versioning with MinVer

TLDR

• MinVer automatically infers version numbers via Git tags, solving issues where GitVersion becomes complex to configure and unstable on feature branches after upgrades.
• If the current commit has a tag, that version is used directly; if not, it automatically increments the patch or pre-release version based on the most recent tag in history.
• MinVer automatically updates attributes such as AssemblyVersion, FileVersion, and PackageVersion, simplifying the CI/CD process.
• It is recommended to avoid pre-release tags ending in numbers (e.g., 0.0.1-alpha.0.0) to prevent confusion during version increments.
• If you encounter a git is not present in PATH error during execution, ensure that Git is correctly installed and added to your system environment variables.

How MinVer Versioning Works

The core logic of MinVer lies in version inference based on Git history, making it suitable for .NET projects that require automated NuGet package version management.

Version Inference Rules

Under what circumstances does the version number change? When a developer moves or adds tags in the Git history, MinVer operates according to the following logic:

• Current commit has a version tag: The tagged version is used directly.
• Current commit has no version tag:
  • Search for the most recent tag:
    • If it is a pre-release version: Use that version directly and append the height (number of commits since the tag).
    • If it is a release version: Automatically increment the patch number and append the default pre-release identifier (default is alpha.0) and the height.
  • If no tag is found at all: Defaults to 0.0.1-alpha.0 plus the height.

Attribute Mapping Table

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

Attribute	Mapping Format
AssemblyVersion	{MinVerMajor}.0.0.0
FileVersion	{MinVerMajor}.{MinVerMinor}.{MinVerPatch}.0
InformationalVersion	{MinVerVersion}
PackageVersion	{MinVerMajor}.{MinVerMinor}.{MinVerPatch} (or including pre-release identifier)

Implementation and Configuration Recommendations

In the .csproj file, you can use PropertyGroup to customize settings to match your team's tagging conventions.

Common Configuration Examples

When do you need custom settings? When your team is accustomed to using a v prefix (e.g., v1.0.0) or wishes to change the pre-release identifier to preview.

<PropertyGroup>
  <!-- Set version tag prefix -->
  <MinVerTagPrefix>v</MinVerTagPrefix>
  <!-- Custom pre-release identifier -->
  <MinVerDefaultPreReleaseIdentifiers>preview.0</MinVerDefaultPreReleaseIdentifiers>
</PropertyGroup>

Verification of Implementation Results

Depending on the Git state, the version number behavior generated by MinVer is as follows:

• Untagged state: The system automatically generates a version in the 0.0.0-alpha.0.1 format.  

• Adding a release version tag: If the previous commit was 0.1.0, the current version will automatically increment to 0.1.1-alpha.0.1.  

• Adding a pre-release version tag: If the previous commit was 0.0.1-alpha.0, it will increment based on this version.  

• Latest commit tag: If you tag 0.1.2 directly on the current commit, the version number will map precisely.  

TIP

Avoid using tag formats like 0.0.1-alpha.0.0, otherwise the next one will become 0.0.1-alpha.0.0.1, causing version number confusion.

WARNING

If you encounter a git is not present in PATH. error when installing MinVer in your project, it means Git is not set in the path of your environment variables. You need to ensure that Git can be executed from the command line.

Change Log

• 2025-03-29 Initial documentation created.