<img src=".meta/Verlite.svg" align="right" width="20%" alt="Logo" />

Verlite

[![Verlite.MsBuild][verlite-msbuild-badge]][verlite-msbuild-link] [![Verlite.CLI][verlite-cli-badge]][verlite-cli-link] [![Verlite.Core][verlite-core-badge]][verlite-core-link]
[![Codecov][codecov-badge]][codecov-link] [![Mutation testing score][mutation-testing-badge]][mutation-testing-link]

Versioning with [SemVer 2][semver-2] Git tags. Automatically set the version from Git tags for .NET Core SDK-style projects, or use the CLI tool for all others. Platform agnostic.

Usage

Add the following to your Directory.Build.props or csproj:

<ItemGroup>
  <PackageReference Include="Verlite.MsBuild" Version="x.y.z" PrivateAssets="All" />
</ItemGroup>

Optionally, if your CI/CD pipelines use shallow clones (such as GitHub Actions by default), add build steps to automatically deepen the repository to—and fetch—the nearest tag:

dotnet tool install --global Verlite.CLI --version "x.y.z"
verlite --auto-fetch

Goals and Scope

Verlite aims to fall somewhere between MinVer and GitVersion—using the same versioning scheme as MinVer, with a slightly richer and more flexible feature set.

Verlite is aimed at continuous delivery workflows, not continuous deployment workflows—where versions are denoted from a branching model or commit messages. Instead with Verlite, tags are the source of truth for versions. Any versions with height attached (see version calculation) are intended only for development purposes and to not be released to the primary feed.

Versioning based upon commit messages or branches is out of scope. Such can be done via passing different options into Verlite by your build process, but keep in mind this is not a supported workflow of Verlite, so shouldn't be done for release critical aspects.

Version Calculation

Take the head commit, if one or more version tags exist, use the highest version, otherwise, keep following all parents until a version tag is found, taking the highest version tag, then bumping the version and appending the "commit height" onto the end.

To bump the version, the patch is by default incremented by 1. The version part to bump can be configured via VerliteAutoIncrement/--auto-increment option.

The commit height is applied by concatenating the prerelease tag, a separator ("."), and the height together, where the prerelease tag is either the last tagged version's prerelease, or if not found/was not a prerelease, using the VerliteDefaultPrereleasePhase/--default-prerelease-phase option.

See docs/VersionCalculation.md for further reading.

Options

| Description | CLI Short, CLI Long, MsBuild Property | Default | | :------------------------------------------------------------------ | :--------------------------------------------------------------- | :------ | | Disable invoking Verlite. | VerliteDisabled | false | | Tags starting with this represent versions. | -t, --tag-prefix, VerliteTagPrefix | v | | Disable the version prefix. | VerliteDisableTagPrefix | false | | The default phase for the prerelease label | -d, --default-prerelease-phase, VerliteDefaultPrereleasePhase | alpha | | The minimum RTM version that's a core version without a prerelease. | -m, --min-version, VerliteMinimumVersion | 0.1.0 | | The height for continuous deliverable auto heights should begin at. | -p, --prerelease-base-height, VerlitePrereleaseBaseHeight | 1 | | Force the calculated version to be this version. | --version-override, VerliteVersionOverride | | | Logging level. | --verbosity, VerliteVerbosity | normal | | Set the build data to this value. | -b, --build-metadata, VerliteBuildMetadata | | | Part of the version to print. | -s, --show | all | | Automatically fetch commits and a tag for shallow clones. | --auto-fetch | false | | Create a lightweight tag instead of fetching the remote's. | --enable-lightweight-tags | false | | Set which version part should be bumped after an RTM release. | -a, --auto-increment, VerliteAutoIncrement | patch | | A command to test whether a tag should be ignored via exit code. | -f, --filter-tags, VerliteFilterTags | | | The remote endpoint to use when fetching tags and commits. | -r, --remote, VerliteRemote | origin | | Generate version strings and embed them via a source generator. | VerliteEmbedVersion | true | | Use a shadow repo (partial, only commits) to read commit history. | --enable-shadow-repo, VerliteEnableShadowRepo | false | | Any change except for ignored files causes a version bump. | --dirty-version-bump- VerliteDirtyVersionBump | false |

Comparison with GitVersion

GitVersion has a focus on branches, and is well suited for a Continuous Deployment workflow, where releases are triggered based upon branches or commit messages. Shallow repositories are not supported.

Verlite cares only about tags, and is well suited for Continuous Delivery workflows, where official releases happen by tagging.

Comparison with MinVer

MinVer's behavior is a subset of Verlite, and so we can configured Verlite to behave the same with the following properties set:

<PropertyGroup>
	<VerliteDisableTagPrefix>true</VerliteDisableTagPrefix>
	<VerliteDefaultPrereleasePhase>alpha.0</VerliteDefaultPrereleasePhase>
<PropertyGroup>

Additionally, Verlite has some extra features, some of which I required or desired, hence the creation of this project. These are:

• Shallow repositories are fully supported.
  • Fetch tags and commits needed for calculating the version with verlite --auto-fetch.
  • Error out if the repository is too shallow instead of silently returning an incorrect version.
• Continuous Delivery versions can start at the first prelease ordinal to reduce long version fatigue. That is to say, after tagging 1.0.0, the next CD version by default is 1.0.1-alpha.1 instead of 1.0.1-alpha.0.1.
  • CD releases after a tagged prerelease behave identical to MinVer, for example, the commit after 1.0.0-rc.1 becomes 1.0.0-rc.1.1 and not 1.0.0-rc.2.
• The default base height after a tag can be set, such as 1.0.0 -> 1.0.1-alpha.0.
• Scripts can query Verlite for a specific version part.

FAQ

• Why Verlite? (simple and feature complete)
• Can I bump the major or minor parts after an RTM tag? (yes)
• Can I change the default phase? (yes)
• Why is the default phase "alpha" and not "alpha.0"? (reduce fatigue)
• Can prereleases be tagged? (yes, must be)
• Can I get the commit hash? (yes)
• Can I use a branching strategy? (sort of)
• Can Verlite be used elsewhere? (yes)
• What is the default tag prefix? ("v")
• Can multiple versions be nested? (yes)
• Can shallow clones be used? (yes)
• What happens if auto fetch isn't used? (nothing unsafe)
• Can I use only signed/specific/arbitrary tags? (yes)
• What is a good changelog strategy? (changes since same or better stability)
• What happens if tag buildmeta and options buildmeta are set? (concatenated together)
• Can I access computed versions in my assembly? (yes)
• Can others access computed versions in the assembly? (no*)
• Can I query the version from the command line for a project? (yes, since net8)

Why Verlite?

For if you find GitVersion too complex and MinVer too minimal for your needs. Verlite is a superset of MinVer, but takes on a small amount of complexity to provide a simpler to use tool.

Can I bump the major or minor parts after an RTM tag?

Yes, the VerliteAutoIncrement option will specify which version part should be bumped after an RTM tag.

Can I change the default phase?

Yes, the the default phase of alpha can be changed using the VerliteDefaultPrereleasePhase option.

Why is the default phase "alpha" and not "alpha.0"?

To reduce fatigue. The first commits after a stable tag are likely to be either: hotfixes that are quickly released, or a merge window opening up, resulting in a flurry of change that developers directly consume from the CD pipeline. Therefore, the default behavior is to omit the leading zero, and keep these particular versions as short as possible.

Should the you prefer alpha.0.n be used after a stable release instead of alpha.n, the VerliteDefaultPrereleasePhase c