You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
329 lines
20 KiB
329 lines
20 KiB
<!doctype html>
|
|
<html>
|
|
<title>semver</title>
|
|
<meta charset="utf-8">
|
|
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
|
<link rel="canonical" href="https://www.npmjs.org/doc/misc/semver.html">
|
|
<script async=true src="../../static/toc.js"></script>
|
|
|
|
<body>
|
|
<div id="wrapper">
|
|
|
|
<h1><a href="../misc/semver.html">semver</a></h1> <p>The semantic versioner for npm</p>
|
|
<h2 id="usage">Usage</h2>
|
|
<pre><code>$ 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
|
|
</code></pre><p>As a command-line utility:</p>
|
|
<pre><code>$ 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.
|
|
</code></pre><h2 id="versions">Versions</h2>
|
|
<p>A "version" is described by the <code>v2.0.0</code> specification found at
|
|
<a href="http://semver.org/">http://semver.org/</a>.</p>
|
|
<p>A leading <code>"="</code> or <code>"v"</code> character is stripped off and ignored.</p>
|
|
<h2 id="ranges">Ranges</h2>
|
|
<p>A <code>version range</code> is a set of <code>comparators</code> which specify versions
|
|
that satisfy the range.</p>
|
|
<p>A <code>comparator</code> is composed of an <code>operator</code> and a <code>version</code>. The set
|
|
of primitive <code>operators</code> is:</p>
|
|
<ul>
|
|
<li><code><</code> Less than</li>
|
|
<li><code><=</code> Less than or equal to</li>
|
|
<li><code>></code> Greater than</li>
|
|
<li><code>>=</code> Greater than or equal to</li>
|
|
<li><code>=</code> Equal. If no operator is specified, then equality is assumed,
|
|
so this operator is optional, but MAY be included.</li>
|
|
</ul>
|
|
<p>For example, the comparator <code>>=1.2.7</code> would match the versions
|
|
<code>1.2.7</code>, <code>1.2.8</code>, <code>2.5.3</code>, and <code>1.3.9</code>, but not the versions <code>1.2.6</code>
|
|
or <code>1.1.0</code>.</p>
|
|
<p>Comparators can be joined by whitespace to form a <code>comparator set</code>,
|
|
which is satisfied by the <strong>intersection</strong> of all of the comparators
|
|
it includes.</p>
|
|
<p>A range is composed of one or more comparator sets, joined by <code>||</code>. A
|
|
version matches a range if and only if every comparator in at least
|
|
one of the <code>||</code>-separated comparator sets is satisfied by the version.</p>
|
|
<p>For example, the range <code>>=1.2.7 <1.3.0</code> would match the versions
|
|
<code>1.2.7</code>, <code>1.2.8</code>, and <code>1.2.99</code>, but not the versions <code>1.2.6</code>, <code>1.3.0</code>,
|
|
or <code>1.1.0</code>.</p>
|
|
<p>The range <code>1.2.7 || >=1.2.9 <2.0.0</code> would match the versions <code>1.2.7</code>,
|
|
<code>1.2.9</code>, and <code>1.4.6</code>, but not the versions <code>1.2.8</code> or <code>2.0.0</code>.</p>
|
|
<h3 id="prerelease-tags">Prerelease Tags</h3>
|
|
<p>If a version has a prerelease tag (for example, <code>1.2.3-alpha.3</code>) then
|
|
it will only be allowed to satisfy comparator sets if at least one
|
|
comparator with the same <code>[major, minor, patch]</code> tuple also has a
|
|
prerelease tag.</p>
|
|
<p>For example, the range <code>>1.2.3-alpha.3</code> would be allowed to match the
|
|
version <code>1.2.3-alpha.7</code>, but it would <em>not</em> be satisfied by
|
|
<code>3.4.5-alpha.9</code>, even though <code>3.4.5-alpha.9</code> is technically "greater
|
|
than" <code>1.2.3-alpha.3</code> according to the SemVer sort rules. The version
|
|
range only accepts prerelease tags on the <code>1.2.3</code> version. The
|
|
version <code>3.4.5</code> <em>would</em> satisfy the range, because it does not have a
|
|
prerelease flag, and <code>3.4.5</code> is greater than <code>1.2.3-alpha.7</code>.</p>
|
|
<p>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.</p>
|
|
<p>Second, a user who has opted into using a prerelease version has
|
|
clearly indicated the intent to use <em>that specific</em> set of
|
|
alpha/beta/rc versions. By including a prerelease tag in the range,
|
|
the user is indicating that they are aware of the risk. However, it
|
|
is still not appropriate to assume that they have opted into taking a
|
|
similar risk on the <em>next</em> set of prerelease versions.</p>
|
|
<h4 id="prerelease-identifiers">Prerelease Identifiers</h4>
|
|
<p>The method <code>.inc</code> takes an additional <code>identifier</code> string argument that
|
|
will append the value of the string as a prerelease identifier:</p>
|
|
<pre><code class="lang-javascript">> semver.inc('1.2.3', 'prerelease', 'beta')
|
|
'1.2.4-beta.0'
|
|
</code></pre>
|
|
<p>command-line example:</p>
|
|
<pre><code class="lang-shell">$ semver 1.2.3 -i prerelease --preid beta
|
|
1.2.4-beta.0
|
|
</code></pre>
|
|
<p>Which then can be used to increment further:</p>
|
|
<pre><code class="lang-shell">$ semver 1.2.4-beta.0 -i prerelease
|
|
1.2.4-beta.1
|
|
</code></pre>
|
|
<h3 id="advanced-range-syntax">Advanced Range Syntax</h3>
|
|
<p>Advanced range syntax desugars to primitive comparators in
|
|
deterministic ways.</p>
|
|
<p>Advanced ranges may be combined in the same way as primitive
|
|
comparators using white space or <code>||</code>.</p>
|
|
<h4 id="hyphen-ranges-x-y-z-a-b-c-">Hyphen Ranges <code>X.Y.Z - A.B.C</code></h4>
|
|
<p>Specifies an inclusive set.</p>
|
|
<ul>
|
|
<li><code>1.2.3 - 2.3.4</code> := <code>>=1.2.3 <=2.3.4</code></li>
|
|
</ul>
|
|
<p>If a partial version is provided as the first version in the inclusive
|
|
range, then the missing pieces are replaced with zeroes.</p>
|
|
<ul>
|
|
<li><code>1.2 - 2.3.4</code> := <code>>=1.2.0 <=2.3.4</code></li>
|
|
</ul>
|
|
<p>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 tuple are accepted, but nothing that would be greater than the
|
|
provided tuple parts.</p>
|
|
<ul>
|
|
<li><code>1.2.3 - 2.3</code> := <code>>=1.2.3 <2.4.0</code></li>
|
|
<li><code>1.2.3 - 2</code> := <code>>=1.2.3 <3.0.0</code></li>
|
|
</ul>
|
|
<h4 id="x-ranges-1-2-x-1-x-1-2-">X-Ranges <code>1.2.x</code> <code>1.X</code> <code>1.2.*</code> <code>*</code></h4>
|
|
<p>Any of <code>X</code>, <code>x</code>, or <code>*</code> may be used to "stand in" for one of the
|
|
numeric values in the <code>[major, minor, patch]</code> tuple.</p>
|
|
<ul>
|
|
<li><code>*</code> := <code>>=0.0.0</code> (Any version satisfies)</li>
|
|
<li><code>1.x</code> := <code>>=1.0.0 <2.0.0</code> (Matching major version)</li>
|
|
<li><code>1.2.x</code> := <code>>=1.2.0 <1.3.0</code> (Matching major and minor versions)</li>
|
|
</ul>
|
|
<p>A partial version range is treated as an X-Range, so the special
|
|
character is in fact optional.</p>
|
|
<ul>
|
|
<li><code>""</code> (empty string) := <code>*</code> := <code>>=0.0.0</code></li>
|
|
<li><code>1</code> := <code>1.x.x</code> := <code>>=1.0.0 <2.0.0</code></li>
|
|
<li><code>1.2</code> := <code>1.2.x</code> := <code>>=1.2.0 <1.3.0</code></li>
|
|
</ul>
|
|
<h4 id="tilde-ranges-1-2-3-1-2-1-">Tilde Ranges <code>~1.2.3</code> <code>~1.2</code> <code>~1</code></h4>
|
|
<p>Allows patch-level changes if a minor version is specified on the
|
|
comparator. Allows minor-level changes if not.</p>
|
|
<ul>
|
|
<li><code>~1.2.3</code> := <code>>=1.2.3 <1.(2+1).0</code> := <code>>=1.2.3 <1.3.0</code></li>
|
|
<li><code>~1.2</code> := <code>>=1.2.0 <1.(2+1).0</code> := <code>>=1.2.0 <1.3.0</code> (Same as <code>1.2.x</code>)</li>
|
|
<li><code>~1</code> := <code>>=1.0.0 <(1+1).0.0</code> := <code>>=1.0.0 <2.0.0</code> (Same as <code>1.x</code>)</li>
|
|
<li><code>~0.2.3</code> := <code>>=0.2.3 <0.(2+1).0</code> := <code>>=0.2.3 <0.3.0</code></li>
|
|
<li><code>~0.2</code> := <code>>=0.2.0 <0.(2+1).0</code> := <code>>=0.2.0 <0.3.0</code> (Same as <code>0.2.x</code>)</li>
|
|
<li><code>~0</code> := <code>>=0.0.0 <(0+1).0.0</code> := <code>>=0.0.0 <1.0.0</code> (Same as <code>0.x</code>)</li>
|
|
<li><code>~1.2.3-beta.2</code> := <code>>=1.2.3-beta.2 <1.3.0</code> Note that prereleases in
|
|
the <code>1.2.3</code> version will be allowed, if they are greater than or
|
|
equal to <code>beta.2</code>. So, <code>1.2.3-beta.4</code> would be allowed, but
|
|
<code>1.2.4-beta.2</code> would not, because it is a prerelease of a
|
|
different <code>[major, minor, patch]</code> tuple.</li>
|
|
</ul>
|
|
<h4 id="caret-ranges-1-2-3-0-2-5-0-0-4-">Caret Ranges <code>^1.2.3</code> <code>^0.2.5</code> <code>^0.0.4</code></h4>
|
|
<p>Allows changes that do not modify the left-most non-zero digit in the
|
|
<code>[major, minor, patch]</code> tuple. In other words, this allows patch and
|
|
minor updates for versions <code>1.0.0</code> and above, patch updates for
|
|
versions <code>0.X >=0.1.0</code>, and <em>no</em> updates for versions <code>0.0.X</code>.</p>
|
|
<p>Many authors treat a <code>0.x</code> version as if the <code>x</code> were the major
|
|
"breaking-change" indicator.</p>
|
|
<p>Caret ranges are ideal when an author may make breaking changes
|
|
between <code>0.2.4</code> and <code>0.3.0</code> releases, which is a common practice.
|
|
However, it presumes that there will <em>not</em> be breaking changes between
|
|
<code>0.2.4</code> and <code>0.2.5</code>. It allows for changes that are presumed to be
|
|
additive (but non-breaking), according to commonly observed practices.</p>
|
|
<ul>
|
|
<li><code>^1.2.3</code> := <code>>=1.2.3 <2.0.0</code></li>
|
|
<li><code>^0.2.3</code> := <code>>=0.2.3 <0.3.0</code></li>
|
|
<li><code>^0.0.3</code> := <code>>=0.0.3 <0.0.4</code></li>
|
|
<li><code>^1.2.3-beta.2</code> := <code>>=1.2.3-beta.2 <2.0.0</code> Note that prereleases in
|
|
the <code>1.2.3</code> version will be allowed, if they are greater than or
|
|
equal to <code>beta.2</code>. So, <code>1.2.3-beta.4</code> would be allowed, but
|
|
<code>1.2.4-beta.2</code> would not, because it is a prerelease of a
|
|
different <code>[major, minor, patch]</code> tuple.</li>
|
|
<li><code>^0.0.3-beta</code> := <code>>=0.0.3-beta <0.0.4</code> Note that prereleases in the
|
|
<code>0.0.3</code> version <em>only</em> will be allowed, if they are greater than or
|
|
equal to <code>beta</code>. So, <code>0.0.3-pr.2</code> would be allowed.</li>
|
|
</ul>
|
|
<p>When parsing caret ranges, a missing <code>patch</code> value desugars to the
|
|
number <code>0</code>, but will allow flexibility within that value, even if the
|
|
major and minor versions are both <code>0</code>.</p>
|
|
<ul>
|
|
<li><code>^1.2.x</code> := <code>>=1.2.0 <2.0.0</code></li>
|
|
<li><code>^0.0.x</code> := <code>>=0.0.0 <0.1.0</code></li>
|
|
<li><code>^0.0</code> := <code>>=0.0.0 <0.1.0</code></li>
|
|
</ul>
|
|
<p>A missing <code>minor</code> and <code>patch</code> values will desugar to zero, but also
|
|
allow flexibility within those values, even if the major version is
|
|
zero.</p>
|
|
<ul>
|
|
<li><code>^1.x</code> := <code>>=1.0.0 <2.0.0</code></li>
|
|
<li><code>^0.x</code> := <code>>=0.0.0 <1.0.0</code></li>
|
|
</ul>
|
|
<h3 id="range-grammar">Range Grammar</h3>
|
|
<p>Putting all this together, here is a Backus-Naur grammar for ranges,
|
|
for the benefit of parser authors:</p>
|
|
<pre><code class="lang-bnf">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]+
|
|
</code></pre>
|
|
<h2 id="functions">Functions</h2>
|
|
<p>All methods and classes take a final <code>loose</code> 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.</p>
|
|
<p>Strict-mode Comparators and Ranges will be strict about the SemVer
|
|
strings that they parse.</p>
|
|
<ul>
|
|
<li><code>valid(v)</code>: Return the parsed version, or null if it's not valid.</li>
|
|
<li><code>inc(v, release)</code>: Return the version incremented by the release
|
|
type (<code>major</code>, <code>premajor</code>, <code>minor</code>, <code>preminor</code>, <code>patch</code>,
|
|
<code>prepatch</code>, or <code>prerelease</code>), or null if it's not valid<ul>
|
|
<li><code>premajor</code> in one call will bump the version up to the next major
|
|
version and down to a prerelease of that major version.
|
|
<code>preminor</code>, and <code>prepatch</code> work the same way.</li>
|
|
<li>If called from a non-prerelease version, the <code>prerelease</code> will work the
|
|
same as <code>prepatch</code>. It increments the patch version, then makes a
|
|
prerelease. If the input version is already a prerelease it simply
|
|
increments it.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>prerelease(v)</code>: Returns an array of prerelease components, or null
|
|
if none exist. Example: <code>prerelease('1.2.3-alpha.1') -> ['alpha', 1]</code></li>
|
|
<li><code>major(v)</code>: Return the major version number.</li>
|
|
<li><code>minor(v)</code>: Return the minor version number.</li>
|
|
<li><code>patch(v)</code>: Return the patch version number.</li>
|
|
</ul>
|
|
<h3 id="comparison">Comparison</h3>
|
|
<ul>
|
|
<li><code>gt(v1, v2)</code>: <code>v1 > v2</code></li>
|
|
<li><code>gte(v1, v2)</code>: <code>v1 >= v2</code></li>
|
|
<li><code>lt(v1, v2)</code>: <code>v1 < v2</code></li>
|
|
<li><code>lte(v1, v2)</code>: <code>v1 <= v2</code></li>
|
|
<li><code>eq(v1, v2)</code>: <code>v1 == v2</code> This is true if they're logically equivalent,
|
|
even if they're not the exact same string. You already know how to
|
|
compare strings.</li>
|
|
<li><code>neq(v1, v2)</code>: <code>v1 != v2</code> The opposite of <code>eq</code>.</li>
|
|
<li><code>cmp(v1, comparator, v2)</code>: Pass in a comparison string, and it'll call
|
|
the corresponding function above. <code>"==="</code> and <code>"!=="</code> do simple
|
|
string comparison, but are included for completeness. Throws if an
|
|
invalid comparison string is provided.</li>
|
|
<li><code>compare(v1, v2)</code>: Return <code>0</code> if <code>v1 == v2</code>, or <code>1</code> if <code>v1</code> is greater, or <code>-1</code> if
|
|
<code>v2</code> is greater. Sorts in ascending order if passed to <code>Array.sort()</code>.</li>
|
|
<li><code>rcompare(v1, v2)</code>: The reverse of compare. Sorts an array of versions
|
|
in descending order when passed to <code>Array.sort()</code>.</li>
|
|
<li><code>diff(v1, v2)</code>: Returns difference between two versions by the release type
|
|
(<code>major</code>, <code>premajor</code>, <code>minor</code>, <code>preminor</code>, <code>patch</code>, <code>prepatch</code>, or <code>prerelease</code>),
|
|
or null if the versions are the same.</li>
|
|
</ul>
|
|
<h3 id="ranges">Ranges</h3>
|
|
<ul>
|
|
<li><code>validRange(range)</code>: Return the valid range or null if it's not valid</li>
|
|
<li><code>satisfies(version, range)</code>: Return true if the version satisfies the
|
|
range.</li>
|
|
<li><code>maxSatisfying(versions, range)</code>: Return the highest version in the list
|
|
that satisfies the range, or <code>null</code> if none of them do.</li>
|
|
<li><code>minSatisfying(versions, range)</code>: Return the lowest version in the list
|
|
that satisfies the range, or <code>null</code> if none of them do.</li>
|
|
<li><code>gtr(version, range)</code>: Return <code>true</code> if version is greater than all the
|
|
versions possible in the range.</li>
|
|
<li><code>ltr(version, range)</code>: Return <code>true</code> if version is less than all the
|
|
versions possible in the range.</li>
|
|
<li><code>outside(version, range, hilo)</code>: Return true if the version is outside
|
|
the bounds of the range in either the high or low direction. The
|
|
<code>hilo</code> argument must be either the string <code>'>'</code> or <code>'<'</code>. (This is
|
|
the function called by <code>gtr</code> and <code>ltr</code>.)</li>
|
|
</ul>
|
|
<p>Note that, since ranges may be non-contiguous, a version might not be
|
|
greater than a range, less than a range, <em>or</em> satisfy a range! For
|
|
example, the range <code>1.2 <1.2.9 || >2.0.0</code> would have a hole from <code>1.2.9</code>
|
|
until <code>2.0.0</code>, so the version <code>1.2.10</code> would not be greater than the
|
|
range (because <code>2.0.1</code> satisfies, which is higher), nor less than the
|
|
range (since <code>1.2.8</code> satisfies, which is lower), and it also does not
|
|
satisfy the range.</p>
|
|
<p>If you want to know if a version satisfies or does not satisfy a
|
|
range, use the <code>satisfies(version, range)</code> function.</p>
|
|
|
|
</div>
|
|
|
|
<table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
|
|
<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
|
|
<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr>
|
|
<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr>
|
|
<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
|
|
<tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
|
|
<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr>
|
|
<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr>
|
|
</table>
|
|
<p id="footer">semver — npm@4.4.1</p>
|
|
|