|
|
- <!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="install">Install</h2>
- <pre><code class="language-bash">npm install --save semver
- `</code></pre>
- <h2 id="usage">Usage</h2>
- <p>As a node module:</p>
- <pre><code class="language-js">const 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
- semver.valid(semver.coerce('v2')) // '2.0.0'
- semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'</code></pre>
- <p>As a command-line utility:</p>
- <pre><code>$ semver -h
-
- SemVer 5.3.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
-
- -c --coerce
- Coerce a string into SemVer if possible
- (does not imply --loose)
-
- 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="language-javascript">semver.inc('1.2.3', 'prerelease', 'beta')
- // '1.2.4-beta.0'</code></pre>
- <p>command-line example:</p>
- <pre><code class="language-bash">$ 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="language-bash">$ 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="language-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>
- <li><code>intersects(r1, r2, loose)</code>: Return true if the two supplied ranges
- or comparators intersect.</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="comparators">Comparators</h3>
- <ul>
- <li><code>intersects(comparator)</code>: Return true if the comparators intersect</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>
- <li><code>intersects(range)</code>: Return true if any of the ranges comparators intersect</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>
- <h3 id="coercion">Coercion</h3>
- <ul>
- <li><code>coerce(version)</code>: Coerces a string to semver if possible</li>
- </ul>
- <p>This aims to provide a very forgiving translation of a non-semver
- string to semver. It looks for the first digit in a string, and
- consumes all remaining characters which satisfy at least a partial semver
- (e.g., <code>1</code>, <code>1.2</code>, <code>1.2.3</code>) up to the max permitted length (256 characters).
- Longer versions are simply truncated (<code>4.6.3.9.2-alpha2</code> becomes <code>4.6.3</code>).
- All surrounding text is simply ignored (<code>v3.4 replaces v3.3.1</code> becomes <code>3.4.0</code>).
- Only text which lacks digits will fail coercion (<code>version one</code> is not valid).
- The maximum length for any semver component considered for coercion is 16 characters;
- longer components will be ignored (<code>10000000000000000.4.7.4</code> becomes <code>4.7.4</code>).
- The maximum value for any semver component is <code>Integer.MAX_SAFE_INTEGER || (2**53 - 1)</code>;
- higher value components are invalid (<code>9999999999999999.4.7.4</code> is likely invalid).</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@6.4.1</p>
-
|
