tagcmp/README.md

# 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.

[renovate]: https://github.com/renovatebot/renovate/blob/main/lib/versioning/docker/readme.md
[renovate implementation]: https://github.com/renovatebot/renovate/tree/main/lib/datasource/docker

## 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

```golang
// 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 a `Parse` function
> which handles more general cases. Please open an issue, change sets are
> welcome.

```golang
// 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",
```

## License

[GPLv3+](./LICENSE)