1# SemVer 2 3The `semver` package provides the ability to work with [Semantic Versions](http://semver.org) in Go. Specifically it provides the ability to: 4 5* Parse semantic versions 6* Sort semantic versions 7* Check if a semantic version fits within a set of constraints 8* Optionally work with a `v` prefix 9 10[![Stability: 11Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html) 12[![Build Status](https://travis-ci.org/Masterminds/semver.svg)](https://travis-ci.org/Masterminds/semver) [![Build status](https://ci.appveyor.com/api/projects/status/jfk66lib7hb985k8/branch/master?svg=true&passingText=windows%20build%20passing&failingText=windows%20build%20failing)](https://ci.appveyor.com/project/mattfarina/semver/branch/master) [![GoDoc](https://godoc.org/github.com/Masterminds/semver?status.svg)](https://godoc.org/github.com/Masterminds/semver) [![Go Report Card](https://goreportcard.com/badge/github.com/Masterminds/semver)](https://goreportcard.com/report/github.com/Masterminds/semver) 13 14If you are looking for a command line tool for version comparisons please see 15[vert](https://github.com/Masterminds/vert) which uses this library. 16 17## Parsing Semantic Versions 18 19To parse a semantic version use the `NewVersion` function. For example, 20 21```go 22 v, err := semver.NewVersion("1.2.3-beta.1+build345") 23``` 24 25If there is an error the version wasn't parseable. The version object has methods 26to get the parts of the version, compare it to other versions, convert the 27version back into a string, and get the original string. For more details 28please see the [documentation](https://godoc.org/github.com/Masterminds/semver). 29 30## Sorting Semantic Versions 31 32A set of versions can be sorted using the [`sort`](https://golang.org/pkg/sort/) 33package from the standard library. For example, 34 35```go 36 raw := []string{"1.2.3", "1.0", "1.3", "2", "0.4.2",} 37 vs := make([]*semver.Version, len(raw)) 38 for i, r := range raw { 39 v, err := semver.NewVersion(r) 40 if err != nil { 41 t.Errorf("Error parsing version: %s", err) 42 } 43 44 vs[i] = v 45 } 46 47 sort.Sort(semver.Collection(vs)) 48``` 49 50## Checking Version Constraints 51 52Checking a version against version constraints is one of the most featureful 53parts of the package. 54 55```go 56 c, err := semver.NewConstraint(">= 1.2.3") 57 if err != nil { 58 // Handle constraint not being parseable. 59 } 60 61 v, _ := semver.NewVersion("1.3") 62 if err != nil { 63 // Handle version not being parseable. 64 } 65 // Check if the version meets the constraints. The a variable will be true. 66 a := c.Check(v) 67``` 68 69## Basic Comparisons 70 71There are two elements to the comparisons. First, a comparison string is a list 72of comma separated and comparisons. These are then separated by || separated or 73comparisons. For example, `">= 1.2, < 3.0.0 || >= 4.2.3"` is looking for a 74comparison that's greater than or equal to 1.2 and less than 3.0.0 or is 75greater than or equal to 4.2.3. 76 77The basic comparisons are: 78 79* `=`: equal (aliased to no operator) 80* `!=`: not equal 81* `>`: greater than 82* `<`: less than 83* `>=`: greater than or equal to 84* `<=`: less than or equal to 85 86## Working With Pre-release Versions 87 88Pre-releases, for those not familiar with them, are used for software releases 89prior to stable or generally available releases. Examples of pre-releases include 90development, alpha, beta, and release candidate releases. A pre-release may be 91a version such as `1.2.3-beta.1` while the stable release would be `1.2.3`. In the 92order of precidence, pre-releases come before their associated releases. In this 93example `1.2.3-beta.1 < 1.2.3`. 94 95According to the Semantic Version specification pre-releases may not be 96API compliant with their release counterpart. It says, 97 98> 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. 99 100SemVer comparisons without a pre-release comparator will skip pre-release versions. 101For example, `>=1.2.3` will skip pre-releases when looking at a list of releases 102while `>=1.2.3-0` will evaluate and find pre-releases. 103 104The reason for the `0` as a pre-release version in the example comparison is 105because pre-releases can only contain ASCII alphanumerics and hyphens (along with 106`.` separators), per the spec. Sorting happens in ASCII sort order, again per the spec. The lowest character is a `0` in ASCII sort order (see an [ASCII Table](http://www.asciitable.com/)) 107 108Understanding ASCII sort ordering is important because A-Z comes before a-z. That 109means `>=1.2.3-BETA` will return `1.2.3-alpha`. What you might expect from case 110sensitivity doesn't apply here. This is due to ASCII sort ordering which is what 111the spec specifies. 112 113## Hyphen Range Comparisons 114 115There are multiple methods to handle ranges and the first is hyphens ranges. 116These look like: 117 118* `1.2 - 1.4.5` which is equivalent to `>= 1.2, <= 1.4.5` 119* `2.3.4 - 4.5` which is equivalent to `>= 2.3.4, <= 4.5` 120 121## Wildcards In Comparisons 122 123The `x`, `X`, and `*` characters can be used as a wildcard character. This works 124for all comparison operators. When used on the `=` operator it falls 125back to the pack level comparison (see tilde below). For example, 126 127* `1.2.x` is equivalent to `>= 1.2.0, < 1.3.0` 128* `>= 1.2.x` is equivalent to `>= 1.2.0` 129* `<= 2.x` is equivalent to `< 3` 130* `*` is equivalent to `>= 0.0.0` 131 132## Tilde Range Comparisons (Patch) 133 134The tilde (`~`) comparison operator is for patch level ranges when a minor 135version is specified and major level changes when the minor number is missing. 136For example, 137 138* `~1.2.3` is equivalent to `>= 1.2.3, < 1.3.0` 139* `~1` is equivalent to `>= 1, < 2` 140* `~2.3` is equivalent to `>= 2.3, < 2.4` 141* `~1.2.x` is equivalent to `>= 1.2.0, < 1.3.0` 142* `~1.x` is equivalent to `>= 1, < 2` 143 144## Caret Range Comparisons (Major) 145 146The caret (`^`) comparison operator is for major level changes. This is useful 147when comparisons of API versions as a major change is API breaking. For example, 148 149* `^1.2.3` is equivalent to `>= 1.2.3, < 2.0.0` 150* `^0.0.1` is equivalent to `>= 0.0.1, < 1.0.0` 151* `^1.2.x` is equivalent to `>= 1.2.0, < 2.0.0` 152* `^2.3` is equivalent to `>= 2.3, < 3` 153* `^2.x` is equivalent to `>= 2.0.0, < 3` 154 155# Validation 156 157In addition to testing a version against a constraint, a version can be validated 158against a constraint. When validation fails a slice of errors containing why a 159version didn't meet the constraint is returned. For example, 160 161```go 162 c, err := semver.NewConstraint("<= 1.2.3, >= 1.4") 163 if err != nil { 164 // Handle constraint not being parseable. 165 } 166 167 v, _ := semver.NewVersion("1.3") 168 if err != nil { 169 // Handle version not being parseable. 170 } 171 172 // Validate a version against a constraint. 173 a, msgs := c.Validate(v) 174 // a is false 175 for _, m := range msgs { 176 fmt.Println(m) 177 178 // Loops over the errors which would read 179 // "1.3 is greater than 1.2.3" 180 // "1.3 is less than 1.4" 181 } 182``` 183 184# Fuzzing 185 186 [dvyukov/go-fuzz](https://github.com/dvyukov/go-fuzz) is used for fuzzing. 187 1881. `go-fuzz-build` 1892. `go-fuzz -workdir=fuzz` 190 191# Contribute 192 193If you find an issue or want to contribute please file an [issue](https://github.com/Masterminds/semver/issues) 194or [create a pull request](https://github.com/Masterminds/semver/pulls). 195