1 semver(1) -- The semantic versioner for npm
2 ===========================================
8 semver.valid('1.2.3') // '1.2.3'
9 semver.valid('a.b.c') // null
10 semver.clean(' =v1.2.3 ') // '1.2.3'
11 semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
12 semver.gt('1.2.3', '9.8.7') // false
13 semver.lt('1.2.3', '9.8.7') // true
15 As a command-line utility:
19 Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | --preid <identifier> | -l | -rv]
20 Test if version(s) satisfy the supplied range(s), and sort them.
22 Multiple versions or ranges may be supplied, unless increment
23 option is specified. In that case, only a single version may
24 be used, and it is incremented by the specified level
26 Program exits successfully if any valid version satisfies
27 all supplied ranges, and prints all satisfying versions.
29 If no versions are valid, or ranges are not satisfied,
32 Versions are printed in ascending order, so supplying
33 multiple versions to the utility will just sort them.
37 A "version" is described by the `v2.0.0` specification found at
40 A leading `"="` or `"v"` character is stripped off and ignored.
44 A `version range` is a set of `comparators` which specify versions
45 that satisfy the range.
47 A `comparator` is composed of an `operator` and a `version`. The set
48 of primitive `operators` is:
51 * `<=` Less than or equal to
53 * `>=` Greater than or equal to
54 * `=` Equal. If no operator is specified, then equality is assumed,
55 so this operator is optional, but MAY be included.
57 For example, the comparator `>=1.2.7` would match the versions
58 `1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
61 Comparators can be joined by whitespace to form a `comparator set`,
62 which is satisfied by the **intersection** of all of the comparators
65 A range is composed of one or more comparator sets, joined by `||`. A
66 version matches a range if and only if every comparator in at least
67 one of the `||`-separated comparator sets is satisfied by the version.
69 For example, the range `>=1.2.7 <1.3.0` would match the versions
70 `1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
73 The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
74 `1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
78 If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
79 it will only be allowed to satisfy comparator sets if at least one
80 comparator with the same `[major, minor, patch]` tuple also has a
83 For example, the range `>1.2.3-alpha.3` would be allowed to match the
84 version `1.2.3-alpha.7`, but it would *not* be satisfied by
85 `3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
86 than" `1.2.3-alpha.3` according to the SemVer sort rules. The version
87 range only accepts prerelease tags on the `1.2.3` version. The
88 version `3.4.5` *would* satisfy the range, because it does not have a
89 prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
91 The purpose for this behavior is twofold. First, prerelease versions
92 frequently are updated very quickly, and contain many breaking changes
93 that are (by the author's design) not yet fit for public consumption.
94 Therefore, by default, they are excluded from range matching
97 Second, a user who has opted into using a prerelease version has
98 clearly indicated the intent to use *that specific* set of
99 alpha/beta/rc versions. By including a prerelease tag in the range,
100 the user is indicating that they are aware of the risk. However, it
101 is still not appropriate to assume that they have opted into taking a
102 similar risk on the *next* set of prerelease versions.
104 #### Prerelease Identifiers
106 The method `.inc` takes an additional `identifier` string argument that
107 will append the value of the string as a prerelease identifier:
110 > semver.inc('1.2.3', 'prerelease', 'beta')
114 command-line example:
117 $ semver 1.2.3 -i prerelease --preid beta
121 Which then can be used to increment further:
124 $ semver 1.2.4-beta.0 -i prerelease
128 ### Advanced Range Syntax
130 Advanced range syntax desugars to primitive comparators in
133 Advanced ranges may be combined in the same way as primitive
134 comparators using white space or `||`.
136 #### Hyphen Ranges `X.Y.Z - A.B.C`
138 Specifies an inclusive set.
140 * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
142 If a partial version is provided as the first version in the inclusive
143 range, then the missing pieces are replaced with zeroes.
145 * `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
147 If a partial version is provided as the second version in the
148 inclusive range, then all versions that start with the supplied parts
149 of the tuple are accepted, but nothing that would be greater than the
150 provided tuple parts.
152 * `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
153 * `1.2.3 - 2` := `>=1.2.3 <3.0.0`
155 #### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
157 Any of `X`, `x`, or `*` may be used to "stand in" for one of the
158 numeric values in the `[major, minor, patch]` tuple.
160 * `*` := `>=0.0.0` (Any version satisfies)
161 * `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
162 * `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
164 A partial version range is treated as an X-Range, so the special
165 character is in fact optional.
167 * `""` (empty string) := `*` := `>=0.0.0`
168 * `1` := `1.x.x` := `>=1.0.0 <2.0.0`
169 * `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
171 #### Tilde Ranges `~1.2.3` `~1.2` `~1`
173 Allows patch-level changes if a minor version is specified on the
174 comparator. Allows minor-level changes if not.
176 * `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
177 * `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
178 * `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
179 * `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
180 * `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
181 * `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
182 * `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
183 the `1.2.3` version will be allowed, if they are greater than or
184 equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
185 `1.2.4-beta.2` would not, because it is a prerelease of a
186 different `[major, minor, patch]` tuple.
188 #### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
190 Allows changes that do not modify the left-most non-zero digit in the
191 `[major, minor, patch]` tuple. In other words, this allows patch and
192 minor updates for versions `1.0.0` and above, patch updates for
193 versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
195 Many authors treat a `0.x` version as if the `x` were the major
196 "breaking-change" indicator.
198 Caret ranges are ideal when an author may make breaking changes
199 between `0.2.4` and `0.3.0` releases, which is a common practice.
200 However, it presumes that there will *not* be breaking changes between
201 `0.2.4` and `0.2.5`. It allows for changes that are presumed to be
202 additive (but non-breaking), according to commonly observed practices.
204 * `^1.2.3` := `>=1.2.3 <2.0.0`
205 * `^0.2.3` := `>=0.2.3 <0.3.0`
206 * `^0.0.3` := `>=0.0.3 <0.0.4`
207 * `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
208 the `1.2.3` version will be allowed, if they are greater than or
209 equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
210 `1.2.4-beta.2` would not, because it is a prerelease of a
211 different `[major, minor, patch]` tuple.
212 * `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the
213 `0.0.3` version *only* will be allowed, if they are greater than or
214 equal to `beta`. So, `0.0.3-pr.2` would be allowed.
216 When parsing caret ranges, a missing `patch` value desugars to the
217 number `0`, but will allow flexibility within that value, even if the
218 major and minor versions are both `0`.
220 * `^1.2.x` := `>=1.2.0 <2.0.0`
221 * `^0.0.x` := `>=0.0.0 <0.1.0`
222 * `^0.0` := `>=0.0.0 <0.1.0`
224 A missing `minor` and `patch` values will desugar to zero, but also
225 allow flexibility within those values, even if the major version is
228 * `^1.x` := `>=1.0.0 <2.0.0`
229 * `^0.x` := `>=0.0.0 <1.0.0`
233 Putting all this together, here is a Backus-Naur grammar for ranges,
234 for the benefit of parser authors:
237 range-set ::= range ( logical-or range ) *
238 logical-or ::= ( ' ' ) * '||' ( ' ' ) *
239 range ::= hyphen | simple ( ' ' simple ) * | ''
240 hyphen ::= partial ' - ' partial
241 simple ::= primitive | partial | tilde | caret
242 primitive ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
243 partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
244 xr ::= 'x' | 'X' | '*' | nr
245 nr ::= '0' | ['1'-'9']['0'-'9']+
246 tilde ::= '~' partial
247 caret ::= '^' partial
248 qualifier ::= ( '-' pre )? ( '+' build )?
251 parts ::= part ( '.' part ) *
252 part ::= nr | [-0-9A-Za-z]+
257 All methods and classes take a final `loose` boolean argument that, if
258 true, will be more forgiving about not-quite-valid semver strings.
259 The resulting output will always be 100% strict, of course.
261 Strict-mode Comparators and Ranges will be strict about the SemVer
262 strings that they parse.
264 * `valid(v)`: Return the parsed version, or null if it's not valid.
265 * `inc(v, release)`: Return the version incremented by the release
266 type (`major`, `premajor`, `minor`, `preminor`, `patch`,
267 `prepatch`, or `prerelease`), or null if it's not valid
268 * `premajor` in one call will bump the version up to the next major
269 version and down to a prerelease of that major version.
270 `preminor`, and `prepatch` work the same way.
271 * If called from a non-prerelease version, the `prerelease` will work the
272 same as `prepatch`. It increments the patch version, then makes a
273 prerelease. If the input version is already a prerelease it simply
275 * `major(v)`: Return the major version number.
276 * `minor(v)`: Return the minor version number.
277 * `patch(v)`: Return the patch version number.
281 * `gt(v1, v2)`: `v1 > v2`
282 * `gte(v1, v2)`: `v1 >= v2`
283 * `lt(v1, v2)`: `v1 < v2`
284 * `lte(v1, v2)`: `v1 <= v2`
285 * `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
286 even if they're not the exact same string. You already know how to
288 * `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
289 * `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
290 the corresponding function above. `"==="` and `"!=="` do simple
291 string comparison, but are included for completeness. Throws if an
292 invalid comparison string is provided.
293 * `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
294 `v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
295 * `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions
296 in descending order when passed to `Array.sort()`.
297 * `diff(v1, v2)`: Returns difference between two versions by the release type
298 (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
299 or null if the versions are the same.
304 * `validRange(range)`: Return the valid range or null if it's not valid
305 * `satisfies(version, range)`: Return true if the version satisfies the
307 * `maxSatisfying(versions, range)`: Return the highest version in the list
308 that satisfies the range, or `null` if none of them do.
309 * `gtr(version, range)`: Return `true` if version is greater than all the
310 versions possible in the range.
311 * `ltr(version, range)`: Return `true` if version is less than all the
312 versions possible in the range.
313 * `outside(version, range, hilo)`: Return true if the version is outside
314 the bounds of the range in either the high or low direction. The
315 `hilo` argument must be either the string `'>'` or `'<'`. (This is
316 the function called by `gtr` and `ltr`.)
318 Note that, since ranges may be non-contiguous, a version might not be
319 greater than a range, less than a range, *or* satisfy a range! For
320 example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
321 until `2.0.0`, so the version `1.2.10` would not be greater than the
322 range (because `2.0.1` satisfies, which is higher), nor less than the
323 range (since `1.2.8` satisfies, which is lower), and it also does not
326 If you want to know if a version satisfies or does not satisfy a
327 range, use the `satisfies(version, range)` function.