README.md

Cake.MinVer

Cross-platform addin for the Cake build automation system that enables you to use MinVer for versioning projects using Git tags. The latest version of Cake.MinVer targets .NET 7.0 and .NET 6.0, and runs on Windows, Linux, and macOS.

Give a Star! ⭐

If you like or are using this project please give it a star. Thanks!

Prerequisites

In order to use Cake.MinVer, you will need to install Cake and MinVer dotnet tools either as local tools (recommended) or as global tools, and these tools require .NET Core SDK 2.1.300 or later and Git.

Getting started 🚀

This addin exposes the functionality of MinVer to the Cake DSL by being a very thin wrapper around its command line interface; this means that you can use Cake.MinVer in the same way as you would normally use minver-cli, but with a Cake-friendly interface.

First of all, you need to import Cake.MinVer in your build script by using the addin directive:

#addin "nuget:?package=Cake.MinVer&version=3.0.0"

Make sure the &version= attribute references the latest version of Cake.MinVer compatible with the Cake runner that you are using. Check the compatibility table to see which version of Cake.MinVer to choose.

Next, call MinVer() in order to get the version information using the default settings:

#addin "nuget:?package=Cake.MinVer&version=3.0.0"

var version = MinVer();

Task("Example")
    .Does(context =>
{
    context.Information($"Version: {version.Version}");
    context.Information($"Major: {version.Major}");
    context.Information($"Minor: {version.Minor}");
    context.Information($"Patch: {version.Patch}");
    context.Information($"PreRelease: {version.PreRelease}");
    context.Information($"BuildMetadata: {version.BuildMetadata}");
});

RunTarget("Example");

Using Cake.MinVer with Cake and MinVer installed as local tools

Install Cake and MinVer as local tools in your project (one-time setup):

dotnet new tool-manifest
dotnet tool install cake.tool
dotnet tool install minver-cli
git add .config/dotnet-tools.json
git commit -m "Install Cake & MinVer dotnet tools"

Then, before buiding your project (e.g. in your CI server), ensure that Cake and MinVer are available before running your Cake build, by running dotnet tool restore:

dotnet tool restore
dotnet cake

Using Cake.MinVer with Cake and MinVer installed as global tools

Install Cake and MinVer as global tools in your project (one-time setup):

dotnet tool install --global cake.tool
dotnet tool install --global minver-cli

MinVer properties available to your Cake build script

Property	Type	Description
Version	string	The original, non-normalized version string
Major	int	The major version number
Minor	int	The minor version number
Patch	int	The patch version number
PreRelease	string	The pre-release extension
IsPreRelease	bool	true if PreRelease is not null or empty
BuildMetadata	string	The build metadata extension
AssemblyVersion	string	{Major}.0.0.0
FileVersion	string	{Major}.{Minor}.{Patch}.0
InformationalVersion	string	same as Version above
PackageVersion	string	same as Version above

MinVer settings you can customize

Property	Type	Description
AutoIncrement	MinVerAutoIncrement	The version part to be automatically incremented: Default, Major, Minor, or Patch
BuildMetadata	string	The build metadata
DefaultPreReleasePhase	string	The default pre-release phase
MinimumMajorMinor	string	The minimum major and minor version
Repo	DirectoryPath	The working directory for MinVer to use
TagPrefix	string	The tag prefix
Verbosity	MinVerVerbosity	The verbosity: Default, Error, Warn, Info, Debug, Trace

For more details on how MinVer works, check its documentation.

Using Cake.MinVer with custom settings

You can define your settings using an instance of MinVerSettings, for example:

var settings = new MinVerSettings()
{
    AutoIncrement = MinVerAutoIncrement.Minor,
    DefaultPreReleasePhase = "preview",
    MinimumMajorMinor = "2.5",
    TagPrefix = "v",
    Verbosity = MinVerVerbosity.Trace,
};

var version = MinVer(settings);

Alternatively, you can define your settings using Cake's configurator pattern:

var version = MinVer(settings => settings
    .WithMinimumMajorMinor("2.5")
    .WithAutoIncrement(MinVerAutoIncrement.Minor)
    .WithDefaultPreReleasePhase("preview")
    .WithMinimumMajorMinor("2.5")
    .WithTagPrefix("v")
    .WithVerbosity(MinVerVerbosity.Trace)
);

Usage Examples

In the sample folder, there are several examples of usage:

• Default settings
• Custom settings with MinVerSettings instance
  • Increment the minor version
  • Set the build metadata
  • Set the default pre-release phase
  • Set the minimum major and minor version
  • Set the working directory
  • Set the tag prefix
  • Set the verbosity
• Custom settings with configurator pattern
  • Increment the minor version
  • Set the build metadata
  • Set the default pre-release phase
  • Set the minimum major and minor version
  • Set the working directory
  • Set the tag prefix
  • Set the verbosity

Compatibility

Cake.MinVer is compatible with all Cake runners that run on .NET 5 or .NET Core 2.1+, and below you can find which version of Cake.MinVer you should use based on the version of the Cake runner you're using.

Cake runner	Cake.MinVer	Cake addin directive
3.0.0 or higher	3.0.0 or higher	#addin "nuget:?package=Cake.MinVer&version=3.0.0"
2.0.0 - 2.3.0	2.0.0	#addin "nuget:?package=Cake.MinVer&version=2.0.0"
1.0.0 - 1.3.0	1.0.0 - 1.0.1	#addin "nuget:?package=Cake.MinVer&version=1.0.1"
0.33.0 - 0.38.5	0.2.0	#addin "nuget:?package=Cake.MinVer&version=0.2.0"
< 0.33.0	N/A	(not supported)

Discussion

For questions and to discuss ideas & feature requests, use the GitHub discussions on the Cake GitHub repository, under the Extension Q&A category.

Release History

Click on the Releases tab on GitHub.

---

Copyright © 2020-2023 C. Augusto Proiete & Contributors - Provided under the MIT License.