semver

README

go-semver

Simple version string parser, bulider, bumper etc. Follows strictly semantic Versioning 2.0.0 specification and has unit tests to ensure it works for most edge cases.

Note: this isn't stable version yet. It should do the job and all tests are passing but API will be freezed only after version 1.0.0 tag. No promises till that point.

Features

• Validate version stored in a string.
• Parse and unpack to standarized Version structure where it can be easily introspected or used for higher "business" logic.
• Bump parsed structure to next version.
• Operator to compare two versions: allows choosing max version, sorting etc.

Install

Run go get github.com/adamwasila/go-semver

Requirements

go 1.15 or newer is preferred. Run all unit tests first before using any older version of go.

Examples

Create new semver struct:

sv, _ := semver.New(
    semver.SetCore("1.2.3"),
    semver.Prerelease("rc.1"), semver.BuildMetadata("cafebabe"),
)
fmt.Printf("%s", sv.String())

Output:

1.2.3-rc.1+cafebabe

Parse string with version (will panic if version is incorrect):

v := "1.2.3-ver.12a+build.1234"
sv := semver.MustParse(v)
fmt.Printf("%s == %s", v, sv.String())

Output:

1.2.3-ver.12a+build.1234 == 1.2.3-ver.12a+build.1234

Bump version:

sv := semver.MustParse("1.2.3-rc.1+cafebabe")
sv, _ = sv.Bump(semver.NextMajor())
fmt.Printf("%s", sv.String())

Output:

2.0.0

Tools

There are few commandline tools available built with help of this library stored in this repository. These can be regarded as example of library use but should be useful as standalone tools used for release scripting.

semver-verify

Validates versions specified in argument list returning error code and description of each version that does not follow semver 2.0 format strictly.

Example of use:

$ semver-verify 1.0.0 2.1.1 3.0.0-rc.1 4.0.0-invalid.~

Invalid version: '4.0.0-invalid.~', error at position 14: invalid character in prerelease identifier: '~'

semver-sort

Reads standard input with list of versions, sorts them accordingly and returns the result. Have few flags to customize output as shown in following examples:

Sort list of versions, plain and simple (default behaviour):

$ echo "17.0.0 1.2.3 2.0.0-rc.0 2.0.0-alpha.0 2.0.0-beta.0" | semver-sort

1.2.3
2.0.0-alpha.0
2.0.0-beta.0
2.0.0-rc.0
17.0.0 

Show only the last (newest) version in the set:

$ echo "3.0.0 5.0.0 17.0.0-prerelease0 17.0.0 1.2.3 2.0.0-rc.0 2.0.0-alpha.0 2.0.0-beta.0" | semver-sort -1

17.0.0

Show oldest version in the set:

$ echo "3.0.0 5.0.0 17.0.0-prerelease0 17.0.0 1.2.3 2.0.0-rc.0 2.0.0-alpha.0 2.0.0-beta.0" | semver-sort -1 -r

1.2.3

semver-bump

Reads single version given as argument and bump it to next version with help of specified flags.

If no specific flag given will attempt to bump into next patch version.

Examples:

$ semver-bump -major 2.4.16

3.0.0

$ semver-bump -meta `git rev-parse HEAD` -patch 1.2.3

1.2.4+e8175a115ddbb63de0d34003ed0acde9cd66e21f

$ semver-bump -release 2.0.0-rc.0

2.0.0

License

Distributed under Apache License Version 2.0. See LICENSE for more information.

Contact

To discuss about bugs or features: please fill gitlab issue ticket.

Pull Requests except for trivial (eg. typo) fixes should also be discussed by opening issue first.

Documentation

Overview

Package semver provides methods to validate, parse, compare and modify semantic version compliant strings.

Index

• Variables
• func BuildMetadata(bl string) func(*Version) error
• func Less(s1, s2 *Version) bool
• func Prerelease(pr string) func(*Version) error
• func SetCore(core string) func(*Version) error
• func Valid(semver string) bool
• type BumpOption
  • func NextMajor() BumpOption
  • func NextMinor() BumpOption
  • func NextPatch() BumpOption
  • func NextPrerelease() BumpOption
  • func NextRelease() BumpOption
• type Version
  • func MustParse(semver string) Version
  • func New(options ...func(*Version) error) (*Version, error)
  • func Parse(s string) (Version, error)
  • func (semver *Version) Bump(options ...BumpOption) (Version, error)
  • func (semver *Version) MustBump(options ...BumpOption) Version
  • func (semver *Version) String() string
  • func (semver *Version) Valid() bool

Examples

• Less
• MustParse
• New
• Version.Bump

Variables

var ErrCorruptedVersion = errors.New("corrupted version")

var ErrNoPrerelease = errors.New("no prerelease set in version")

Functions

func BuildMetadata

func BuildMetadata(bl string) func(*Version) error

BuildMetadata return option to set buildmetadata component. Empty string is silently ignored returning no error.

In current spec buildmetadata must consist of:

* dot separated, nonempty components of [a-zA-Z0-9-] alphabet.

func Less

func Less(s1, s2 *Version) bool

Less perform comparison of to specified versions. It strictly follows rules of semver specification, paragraph 11.: https://semver.org/#spec-item-11

Example

versions := []string{
	"1.0.0+first",
	"1.0.0+second",
	"1.0.0+3rd",
	"1.0.0-rc.1",
	"1.0.0-beta.11",
	"1.0.0-beta.2",
	"1.0.0-beta",
	"1.0.0-alpha.beta",
	"1.0.0-alpha.1",
	"1.0.0-alpha",
}

sort.SliceStable(versions, func(i, j int) bool {
	v1 := semver.MustParse(versions[i])
	v2 := semver.MustParse(versions[j])
	return semver.Less(&v1, &v2)
})

for i, v := range versions {
	fmt.Printf("%d. %v\n", i, v)
}

Output:

0. 1.0.0-alpha
1. 1.0.0-alpha.1
2. 1.0.0-alpha.beta
3. 1.0.0-beta
4. 1.0.0-beta.2
5. 1.0.0-beta.11
6. 1.0.0-rc.1
7. 1.0.0+first
8. 1.0.0+second
9. 1.0.0+3rd

func Prerelease

func Prerelease(pr string) func(*Version) error

Prerelease return option to set prerelease component. Empty string is silently ignored returning no error. Calling this option will not clear prerelease component so it may be used more than once and final result will be sum of all requests

With current spec valid request string should be:

* dot separated, nonempty components of [a-zA-Z0-9-] alphabet * if only numbers are used for particular component leading zeroes are forbidden

Valid examples:

`a.b.c`, `rc.1`, `rc01`, `alpha.beta.gamma` etc.

func SetCore

func SetCore(core string) func(*Version) error

SetCore returns option to set version core: dot separated major, minor and patch number. Numbers must not have leading zeros.

func Valid

func Valid(semver string) bool

Valid performs regular parse and returns whetever it was successful or not bug discarding actual result

Types

type BumpOption

type BumpOption func(*Version) error

BumpOption is function option that changes version to newer

func NextMajor

func NextMajor() BumpOption

NextMajor is major version increment

func NextMinor

func NextMinor() BumpOption

NextMinor is minor version increment

func NextPatch

func NextPatch() BumpOption

NextPatch is patch version increment

func NextPrerelease

func NextPrerelease() BumpOption

NextPrerelease is incrementing last numeric prerelease component

func NextRelease

func NextRelease() BumpOption

NextRelease is increment to next non-prerelease version

type Version

type Version struct {
	Major         string
	Minor         string
	Patch         string
	Prerelease    []string
	Buildmetadata []string
}

func MustParse

func MustParse(semver string) Version

MustParse behaves like Parse but in case validation fails simply panics instead of returning an error

Example

v := "1.2.3-ver.12a+build.1234"
sv := semver.MustParse(v)
fmt.Printf("%s == %s", v, sv.String())

Output:

1.2.3-ver.12a+build.1234 == 1.2.3-ver.12a+build.1234

func New

func New(options ...func(*Version) error) (*Version, error)

New creates new version struct instance

Example

sv, _ := semver.New(
	semver.SetCore("1.2.3"),
	semver.Prerelease("rc.1"), semver.BuildMetadata("cafebabe"),
)
fmt.Printf("%s", sv.String())

Output:

1.2.3-rc.1+cafebabe

func Parse

func Parse(s string) (Version, error)

Parse unpacks provided version string to predefined Version struct

func (*Version) Bump

func (semver *Version) Bump(options ...BumpOption) (Version, error)

Bump changes version to newer using provided list of bump options

Example

sv := semver.MustParse("1.2.3-rc.1+cafebabe")
sv, _ = sv.Bump(semver.NextMajor())
fmt.Printf("%s", sv.String())

Output:

2.0.0

func (*Version) MustBump

func (semver *Version) MustBump(options ...BumpOption) Version

MustBump works like Bump but panics in cases where Bump returns an error

func (*Version) String

func (semver *Version) String() string

String returns semver compliant version string. It is efectively a reverse of Parse/MustParse functions.

func (*Version) Valid

func (semver *Version) Valid() bool

Valid checks if version struct follows semver rules. Instances created by New must always be valid. Purpose of this method is to check directly created or modified structs.