View on GitHub

sprig

Useful template functions for Go templates.

Semantic Version Functions

Some version schemes are easily parseable and comparable. Sprig provides functions for working with SemVer 2 versions.

semver

The semver function parses a string into a Semantic Version:

$version := semver "1.2.3-alpha.1+123"

If the parser fails, it will cause template execution to halt with an error.

At this point, $version is a pointer to a Version object with the following properties:

Additionally, you can compare a Version to another version using the Compare function:

semver "1.4.3" | (semver "1.2.3").Compare

The above will return -1.

The return values are:

(Note that in SemVer, the Metadata field is not compared during version comparison operations.)

semverCompare

A more robust comparison function is provided as semverCompare. This version supports version ranges:

The SemVer functions use the Masterminds semver library, from the creators of Sprig.

Basic Comparisons

There are two elements to the comparisons. First, a comparison string is a list of comma separated and comparisons. These are then separated by || separated or comparisons. For example, ">= 1.2, < 3.0.0 || >= 4.2.3" is looking for a comparison that’s greater than or equal to 1.2 and less than 3.0.0 or is greater than or equal to 4.2.3.

The basic comparisons are:

Note, according to the Semantic Version specification pre-releases may not be API compliant with their release counterpart. It says,

A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

SemVer comparisons without a pre-release value will skip pre-release versions. For example, >1.2.3 will skip pre-releases when looking at a list of values while >1.2.3-alpha.1 will evaluate pre-releases.

Hyphen Range Comparisons

There are multiple methods to handle ranges and the first is hyphens ranges. These look like:

Wildcards In Comparisons

The x, X, and * characters can be used as a wildcard character. This works for all comparison operators. When used on the = operator it falls back to the pack level comparison (see tilde below). For example,

Tilde Range Comparisons (Patch)

The tilde (~) comparison operator is for patch level ranges when a minor version is specified and major level changes when the minor number is missing. For example,

Caret Range Comparisons (Major)

The caret (^) comparison operator is for major level changes. This is useful when comparisons of API versions as a major change is API breaking. For example,