mirror of https://github.com/nodejs/node.git
135 lines
9.9 KiB
HTML
135 lines
9.9 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<title>semver</title>
|
|
<meta http-equiv="content-type" value="text/html;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
|
|
|
|
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
|
|
|
|
Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | -d <dec>]
|
|
Test if version(s) satisfy the supplied range(s), and sort them.
|
|
|
|
Multiple versions or ranges may be supplied, unless increment
|
|
or decrement options are specified. In that case, only a single
|
|
version may be used, and it is incremented by the specified level
|
|
|
|
Program exits successfully if any valid version satisfies
|
|
all supplied ranges, and prints all satisfying versions.
|
|
|
|
If no versions are valid, or ranges are not satisfied,
|
|
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 v2.0.0 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>The following range styles are supported:</p>
|
|
|
|
<ul><li><code>1.2.3</code> A specific version. When nothing else will do. Note that
|
|
build metadata is still ignored, so <code>1.2.3+build2012</code> will satisfy
|
|
this range.</li><li><code>>1.2.3</code> Greater than a specific version.</li><li><code><1.2.3</code> Less than a specific version. If there is no prerelease
|
|
tag on the version range, then no prerelease version will be allowed
|
|
either, even though these are technically "less than".</li><li><code>>=1.2.3</code> Greater than or equal to. Note that prerelease versions
|
|
are NOT equal to their "normal" equivalents, so <code>1.2.3-beta</code> will
|
|
not satisfy this range, but <code>2.3.0-beta</code> will.</li><li><code><=1.2.3</code> Less than or equal to. In this case, prerelease versions
|
|
ARE allowed, so <code>1.2.3-beta</code> would satisfy.</li><li><code>1.2.3 - 2.3.4</code> := <code>>=1.2.3 <=2.3.4</code></li><li><code>~1.2.3</code> := <code>>=1.2.3-0 <1.3.0-0</code> "Reasonably close to 1.2.3". When
|
|
using tilde operators, prerelease versions are supported as well,
|
|
but a prerelease of the next significant digit will NOT be
|
|
satisfactory, so <code>1.3.0-beta</code> will not satisfy <code>~1.2.3</code>.</li><li><code>^1.2.3</code> := <code>>=1.2.3-0 <2.0.0-0</code> "Compatible with 1.2.3". When
|
|
using caret operators, anything from the specified version (including
|
|
prerelease) will be supported up to, but not including, the next
|
|
major version (or its prereleases). <code>1.5.1</code> will satisfy <code>^1.2.3</code>,
|
|
while <code>1.2.2</code> and <code>2.0.0-beta</code> will not.</li><li><code>^0.1.3</code> := <code>>=0.1.3-0 <0.2.0-0</code> "Compatible with 0.1.3". 0.x.x versions are
|
|
special: the first non-zero component indicates potentially breaking changes,
|
|
meaning the caret operator matches any version with the same first non-zero
|
|
component starting at the specified version.</li><li><code>^0.0.2</code> := <code>=0.0.2</code> "Only the version 0.0.2 is considered compatible"</li><li><code>~1.2</code> := <code>>=1.2.0-0 <1.3.0-0</code> "Any version starting with 1.2"</li><li><code>^1.2</code> := <code>>=1.2.0-0 <2.0.0-0</code> "Any version compatible with 1.2"</li><li><code>1.2.x</code> := <code>>=1.2.0-0 <1.3.0-0</code> "Any version starting with 1.2"</li><li><code>~1</code> := <code>>=1.0.0-0 <2.0.0-0</code> "Any version starting with 1"</li><li><code>^1</code> := <code>>=1.0.0-0 <2.0.0-0</code> "Any version compatible with 1"</li><li><code>1.x</code> := <code>>=1.0.0-0 <2.0.0-0</code> "Any version starting with 1"</li></ul>
|
|
|
|
<p>Ranges can be joined with either a space (which implies "and") or a
|
|
<code>||</code> (which implies "or").</p>
|
|
|
|
<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>valid(v): Return the parsed version, or null if it's not valid.</li><li>inc(v, release): Return the version incremented by the release type
|
|
(major, minor, patch, or prerelease), or null if it's not valid.</li></ul>
|
|
|
|
<h3 id="Comparison">Comparison</h3>
|
|
|
|
<ul><li>gt(v1, v2): <code>v1 > v2</code></li><li>gte(v1, v2): <code>v1 >= v2</code></li><li>lt(v1, v2): <code>v1 < v2</code></li><li>lte(v1, v2): <code>v1 <= v2</code></li><li>eq(v1, v2): <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>neq(v1, v2): <code>v1 != v2</code> The opposite of eq.</li><li>cmp(v1, comparator, v2): 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>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 Array.sort().</li><li>rcompare(v1, v2): The reverse of compare. Sorts an array of versions
|
|
in descending order when passed to Array.sort().</li></ul>
|
|
|
|
<h3 id="Ranges">Ranges</h3>
|
|
|
|
<ul><li>validRange(range): Return the valid range or null if it's not valid</li><li>satisfies(version, range): Return true if the version satisfies the
|
|
range.</li><li>maxSatisfying(versions, range): Return the highest version in the list
|
|
that satisfies the range, or null if none of them do.</li><li>gtr(version, range): Return true if version is greater than all the
|
|
versions possible in the range.</li><li>ltr(version, range): Return true if version is less than all the
|
|
versions possible in the range.</li><li>outside(version, range, hilo): 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 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.</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@1.4.9</p>
|
|
|