1 semver(1) -- The semantic versioner for npm
2 ===========================================
8 var semver = require('semver')
10 semver.valid('1.2.3') // '1.2.3'
11 semver.valid('a.b.c') // null
12 semver.clean(' =v1.2.3 ') // '1.2.3'
13 semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
14 semver.gt('1.2.3', '9.8.7') // false
15 semver.lt('1.2.3', '9.8.7') // true
17 As a command-line utility:
23 A JavaScript implementation of the http://semver.org/ specification
24 Copyright Isaac Z. Schlueter
26 Usage: semver [options] <version> [<version> [...]]
27 Prints valid versions sorted by SemVer precedence
31 Print versions that match the specified range.
33 -i --increment [<level>]
34 Increment a version by the specified level. Level can
35 be one of: major, minor, patch, premajor, preminor,
36 prepatch, or prerelease. Default level is 'patch'.
37 Only one version may be specified.
40 Identifier to be used to prefix premajor, preminor,
41 prepatch or prerelease version increments.
44 Interpret versions and ranges loosely
46 Program exits successfully if any valid version satisfies
47 all supplied ranges, and prints all satisfying versions.
49 If no satisfying versions are found, then exits failure.
51 Versions are printed in ascending order, so supplying
52 multiple versions to the utility will just sort them.
56 A "version" is described by the `v2.0.0` specification found at
59 A leading `"="` or `"v"` character is stripped off and ignored.
63 A `version range` is a set of `comparators` which specify versions
64 that satisfy the range.
66 A `comparator` is composed of an `operator` and a `version`. The set
67 of primitive `operators` is:
70 * `<=` Less than or equal to
72 * `>=` Greater than or equal to
73 * `=` Equal. If no operator is specified, then equality is assumed,
74 so this operator is optional, but MAY be included.
76 For example, the comparator `>=1.2.7` would match the versions
77 `1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
80 Comparators can be joined by whitespace to form a `comparator set`,
81 which is satisfied by the **intersection** of all of the comparators
84 A range is composed of one or more comparator sets, joined by `||`. A
85 version matches a range if and only if every comparator in at least
86 one of the `||`-separated comparator sets is satisfied by the version.
88 For example, the range `>=1.2.7 <1.3.0` would match the versions
89 `1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
92 The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
93 `1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
97 If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
98 it will only be allowed to satisfy comparator sets if at least one
99 comparator with the same `[major, minor, patch]` tuple also has a
102 For example, the range `>1.2.3-alpha.3` would be allowed to match the
103 version `1.2.3-alpha.7`, but it would *not* be satisfied by
104 `3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
105 than" `1.2.3-alpha.3` according to the SemVer sort rules. The version
106 range only accepts prerelease tags on the `1.2.3` version. The
107 version `3.4.5` *would* satisfy the range, because it does not have a
108 prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
110 The purpose for this behavior is twofold. First, prerelease versions
111 frequently are updated very quickly, and contain many breaking changes
112 that are (by the author's design) not yet fit for public consumption.
113 Therefore, by default, they are excluded from range matching
116 Second, a user who has opted into using a prerelease version has
117 clearly indicated the intent to use *that specific* set of
118 alpha/beta/rc versions. By including a prerelease tag in the range,
119 the user is indicating that they are aware of the risk. However, it
120 is still not appropriate to assume that they have opted into taking a
121 similar risk on the *next* set of prerelease versions.
123 #### Prerelease Identifiers
125 The method `.inc` takes an additional `identifier` string argument that
126 will append the value of the string as a prerelease identifier:
129 > semver.inc('1.2.3', 'prerelease', 'beta')
133 command-line example:
136 $ semver 1.2.3 -i prerelease --preid beta
140 Which then can be used to increment further:
143 $ semver 1.2.4-beta.0 -i prerelease
147 ### Advanced Range Syntax
149 Advanced range syntax desugars to primitive comparators in
152 Advanced ranges may be combined in the same way as primitive
153 comparators using white space or `||`.
155 #### Hyphen Ranges `X.Y.Z - A.B.C`
157 Specifies an inclusive set.
159 * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
161 If a partial version is provided as the first version in the inclusive
162 range, then the missing pieces are replaced with zeroes.
164 * `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
166 If a partial version is provided as the second version in the
167 inclusive range, then all versions that start with the supplied parts
168 of the tuple are accepted, but nothing that would be greater than the
169 provided tuple parts.
171 * `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
172 * `1.2.3 - 2` := `>=1.2.3 <3.0.0`
174 #### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
176 Any of `X`, `x`, or `*` may be used to "stand in" for one of the
177 numeric values in the `[major, minor, patch]` tuple.
179 * `*` := `>=0.0.0` (Any version satisfies)
180 * `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
181 * `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
183 A partial version range is treated as an X-Range, so the special
184 character is in fact optional.
186 * `""` (empty string) := `*` := `>=0.0.0`
187 * `1` := `1.x.x` := `>=1.0.0 <2.0.0`
188 * `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
190 #### Tilde Ranges `~1.2.3` `~1.2` `~1`
192 Allows patch-level changes if a minor version is specified on the
193 comparator. Allows minor-level changes if not.
195 * `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
196 * `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
197 * `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
198 * `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
199 * `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
200 * `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
201 * `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
202 the `1.2.3` version will be allowed, if they are greater than or
203 equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
204 `1.2.4-beta.2` would not, because it is a prerelease of a
205 different `[major, minor, patch]` tuple.
207 #### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
209 Allows changes that do not modify the left-most non-zero digit in the
210 `[major, minor, patch]` tuple. In other words, this allows patch and
211 minor updates for versions `1.0.0` and above, patch updates for
212 versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
214 Many authors treat a `0.x` version as if the `x` were the major
215 "breaking-change" indicator.
217 Caret ranges are ideal when an author may make breaking changes
218 between `0.2.4` and `0.3.0` releases, which is a common practice.
219 However, it presumes that there will *not* be breaking changes between
220 `0.2.4` and `0.2.5`. It allows for changes that are presumed to be
221 additive (but non-breaking), according to commonly observed practices.
223 * `^1.2.3` := `>=1.2.3 <2.0.0`
224 * `^0.2.3` := `>=0.2.3 <0.3.0`
225 * `^0.0.3` := `>=0.0.3 <0.0.4`
226 * `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
227 the `1.2.3` version will be allowed, if they are greater than or
228 equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
229 `1.2.4-beta.2` would not, because it is a prerelease of a
230 different `[major, minor, patch]` tuple.
231 * `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the
232 `0.0.3` version *only* will be allowed, if they are greater than or
233 equal to `beta`. So, `0.0.3-pr.2` would be allowed.
235 When parsing caret ranges, a missing `patch` value desugars to the
236 number `0`, but will allow flexibility within that value, even if the
237 major and minor versions are both `0`.
239 * `^1.2.x` := `>=1.2.0 <2.0.0`
240 * `^0.0.x` := `>=0.0.0 <0.1.0`
241 * `^0.0` := `>=0.0.0 <0.1.0`
243 A missing `minor` and `patch` values will desugar to zero, but also
244 allow flexibility within those values, even if the major version is
247 * `^1.x` := `>=1.0.0 <2.0.0`
248 * `^0.x` := `>=0.0.0 <1.0.0`
252 Putting all this together, here is a Backus-Naur grammar for ranges,
253 for the benefit of parser authors:
256 range-set ::= range ( logical-or range ) *
257 logical-or ::= ( ' ' ) * '||' ( ' ' ) *
258 range ::= hyphen | simple ( ' ' simple ) * | ''
259 hyphen ::= partial ' - ' partial
260 simple ::= primitive | partial | tilde | caret
261 primitive ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
262 partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
263 xr ::= 'x' | 'X' | '*' | nr
264 nr ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
265 tilde ::= '~' partial
266 caret ::= '^' partial
267 qualifier ::= ( '-' pre )? ( '+' build )?
270 parts ::= part ( '.' part ) *
271 part ::= nr | [-0-9A-Za-z]+
276 All methods and classes take a final `loose` boolean argument that, if
277 true, will be more forgiving about not-quite-valid semver strings.
278 The resulting output will always be 100% strict, of course.
280 Strict-mode Comparators and Ranges will be strict about the SemVer
281 strings that they parse.
283 * `valid(v)`: Return the parsed version, or null if it's not valid.
284 * `inc(v, release)`: Return the version incremented by the release
285 type (`major`, `premajor`, `minor`, `preminor`, `patch`,
286 `prepatch`, or `prerelease`), or null if it's not valid
287 * `premajor` in one call will bump the version up to the next major
288 version and down to a prerelease of that major version.
289 `preminor`, and `prepatch` work the same way.
290 * If called from a non-prerelease version, the `prerelease` will work the
291 same as `prepatch`. It increments the patch version, then makes a
292 prerelease. If the input version is already a prerelease it simply
294 * `prerelease(v)`: Returns an array of prerelease components, or null
295 if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
296 * `major(v)`: Return the major version number.
297 * `minor(v)`: Return the minor version number.
298 * `patch(v)`: Return the patch version number.
302 * `gt(v1, v2)`: `v1 > v2`
303 * `gte(v1, v2)`: `v1 >= v2`
304 * `lt(v1, v2)`: `v1 < v2`
305 * `lte(v1, v2)`: `v1 <= v2`
306 * `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
307 even if they're not the exact same string. You already know how to
309 * `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
310 * `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
311 the corresponding function above. `"==="` and `"!=="` do simple
312 string comparison, but are included for completeness. Throws if an
313 invalid comparison string is provided.
314 * `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
315 `v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
316 * `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions
317 in descending order when passed to `Array.sort()`.
318 * `diff(v1, v2)`: Returns difference between two versions by the release type
319 (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
320 or null if the versions are the same.
325 * `validRange(range)`: Return the valid range or null if it's not valid
326 * `satisfies(version, range)`: Return true if the version satisfies the
328 * `maxSatisfying(versions, range)`: Return the highest version in the list
329 that satisfies the range, or `null` if none of them do.
330 * `minSatisfying(versions, range)`: Return the lowest version in the list
331 that satisfies the range, or `null` if none of them do.
332 * `gtr(version, range)`: Return `true` if version is greater than all the
333 versions possible in the range.
334 * `ltr(version, range)`: Return `true` if version is less than all the
335 versions possible in the range.
336 * `outside(version, range, hilo)`: Return true if the version is outside
337 the bounds of the range in either the high or low direction. The
338 `hilo` argument must be either the string `'>'` or `'<'`. (This is
339 the function called by `gtr` and `ltr`.)
341 Note that, since ranges may be non-contiguous, a version might not be
342 greater than a range, less than a range, *or* satisfy a range! For
343 example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
344 until `2.0.0`, so the version `1.2.10` would not be greater than the
345 range (because `2.0.1` satisfies, which is higher), nor less than the
346 range (since `1.2.8` satisfies, which is lower), and it also does not
349 If you want to know if a version satisfies or does not satisfy a
350 range, use the `satisfies(version, range)` function.