Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SEMVER(7)							     SEMVER(7)

NAME
       semver -	The semantic versioner for npm

Usage
	 $ npm install semver
	 $ node
	 var semver = require('semver')

	 semver.valid('1.2.3') // '1.2.3'
	 semver.valid('a.b.c') // null
	 semver.clean('	 =v1.2.3   ') // '1.2.3'
	 semver.satisfies('1.2.3', '1.x	|| >=2.5.0 || 5.0.0 - 7.2.3') // true
	 semver.gt('1.2.3', '9.8.7') //	false
	 semver.lt('1.2.3', '9.8.7') //	true

       As a command-line utility:

	 $ semver -h

	 SemVer	5.1.0

	 A JavaScript implementation of	the http://semver.org/ specification
	 Copyright Isaac Z. Schlueter

	 Usage:	semver [options] <version> [<version> [...]]
	 Prints	valid versions sorted by SemVer	precedence

	 Options:
	 -r --range <range>
		 Print versions	that match the specified range.

	 -i --increment	[<level>]
		 Increment a version by	the specified level.  Level can
		 be one	of: major, minor, patch, premajor, preminor,
		 prepatch, or prerelease.  Default level is 'patch'.
		 Only one version may be specified.

	 --preid <identifier>
		 Identifier to be used to prefix premajor, preminor,
		 prepatch or prerelease	version	increments.

	 -l --loose
		 Interpret versions and	ranges loosely

	 Program exits successfully if any valid version satisfies
	 all supplied ranges, and prints all satisfying	versions.

	 If no satisfying versions are found, then exits failure.

	 Versions are printed in ascending order, so supplying
	 multiple versions to the utility will just sort them.

Versions
       A   "version"  is  described  by	 the  v2.0.0  specification  found  at
       http://semver.org/.

       A leading "=" or	"v" character is stripped off and ignored.

Ranges
       A version range is a set	of comparators	which  specify	versions  that
       satisfy the range.

       A  comparator  is  composed  of	an operator and	a version.  The	set of
       primitive operators is:

       o < Less	than

       o <= Less than or equal to

       o > Greater than

       o >= Greater than or equal to

       o = Equal.  If no operator is specified,	then equality is  assumed,  so
	 this operator is optional, but	MAY be included.

       For  example,  the  comparator  >=1.2.7 would match the versions	1.2.7,
       1.2.8, 2.5.3, and 1.3.9,	but not	the versions 1.2.6 or 1.1.0.

       Comparators can be joined by whitespace to form a comparator set, which
       is satisfied by the intersection	of all of the comparators it includes.

       A  range	 is  composed of one or	more comparator	sets, joined by	||.  A
       version matches a range if and only if every comparator in at least one
       of the ||-separated comparator sets is satisfied	by the version.

       For  example,  the range	>=1.2.7	<1.3.0 would match the versions	1.2.7,
       1.2.8, and 1.2.99, but not the versions 1.2.6, 1.3.0, or	1.1.0.

       The range 1.2.7 || >=1.2.9  <2.0.0  would  match	 the  versions	1.2.7,
       1.2.9, and 1.4.6, but not the versions 1.2.8 or 2.0.0.

   Prerelease Tags
       If  a version has a prerelease tag (for example,	1.2.3-alpha.3) then it
       will only be allowed to satisfy comparator sets if at  least  one  com-
       parator with the	same [major, minor, patch] tuple also has a prerelease
       tag.

       For example, the	range >1.2.3-alpha.3 would be  allowed	to  match  the
       version	1.2.3-alpha.7, but it would not	be satisfied by	3.4.5-alpha.9,
       even though 3.4.5-alpha.9 is technically	"greater  than"	 1.2.3-alpha.3
       according  to  the  SemVer  sort	rules.	The version range only accepts
       prerelease tags on the 1.2.3 version.  The version 3.4.5	would  satisfy
       the  range,  because  it	 does not have a prerelease flag, and 3.4.5 is
       greater than 1.2.3-alpha.7.

       The purpose for this behavior is	twofold.  First,  prerelease  versions
       frequently  are updated very quickly, and contain many breaking changes
       that are	(by the	author's design) not yet fit for  public  consumption.
       Therefore, by default, they are excluded	from range matching semantics.

       Second,	a  user	 who  has  opted  into	using a	prerelease version has
       clearly indicated the intent to use that	specific set of	 alpha/beta/rc
       versions.   By including	a prerelease tag in the	range, the user	is in-
       dicating	that they are aware of the risk.  However, it is still not ap-
       propriate  to assume that they have opted into taking a similar risk on
       the next	set of prerelease versions.

   Prerelease Identifiers
       The method .inc takes an	additional  identifier	string	argument  that
       will append the value of	the string as a	prerelease identifier:

	 > semver.inc('1.2.3', 'prerelease', 'beta')
	 '1.2.4-beta.0'

       command-line example:

	 $ semver 1.2.3	-i prerelease --preid beta
	 1.2.4-beta.0

       Which then can be used to increment further:

	 $ semver 1.2.4-beta.0 -i prerelease
	 1.2.4-beta.1

   Advanced Range Syntax
       Advanced	 range syntax desugars to primitive comparators	in determinis-
       tic ways.

       Advanced	ranges may be combined in the same way as  primitive  compara-
       tors using white	space or ||.

   Hyphen Ranges X.Y.Z - A.B.C
       Specifies an inclusive set.

       o 1.2.3 - 2.3.4 := >=1.2.3 <=2.3.4

       If  a partial version is	provided as the	first version in the inclusive
       range, then the missing pieces are replaced with	zeroes.

       o 1.2 - 2.3.4 :=	>=1.2.0	<=2.3.4

       If a partial version is provided	as the second version in the inclusive
       range,  then all	versions that start with the supplied parts of the tu-
       ple are accepted, but nothing that would	be greater than	 the  provided
       tuple parts.

       o 1.2.3 - 2.3 :=	>=1.2.3	<2.4.0

       o 1.2.3 - 2 := >=1.2.3 <3.0.0

   X-Ranges 1.2.x 1.X 1.2.* *
       Any of X, x, or * may be	used to	"stand in" for one of the numeric val-
       ues in the [major, minor, patch]	tuple.

       o * := >=0.0.0 (Any version satisfies)

       o 1.x :=	>=1.0.0	<2.0.0 (Matching major version)

       o 1.2.x := >=1.2.0 <1.3.0 (Matching major and minor versions)

       A partial version range is treated as an	X-Range, so the	special	 char-
       acter is	in fact	optional.

       o "" (empty string) := *	:= >=0.0.0

       o 1 := 1.x.x := >=1.0.0 <2.0.0

       o 1.2 :=	1.2.x := >=1.2.0 <1.3.0

   Tilde Ranges	~1.2.3 ~1.2 ~1
       Allows  patch-level changes if a	minor version is specified on the com-
       parator.	 Allows	minor-level changes if not.

       o ~1.2.3	:= >=1.2.3 <1.(2+1).0 := >=1.2.3 <1.3.0

       o ~1.2 := >=1.2.0 <1.(2+1).0 := >=1.2.0 <1.3.0 (Same as 1.2.x)

       o ~1 := >=1.0.0 <(1+1).0.0 := >=1.0.0 <2.0.0 (Same as 1.x)

       o ~0.2.3	:= >=0.2.3 <0.(2+1).0 := >=0.2.3 <0.3.0

       o ~0.2 := >=0.2.0 <0.(2+1).0 := >=0.2.0 <0.3.0 (Same as 0.2.x)

       o ~0 := >=0.0.0 <(0+1).0.0 := >=0.0.0 <1.0.0 (Same as 0.x)

       o ~1.2.3-beta.2 := >=1.2.3-beta.2 <1.3.0	Note that prereleases  in  the
	 1.2.3	version	 will be allowed, if they are greater than or equal to
	 beta.2.  So, 1.2.3-beta.4 would be allowed,  but  1.2.4-beta.2	 would
	 not,  because it is a prerelease of a different [major, minor,	patch]
	 tuple.

   Caret Ranges	^1.2.3 ^0.2.5 ^0.0.4
       Allows changes that do not modify the left-most non-zero	digit  in  the
       [major, minor, patch] tuple.  In	other words, this allows patch and mi-
       nor updates for versions	1.0.0 and above, patch	updates	 for  versions
       0.X >=0.1.0, and	no updates for versions	0.0.X.

       Many  authors  treat  a	0.x version as if the x	were the major "break-
       ing-change" indicator.

       Caret ranges are	ideal when an author may make breaking changes between
       0.2.4 and 0.3.0 releases, which is a common practice.  However, it pre-
       sumes that there	will not be breaking changes between 0.2.4 and	0.2.5.
       It  allows for changes that are presumed	to be additive (but non-break-
       ing), according to commonly observed practices.

       o ^1.2.3	:= >=1.2.3 <2.0.0

       o ^0.2.3	:= >=0.2.3 <0.3.0

       o ^0.0.3	:= >=0.0.3 <0.0.4

       o ^1.2.3-beta.2 := >=1.2.3-beta.2 <2.0.0	Note that prereleases  in  the
	 1.2.3	version	 will be allowed, if they are greater than or equal to
	 beta.2.  So, 1.2.3-beta.4 would be allowed,  but  1.2.4-beta.2	 would
	 not,  because it is a prerelease of a different [major, minor,	patch]
	 tuple.

       o ^0.0.3-beta :=	>=0.0.3-beta <0.0.4   Note  that  prereleases  in  the
	 0.0.3 version only will be allowed, if	they are greater than or equal
	 to beta.  So, 0.0.3-pr.2 would	be allowed.

       When parsing caret ranges, a missing patch value	desugars to the	number
       0,  but will allow flexibility within that value, even if the major and
       minor versions are both 0.

       o ^1.2.x	:= >=1.2.0 <2.0.0

       o ^0.0.x	:= >=0.0.0 <0.1.0

       o ^0.0 := >=0.0.0 <0.1.0

       A missing minor and patch values	will desugar to	zero, but  also	 allow
       flexibility within those	values,	even if	the major version is zero.

       o ^1.x := >=1.0.0 <2.0.0

       o ^0.x := >=0.0.0 <1.0.0

   Range Grammar
       Putting	all  this  together, here is a Backus-Naur grammar for ranges,
       for the benefit of parser authors:

	 range-set  ::=	range (	logical-or range ) *
	 logical-or ::=	( ' ' )	* '||' ( ' ' ) *
	 range	    ::=	hyphen | simple	( ' ' simple ) * | ''
	 hyphen	    ::=	partial	' - ' partial
	 simple	    ::=	primitive | partial | tilde | caret
	 primitive  ::=	( '<' |	'>' | '>=' | '<=' | '='	| ) partial
	 partial    ::=	xr ( '.' xr ( '.' xr qualifier ? )? )?
	 xr	    ::=	'x' | 'X' | '*'	| nr
	 nr	    ::=	'0' | ['1'-'9']	( ['0'-'9'] ) *
	 tilde	    ::=	'~' partial
	 caret	    ::=	'^' partial
	 qualifier  ::=	( '-' pre )? ( '+' build )?
	 pre	    ::=	parts
	 build	    ::=	parts
	 parts	    ::=	part ( '.' part	) *
	 part	    ::=	nr | [-0-9A-Za-z]+

Functions
       All methods and classes take a final loose boolean  argument  that,  if
       true, will be more forgiving about not-quite-valid semver strings.  The
       resulting output	will always be 100% strict, of course.

       Strict-mode Comparators and Ranges will	be  strict  about  the	SemVer
       strings that they parse.

       o valid(v): Return the parsed version, or null if it's not valid.

       o inc(v,	 release):  Return the version incremented by the release type
	 (major,   premajor, minor, preminor, patch, prepatch, or prerelease),
	 or null if it's not valid

       o premajor  in one call will bump the version up	to the next major ver-
	 sion and down to a prerelease of that major version.	preminor,  and
	 prepatch work the same	way.

       o If called from	a non-prerelease version, the prerelease will work the
	 same as prepatch. It increments the patch version, then makes a  pre-
	 release.  If  the input version is already a prerelease it simply in-
	 crements it.

       o prerelease(v):	Returns	an array of prerelease components, or null  if
	 none exist. Example: prerelease('1.2.3-alpha.1') -> ['alpha', 1]

       o major(v): Return the major version number.

       o minor(v): Return the minor version number.

       o patch(v): Return the patch version number.

   Comparison
       o gt(v1,	v2): v1	> v2

       o gte(v1, v2): v1 >= v2

       o lt(v1,	v2): v1	< v2

       o lte(v1, v2): v1 <= v2

       o eq(v1,	 v2):  v1  == v2 This is true if they're logically equivalent,
	 even if they're not the exact same string.  You already know  how  to
	 compare strings.

       o neq(v1, v2): v1 != v2 The opposite of eq.

       o cmp(v1,  comparator, v2): Pass	in a comparison	string,	and it'll call
	 the corresponding function above.  "===" and "!==" do	simple	string
	 comparison,  but are included for completeness.  Throws if an invalid
	 comparison string is provided.

       o compare(v1, v2): Return 0 if v1 == v2,	or 1 if	v1 is greater,	or  -1
	 if  v2	 is  greater.	Sorts  in  ascending  order  if	 passed	to Ar-
	 ray.sort().

       o rcompare(v1, v2): The reverse of compare.  Sorts an array of versions
	 in descending order when passed to Array.sort().

       o diff(v1,  v2):	Returns	difference between two versions	by the release
	 type (major, premajor,	minor, preminor, patch,	 prepatch,  or	prere-
	 lease), or null if the	versions are the same.

   Ranges
       o validRange(range): Return the valid range or null if it's not valid

       o satisfies(version,  range):  Return true if the version satisfies the
	 range.

       o maxSatisfying(versions, range): Return	the  highest  version  in  the
	 list that satisfies the range,	or null	if none	of them	do.

       o minSatisfying(versions, range): Return	the lowest version in the list
	 that satisfies	the range, or null if none of them do.

       o gtr(version, range): Return true if version is	greater	than  all  the
	 versions possible in the range.

       o ltr(version, range): Return true if version is	less than all the ver-
	 sions possible	in the range.

       o outside(version, range, hilo):	Return true if the version is  outside
	 the  bounds  of  the  range in	either the high	or low direction.  The
	 hilo argument must be either the string '>' or	 '<'.	(This  is  the
	 function called by gtr	and ltr.)

       Note  that,  since ranges may be	non-contiguous,	a version might	not be
       greater than a range, less than a range,	or satisfy a range!  For exam-
       ple,  the range 1.2 <1.2.9 || >2.0.0 would have a hole from 1.2.9 until
       2.0.0, so the version 1.2.10 would not be greater than the  range  (be-
       cause 2.0.1 satisfies, which is higher),	nor less than the range	(since
       1.2.8 satisfies,	which is lower), and it	 also  does  not  satisfy  the
       range.

       If you want to know if a	version	satisfies or does not satisfy a	range,
       use the satisfies(version, range) function.

				   June	2017			     SEMVER(7)

NAME | Usage | Versions | Ranges | Functions

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=semver&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help