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 14## Parsing Semantic Versions 15 16To parse a semantic version use the `NewVersion` function. For example, 17 18```go 19 v, err := semver.NewVersion("1.2.3-beta.1+build345") 20``` 21 22If there is an error the version wasn't parseable. The version object has methods 23to get the parts of the version, compare it to other versions, convert the 24version back into a string, and get the original string. For more details 25please see the [documentation](https://godoc.org/github.com/Masterminds/semver). 26 27## Sorting Semantic Versions 28 29A set of versions can be sorted using the [`sort`](https://golang.org/pkg/sort/) 30package from the standard library. For example, 31 32```go 33 raw := []string{"1.2.3", "1.0", "1.3", "2", "0.4.2",} 34 vs := make([]*semver.Version, len(raw)) 35 for i, r := range raw { 36 v, err := semver.NewVersion(r) 37 if err != nil { 38 t.Errorf("Error parsing version: %s", err) 39 } 40 41 vs[i] = v 42 } 43 44 sort.Sort(semver.Collection(vs)) 45``` 46 47## Checking Version Constraints 48 49Checking a version against version constraints is one of the most featureful 50parts of the package. 51 52```go 53 c, err := semver.NewConstraint(">= 1.2.3") 54 if err != nil { 55 // Handle constraint not being parseable. 56 } 57 58 v, _ := semver.NewVersion("1.3") 59 if err != nil { 60 // Handle version not being parseable. 61 } 62 // Check if the version meets the constraints. The a variable will be true. 63 a := c.Check(v) 64``` 65 66## Basic Comparisons 67 68There are two elements to the comparisons. First, a comparison string is a list 69of comma separated and comparisons. These are then separated by || separated or 70comparisons. For example, `">= 1.2, < 3.0.0 || >= 4.2.3"` is looking for a 71comparison that's greater than or equal to 1.2 and less than 3.0.0 or is 72greater than or equal to 4.2.3. 73 74The basic comparisons are: 75 76* `=`: equal (aliased to no operator) 77* `!=`: not equal 78* `>`: greater than 79* `<`: less than 80* `>=`: greater than or equal to 81* `<=`: less than or equal to 82 83_Note, according to the Semantic Version specification pre-releases may not be 84API compliant with their release counterpart. It says,_ 85 86> _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._ 87 88_SemVer comparisons without a pre-release value will skip pre-release versions. 89For example, `>1.2.3` will skip pre-releases when looking at a list of values 90while `>1.2.3-alpha.1` will evaluate pre-releases._ 91 92## Hyphen Range Comparisons 93 94There are multiple methods to handle ranges and the first is hyphens ranges. 95These look like: 96 97* `1.2 - 1.4.5` which is equivalent to `>= 1.2, <= 1.4.5` 98* `2.3.4 - 4.5` which is equivalent to `>= 2.3.4, <= 4.5` 99 100## Wildcards In Comparisons 101 102The `x`, `X`, and `*` characters can be used as a wildcard character. This works 103for all comparison operators. When used on the `=` operator it falls 104back to the pack level comparison (see tilde below). For example, 105 106* `1.2.x` is equivalent to `>= 1.2.0, < 1.3.0` 107* `>= 1.2.x` is equivalent to `>= 1.2.0` 108* `<= 2.x` is equivalent to `<= 3` 109* `*` is equivalent to `>= 0.0.0` 110 111## Tilde Range Comparisons (Patch) 112 113The tilde (`~`) comparison operator is for patch level ranges when a minor 114version is specified and major level changes when the minor number is missing. 115For example, 116 117* `~1.2.3` is equivalent to `>= 1.2.3, < 1.3.0` 118* `~1` is equivalent to `>= 1, < 2` 119* `~2.3` is equivalent to `>= 2.3, < 2.4` 120* `~1.2.x` is equivalent to `>= 1.2.0, < 1.3.0` 121* `~1.x` is equivalent to `>= 1, < 2` 122 123## Caret Range Comparisons (Major) 124 125The caret (`^`) comparison operator is for major level changes. This is useful 126when comparisons of API versions as a major change is API breaking. For example, 127 128* `^1.2.3` is equivalent to `>= 1.2.3, < 2.0.0` 129* `^1.2.x` is equivalent to `>= 1.2.0, < 2.0.0` 130* `^2.3` is equivalent to `>= 2.3, < 3` 131* `^2.x` is equivalent to `>= 2.0.0, < 3` 132 133# Validation 134 135In addition to testing a version against a constraint, a version can be validated 136against a constraint. When validation fails a slice of errors containing why a 137version didn't meet the constraint is returned. For example, 138 139```go 140 c, err := semver.NewConstraint("<= 1.2.3, >= 1.4") 141 if err != nil { 142 // Handle constraint not being parseable. 143 } 144 145 v, _ := semver.NewVersion("1.3") 146 if err != nil { 147 // Handle version not being parseable. 148 } 149 150 // Validate a version against a constraint. 151 a, msgs := c.Validate(v) 152 // a is false 153 for _, m := range msgs { 154 fmt.Println(m) 155 156 // Loops over the errors which would read 157 // "1.3 is greater than 1.2.3" 158 // "1.3 is less than 1.4" 159 } 160``` 161 162# Contribute 163 164If you find an issue or want to contribute please file an [issue](https://github.com/Masterminds/semver/issues) 165or [create a pull request](https://github.com/Masterminds/semver/pulls). 166