| <!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> | --preid <identifier> | -l | -rv] |
| Test if version(s) satisfy the supplied range(s), and sort them. |
| |
| Multiple versions or ranges may be supplied, unless increment |
| option is 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 <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>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>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@2.15.8</p> |
| |