4.7 KiB
tagcmp
Comparison operations for image tags. Because registries aren't doing this for us 🙄 This library is helpful if you're aiming to use only "stable" and "semver-like" tags and want to be able to do things like compare them, find which tags are more recent, sort them and other types of comparisons.
A best-effort implementation which follows the wisdom of Renovate.
Docker doesn't really have versioning, instead it supports "tags" and these are usually used by Docker image authors as a form of versioning ... It's pretty "wild west" for tagging and not always compliant with SemVer.
The Renovate implementation, which allows image tags to be automatically upgraded, is the only show in town, apparently. This library follows that implementation quite closely.
go doc
package tagcmp // import "coopcloud.tech/tagcmp"
Package tagcmp provides image tag comparison operations.
VARIABLES
var CommitHashPattern = "^[a-f0-9]{7,40}$"
CommitHashPattern matches commit-like hash tags
var DotPattern = "([0-9]+)\\.([0-9]+)"
DotPattern matches tags which contain multiple versions
var EmptyPattern = "^$"
EmptyPattern matches when tags are missing
var ParametrizedPattern = "\\${.+}"
ParametrizedPattern matches when tags are parametrized
var StringPattern = "^[a-zA-Z]+$"
StringPattern matches when tags are only made up of alphabetic characters
FUNCTIONS
func IsParseable(tag string) bool
IsParseable determines if a tag is supported by this library
TYPES
type ByTag []Tag
ByTag sorts tags
func (t ByTag) Len() int
func (t ByTag) Less(i, j int) bool
func (t ByTag) Swap(i, j int)
type Tag struct {
Major string `json:",omitempty"` // major semver part
Minor string `json:",omitempty"` // minor semver part
MissingMinor bool // whether or not the minor semver part was left out
Patch string `json:",omitempty"` // patch semver part
MissingPatch bool // whether or not he patch semver part was left out
Suffix string // tag suffix (e.g. "-alpine")
UsesV bool // whether or not the tag uses the "v" prefix
}
func Parse(tag string) (Tag, error)
Parse converts an image tag into a structured data format. It aims to to
support the general case of tags which are "semver-like" and/or stable and
parseable by heuristics. Image tags follow no formal specification and
therefore this is a best-effort implementation. Examples of tags this
function can parse are: "5", "5.2", "v4", "v5.3.6", "4-alpine",
"v3.2.1-debian".
func (t Tag) Equals(tag Tag) bool
Equals tests Tag equality
func (t Tag) IsCompatible(tag Tag) bool
IsCompatible determines if two tags can be compared together
func (t Tag) IsGreaterThan(tag Tag) bool
IsGreaterThan tests if a tag is greater than another. There are some
tag-isms to take into account here, shorter is bigger (i.e. 2.1 > 2.1.1 ==
true, 2 > 2.1 == true).
func (t Tag) IsLessThan(tag Tag) bool
IsLessThan tests if a tag is less than another. There are some tag-isms to
take into account here, shorter is bigger (i.e. 2.1 < 2.1.1 == false, 2 <
2.1 == false).
func (t Tag) String() string
String formats a Tag correctly in string representation
Types of versions supported
// semver
"5",
"2.6",
"4.3.5",
// semver with 'v'
"v1",
"v2.3",
"v1.0.2",
// semver with suffix
"6-alpine",
"6.2-alpine",
"6.2.1-alpine",
// semver with sufix and 'v'
"v6-alpine",
"v6.2-alpine",
"v6.2.1-alpine",
"v6.2.1-alpine",
// semver with multiple suffix values
"v6.2.1-alpine-foo",
Types of versions not supported
Please note, we could support some of these versions if people really need them to be supported. Some tags are using a unique format which we could support by implementing a very specific parser for (e.g.
ParseMinioTag,ParseZncTag). For now, this library tries to provide aParsefunction which handles more general cases. Please open an issue, change sets are welcome.
// empty
"",
// patametrized
"${MAILU_VERSION:-master}",
"${PHP_VERSION}-fpm-alpine3.13",
// commit hash like
"0a1b2c3d4e5f6a7b8c9d0a1b2c3d4e5f6a7b8c9d",
// numeric
"20191109",
"e02267d",
// not semver
"3.0.6.0",
"r1295",
"version-r1070",
// prerelease
"3.7.0b1",
"3.8.0b1-alpine",
// multiple versions
"5.36-backdrop-php7.4",
"v1.0.5_3.4.0",
"v1.0.5_3.4.0_openid-sso",
// tz based
"RELEASE.2021-04-22T15-44-28Z",
// only text
"alpine",
"latest",
"master",
// multiple - delimters
"apache-debian-1.8-prod",
"version-znc-1.8.2",