Repository files navigation

Thesemver package provides the ability to work withSemantic Versions in Go. Specifically it provides the ability to:

• Parse semantic versions
• Sort semantic versions
• Check if a semantic version fits within a set of constraints
• Optionally work with av prefix

Note, importgithub.com/Masterminds/semver/v3 to use the latest version.

There are three major versions fo thesemver package.

• 3.x.x is the stable and active version. This version is focused on constraintcompatibility for range handling in other tools from other languages. It hasa similar API to the v1 releases. The development of this version is on the masterbranch. The documentation for this version is below.
• 2.x was developed primarily fordep. There areno tagged releases and the development was performed by@sdboyer.There are API breaking changes from v1. This version lives on the2.x branch.
• 1.x.x is the original release. It is no longer maintained. You should use thev3 release instead. You can read the documentation for the 1.x.x releasehere.

There are two functions that can parse semantic versions. TheStrictNewVersionfunction only parses valid version 2 semantic versions as outlined in thespecification. TheNewVersion function attempts to coerce a version into asemantic version and parse it. For example, if there is a leading v or a versionlisted without all 3 parts (e.g.v1.2) it will attempt to coerce it into a validsemantic version (e.g., 1.2.0). In both cases aVersion object is returnedthat can be sorted, compared, and used in constraints.

When parsing a version an error is returned if there is an issue parsing theversion. For example,

v, err := semver.NewVersion("1.2.3-beta.1+build345")

The version object has methods to get the parts of the version, compare it toother versions, convert the version back into a string, and get the originalstring. Getting the original string is useful if the semantic version was coercedinto a valid form.

A set of versions can be sorted using thesort package from the standard library.For example,

raw:= []string{"1.2.3","1.0","1.3","2","0.4.2",}vs:=make([]*semver.Version,len(raw))fori,r:=rangeraw {v,err:=semver.NewVersion(r)iferr!=nil {t.Errorf("Error parsing version: %s",err)    }vs[i]=v}sort.Sort(semver.Collection(vs))

There are two methods for comparing versions. One uses comparison methods onVersion instances and the other usesConstraints. There are some importantdifferences to notes between these two methods of comparison.

1. When two versions are compared using functions such asCompare,LessThan,and others it will follow the specification and always include pre-releaseswithin the comparison. It will provide an answer that is valid with thecomparison section of the spec athttps://semver.org/#spec-item-11
2. When constraint checking is used for checks or validation it will follow adifferent set of rules that are common for ranges with tools like npm/jsand Rust/Cargo. This includes considering pre-releases to be invalid if theranges does not include one. If you want to have it include pre-releases asimple solution is to include-0 in your range.
3. Constraint ranges can have some complex rules including the shorthand use of~ and ^. For more details on those see the options below.

There are differences between the two methods or checking versions because thecomparison methods onVersion follow the specification while comparison rangesare not part of the specification. Different packages and tools have taken itupon themselves to come up with range rules. This has resulted in differences.For example, npm/js and Cargo/Rust follow similar patterns while PHP has adifferent pattern for ^. The comparison features in this package follow thenpm/js and Cargo/Rust lead because applications using it have followed similarpatters with their versions.

Checking a version against version constraints is one of the most featurefulparts of the package.

c,err:=semver.NewConstraint(">= 1.2.3")iferr!=nil {// Handle constraint not being parsable.}v,err:=semver.NewVersion("1.3")iferr!=nil {// Handle version not being parsable.}// Check if the version meets the constraints. The variable a will be true.a:=c.Check(v)

There are two elements to the comparisons. First, a comparison string is a listof space or comma separated AND comparisons. These are then separated by || (OR)comparisons. For example,">= 1.2 < 3.0.0 || >= 4.2.3" is looking for acomparison that's greater than or equal to 1.2 and less than 3.0.0 or isgreater than or equal to 4.2.3.

The basic comparisons are:

• =: equal (aliased to no operator)
• !=: not equal
• >: greater than
• <: less than
• >=: greater than or equal to
• <=: less than or equal to

Pre-releases, for those not familiar with them, are used for software releasesprior to stable or generally available releases. Examples of pre-releases includedevelopment, alpha, beta, and release candidate releases. A pre-release may bea version such as1.2.3-beta.1 while the stable release would be1.2.3. In theorder of precedence, pre-releases come before their associated releases. In thisexample1.2.3-beta.1 < 1.2.3.

According to the Semantic Version specification, pre-releases may not beAPI compliant with their release counterpart. It says,

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.

SemVer's comparisons using constraints without a pre-release comparator will skippre-release versions. For example,>=1.2.3 will skip pre-releases when lookingat a list of releases while>=1.2.3-0 will evaluate and find pre-releases.

The reason for the0 as a pre-release version in the example comparison isbecause pre-releases can only contain ASCII alphanumerics and hyphens (along with. separators), per the spec. Sorting happens in ASCII sort order, again per thespec. The lowest character is a0 in ASCII sort order(see anASCII Table)

Understanding ASCII sort ordering is important because A-Z comes before a-z. Thatmeans>=1.2.3-BETA will return1.2.3-alpha. What you might expect from casesensitivity doesn't apply here. This is due to ASCII sort ordering which is whatthe spec specifies.

There are multiple methods to handle ranges and the first is hyphens ranges.These look like:

• 1.2 - 1.4.5 which is equivalent to>= 1.2 <= 1.4.5
• 2.3.4 - 4.5 which is equivalent to>= 2.3.4 <= 4.5

Note that1.2-1.4.5 without whitespace is parsed completely differently; it'sparsed as a single constraint1.2.0 withprerelease1.4.5.

Thex,X, and* characters can be used as a wildcard character. This worksfor all comparison operators. When used on the= operator it fallsback to the patch level comparison (see tilde below). For example,

• 1.2.x is equivalent to>= 1.2.0, < 1.3.0
• >= 1.2.x is equivalent to>= 1.2.0
• <= 2.x is equivalent to< 3
• * is equivalent to>= 0.0.0

The tilde (~) comparison operator is for patch level ranges when a minorversion is specified and major level changes when the minor number is missing.For example,

• ~1.2.3 is equivalent to>= 1.2.3, < 1.3.0
• ~1 is equivalent to>= 1, < 2
• ~2.3 is equivalent to>= 2.3, < 2.4
• ~1.2.x is equivalent to>= 1.2.0, < 1.3.0
• ~1.x is equivalent to>= 1, < 2

The caret (^) comparison operator is for major level changes once a stable(1.0.0) release has occurred. Prior to a 1.0.0 release the minor versions actsas the API stability level. This is useful when comparisons of API versions as amajor change is API breaking. For example,

• ^1.2.3 is equivalent to>= 1.2.3, < 2.0.0
• ^1.2.x is equivalent to>= 1.2.0, < 2.0.0
• ^2.3 is equivalent to>= 2.3, < 3
• ^2.x is equivalent to>= 2.0.0, < 3
• ^0.2.3 is equivalent to>=0.2.3 <0.3.0
• ^0.2 is equivalent to>=0.2.0 <0.3.0
• ^0.0.3 is equivalent to>=0.0.3 <0.0.4
• ^0.0 is equivalent to>=0.0.0 <0.1.0
• ^0 is equivalent to>=0.0.0 <1.0.0

In addition to testing a version against a constraint, a version can be validatedagainst a constraint. When validation fails a slice of errors containing why aversion didn't meet the constraint is returned. For example,

c,err:=semver.NewConstraint("<= 1.2.3, >= 1.4")iferr!=nil {// Handle constraint not being parseable.}v,err:=semver.NewVersion("1.3")iferr!=nil {// Handle version not being parseable.}// Validate a version against a constraint.a,msgs:=c.Validate(v)// a is falsefor_,m:=rangemsgs {fmt.Println(m)// Loops over the errors which would read// "1.3 is greater than 1.2.3"// "1.3 is less than 1.4"}

If you find an issue or want to contribute please file anissueorcreate a pull request.

Security is an important consideration for this project. The project currentlyuses the following tools to help discover security issues:

• CodeQL
• gosec
• Daily Fuzz testing

If you believe you have found a security vulnerability you can privately discloseit through theGitHub security page.