@cryptotaxi247 / documentation-1 / commits / bd79d0e

CLI documentation update from CI

CI User committed Aug 11, 2021 at 18:19 UTC bd79d0e4e2b231cc5d00fec3e57871cf47ce37ec
5 files changed -788
content/cli/v7/commands/npm-bundle.md deleted
-20
@@ -1,20 +0,0 @@
1 ----
2 -title: npm-bundle
3 -section: 1
4 -description: REMOVED
5 -github_repo: npm/cli
6 -github_branch: release/v7.0.0-beta
7 -github_path: docs/content/commands/npm-bundle.md
8 ----
9 -
10 -### Description
11 -
12 -The `npm bundle` command has been removed in 1.0, for the simple reason
13 -that it is no longer necessary, as the default behavior is now to
14 -install packages into the local space.
15 -
16 -Just use `npm install` now to do what `npm bundle` used to do.
17 -
18 -### See Also
19 -
20 -* [npm install](/cli/v7/commands/npm-install)
content/cli/v7/configuring-npm/package-locks.md deleted
-181
@@ -1,181 +0,0 @@
1 ----
2 -title: package-locks
3 -section: 5
4 -description: An explanation of npm lockfiles
5 -github_repo: npm/cli
6 -github_branch: latest
7 -github_path: docs/content/configuring-npm/package-locks.md
8 ----
9 -
10 -### Description
11 -
12 -Conceptually, the "input" to [`npm install`](/cli/v7/commands/npm-install) is a [package.json](/cli/v7/configuring-npm/package-json), while its
13 -"output" is a fully-formed `node_modules` tree: a representation of the
14 -dependencies you declared. In an ideal world, npm would work like a pure
15 -function: the same `package.json` should produce the exact same `node_modules`
16 -tree, any time. In some cases, this is indeed true. But in many others, npm is
17 -unable to do this. There are multiple reasons for this:
18 -
19 -* different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.
20 -
21 -* a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.
22 -
23 -* A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (`1.2.3` instead of `^1.2.3`)
24 -
25 -* The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.
26 -
27 -As an example, consider package A:
28 -
29 -```json
30 -{
31 - "name": "A",
32 - "version": "0.1.0",
33 - "dependencies": {
34 - "B": "<0.1.0"
35 - }
36 -}
37 -```
38 -
39 -package B:
40 -
41 -```json
42 -{
43 - "name": "B",
44 - "version": "0.0.1",
45 - "dependencies": {
46 - "C": "<0.1.0"
47 - }
48 -}
49 -```
50 -
51 -and package C:
52 -```json
53 -{
54 - "name": "C",
55 - "version": "0.0.1"
56 -}
57 -```
58 -
59 -If these are the only versions of A, B, and C available in the
60 -registry, then a normal `npm install A` will install:
61 -
62 -```json
63 -A@0.1.0
64 -`-- B@0.0.1
65 - `-- C@0.0.1
66 -```
67 -
68 -However, if B@0.0.2 is published, then a fresh `npm install A` will
69 -install:
70 -
71 -```bash
72 -A@0.1.0
73 -`-- B@0.0.2
74 - `-- C@0.0.1
75 -```
76 -
77 -assuming the new version did not modify B's dependencies. Of course,
78 -the new version of B could include a new version of C and any number
79 -of new dependencies. If such changes are undesirable, the author of A
80 -could specify a dependency on B@0.0.1. However, if A's author and B's
81 -author are not the same person, there's no way for A's author to say
82 -that he or she does not want to pull in newly published versions of C
83 -when B hasn't changed at all.
84 -
85 -To prevent this potential issue, npm uses [package-lock.json](/cli/v7/configuring-npm/package-lock-json) or, if present, [npm-shrinkwrap.json](/cli/v7/configuring-npm/shrinkwrap-json). These files are called package locks, or lockfiles.
86 -
87 -Whenever you run `npm install`, npm generates or updates your package lock,
88 -which will look something like this:
89 -
90 -```json
91 -{
92 - "name": "A",
93 - "version": "0.1.0",
94 - ...metadata fields...
95 - "dependencies": {
96 - "B": {
97 - "version": "0.0.1",
98 - "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
99 - "integrity": "sha512-DeAdb33F+"
100 - "dependencies": {
101 - "C": {
102 - "version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
103 - }
104 - }
105 - }
106 - }
107 -}
108 -```
109 -
110 -This file describes an *exact*, and more importantly *reproducible*
111 -`node_modules` tree. Once it's present, any future installation will base its
112 -work off this file, instead of recalculating dependency versions off
113 -[package.json](/cli/v7/configuring-npm/package-json).
114 -
115 -The presence of a package lock changes the installation behavior such that:
116 -
117 -1. The module tree described by the package lock is reproduced. This means
118 -reproducing the structure described in the file, using the specific files
119 -referenced in "resolved" if available, falling back to normal package resolution
120 -using "version" if one isn't.
121 -
122 -2. The tree is walked and any missing dependencies are installed in the usual
123 -fashion.
124 -
125 -If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts`
126 -property of the `package.json`, they will be executed in order. `preshrinkwrap`
127 -and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
128 -executed afterwards. These scripts run for both `package-lock.json` and
129 -`npm-shrinkwrap.json`. For example to run some postprocessing on the generated
130 -file:
131 -
132 -```json
133 - "scripts": {
134 - "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
135 - }
136 -```
137 -
138 -#### Using locked packages
139 -
140 -Using a locked package is no different than using any package without a package
141 -lock: any commands that update `node_modules` and/or `package.json`'s
142 -dependencies will automatically sync the existing lockfile. This includes `npm
143 -install`, `npm rm`, `npm update`, etc. To prevent this update from happening,
144 -you can use the `--no-save` option to prevent saving altogether, or
145 -`--no-shrinkwrap` to allow `package.json` to be updated while leaving
146 -`package-lock.json` or `npm-shrinkwrap.json` intact.
147 -
148 -It is highly recommended you commit the generated package lock to source
149 -control: this will allow anyone else on your team, your deployments, your
150 -CI/continuous integration, and anyone else who runs `npm install` in your
151 -package source to get the exact same dependency tree that you were developing
152 -on. Additionally, the diffs from these changes are human-readable and will
153 -inform you of any changes npm has made to your `node_modules`, so you can notice
154 -if any transitive dependencies were updated, hoisted, etc.
155 -
156 -#### Resolving lockfile conflicts
157 -
158 -Occasionally, two separate npm install will create package locks that cause
159 -merge conflicts in source control systems. As of `npm@5.7.0`, these conflicts
160 -can be resolved by manually fixing any `package.json` conflicts, and then
161 -running `npm install [--package-lock-only]` again. npm will automatically
162 -resolve any conflicts for you and write a merged package lock that includes all
163 -the dependencies from both branches in a reasonable tree. If
164 -`--package-lock-only` is provided, it will do this without also modifying your
165 -local `node_modules/`.
166 -
167 -To make this process seamless on git, consider installing
168 -[`npm-merge-driver`](https://npm.im/npm-merge-driver), which will teach git how
169 -to do this itself without any user interaction. In short: `$ npx
170 -npm-merge-driver install -g` will let you do this, and even works with
171 -pre-`npm@5.7.0` versions of npm 5, albeit a bit more noisily. Note that if
172 -`package.json` itself conflicts, you will have to resolve that by hand and run
173 -`npm install` manually, even with the merge driver.
174 -
175 -### See Also
176 -
177 -* https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527
178 -* [package.json](/cli/v7/configuring-npm/package-json)
179 -* [package-lock.json](/cli/v7/configuring-npm/package-lock-json)
180 -* [shrinkwrap.json](/cli/v7/configuring-npm/shrinkwrap-json)
181 -* [npm shrinkwrap](/cli/v7/commands/npm-shrinkwrap)
content/cli/v7/configuring-npm/shrinkwrap-json.md deleted
-33
@@ -1,33 +0,0 @@
1 ----
2 -title: shrinkwrap.json
3 -section: 5
4 -description: A publishable lockfile
5 -github_repo: npm/cli
6 -github_branch: latest
7 -github_path: docs/content/configuring-npm/shrinkwrap-json.md
8 ----
9 -
10 -### Description
11 -
12 -`npm-shrinkwrap.json` is a file created by [`npm shrinkwrap`](/cli/v7/commands/npm-shrinkwrap). It is identical to
13 -`package-lock.json`, with one major caveat: Unlike `package-lock.json`,
14 -`npm-shrinkwrap.json` may be included when publishing a package.
15 -
16 -The recommended use-case for `npm-shrinkwrap.json` is applications deployed
17 -through the publishing process on the registry: for example, daemons and
18 -command-line tools intended as global installs or `devDependencies`. It's
19 -strongly discouraged for library authors to publish this file, since that would
20 -prevent end users from having control over transitive dependency updates.
21 -
22 -Additionally, if both `package-lock.json` and `npm-shrinkwrap.json` are present
23 -in a package root, `package-lock.json` will be ignored in favor of this file.
24 -
25 -For full details and description of the `npm-shrinkwrap.json` file format, refer
26 -to the manual page for [package-lock.json](/cli/v7/configuring-npm/package-lock-json).
27 -
28 -### See also
29 -
30 -* [npm shrinkwrap](/cli/v7/commands/npm-shrinkwrap)
31 -* [package-lock.json](/cli/v7/configuring-npm/package-lock-json)
32 -* [package.json](/cli/v7/configuring-npm/package-json)
33 -* [npm install](/cli/v7/commands/npm-install)
content/cli/v7/using-npm/disputes.md deleted
-136
@@ -1,136 +0,0 @@
1 ----
2 -title: disputes
3 -section: 7
4 -description: Handling Module Name Disputes
5 -github_repo: npm/cli
6 -github_branch: latest
7 -github_path: docs/content/using-npm/disputes.md
8 ----
9 -
10 -This document describes the steps that you should take to resolve module name
11 -disputes with other npm publishers. It also describes special steps you should
12 -take about names you think infringe your trademarks.
13 -
14 -This document is a clarification of the acceptable behavior outlined in the
15 -[npm Code of Conduct](https://www.npmjs.com/policies/conduct), and nothing in
16 -this document should be interpreted to contradict any aspect of the npm Code of
17 -Conduct.
18 -
19 -### TL;DR
20 -
21 -1. Get the author email with `npm owner ls <pkgname>`
22 -2. Email the author, CC <support@npmjs.com>
23 -3. After a few weeks, if there's no resolution, we'll sort it out.
24 -
25 -Don't squat on package names. Publish code or move out of the way.
26 -
27 -### Description
28 -
29 -There sometimes arise cases where a user publishes a module, and then later,
30 -some other user wants to use that name. Here are some common ways that happens
31 -(each of these is based on actual events.)
32 -
33 -1. Alice writes a JavaScript module `foo`, which is not node-specific. Alice
34 - doesn't use node at all. Yusuf wants to use `foo` in node, so he wraps it in
35 - an npm module. Some time later, Alice starts using node, and wants to take
36 - over management of her program.
37 -2. Yusuf writes an npm module `foo`, and publishes it. Perhaps much later, Alice
38 - finds a bug in `foo`, and fixes it. She sends a pull request to Yusuf, but
39 - Yusuf doesn't have the time to deal with it, because he has a new job and a
40 - new baby and is focused on his new Erlang project, and kind of not involved
41 - with node any more. Alice would like to publish a new `foo`, but can't,
42 - because the name is taken.
43 -3. Yusuf writes a 10-line flow-control library, and calls it `foo`, and
44 - publishes it to the npm registry. Being a simple little thing, it never
45 - really has to be updated. Alice works for Foo Inc, the makers of the
46 - critically acclaimed and widely-marketed `foo` JavaScript toolkit framework.
47 - They publish it to npm as `foojs`, but people are routinely confused when
48 - `npm install foo` is some different thing.
49 -4. Yusuf writes a parser for the widely-known `foo` file format, because he
50 - needs it for work. Then, he gets a new job, and never updates the prototype.
51 - Later on, Alice writes a much more complete `foo` parser, but can't publish,
52 - because Yusuf's `foo` is in the way.
53 -
54 -1. `npm owner ls foo`. This will tell Alice the email address of the owner
55 - (Yusuf).
56 -2. Alice emails Yusuf, explaining the situation **as respectfully as possible**,
57 - and what she would like to do with the module name. She adds the npm support
58 - staff <support@npmjs.com> to the CC list of the email. Mention in the email
59 - that Yusuf can run npm owner `add alice foo` to add Alice as an owner of the
60 - foo package.
61 -3. After a reasonable amount of time, if Yusuf has not responded, or if Yusuf
62 - and Alice can't come to any sort of resolution, email support
63 - <support@npmjs.com> and we'll sort it out. ("Reasonable" is usually at least
64 - 4 weeks.)
65 -
66 -### Reasoning
67 -
68 -In almost every case so far, the parties involved have been able to reach an
69 -amicable resolution without any major intervention. Most people really do want
70 -to be reasonable, and are probably not even aware that they're in your way.
71 -
72 -Module ecosystems are most vibrant and powerful when they are as self-directed
73 -as possible. If an admin one day deletes something you had worked on, then that
74 -is going to make most people quite upset, regardless of the justification. When
75 -humans solve their problems by talking to other humans with respect, everyone
76 -has the chance to end up feeling good about the interaction.
77 -
78 -### Exceptions
79 -
80 -Some things are not allowed, and will be removed without discussion if they are
81 -brought to the attention of the npm registry admins, including but not limited
82 -to:
83 -
84 -1. Malware (that is, a package designed to exploit or harm the machine on which
85 - it is installed).
86 -2. Violations of copyright or licenses (for example, cloning an MIT-licensed
87 - program, and then removing or changing the copyright and license statement).
88 -3. Illegal content.
89 -4. "Squatting" on a package name that you plan to use, but aren't actually
90 - using. Sorry, I don't care how great the name is, or how perfect a fit it is
91 - for the thing that someday might happen. If someone wants to use it today,
92 - and you're just taking up space with an empty tarball, you're going to be
93 - evicted.
94 -5. Putting empty packages in the registry. Packages must have SOME
95 - functionality. It can be silly, but it can't be nothing. (See also:
96 - squatting.)
97 -6. Doing weird things with the registry, like using it as your own personal
98 - application database or otherwise putting non-packagey things into it.
99 -7. Other things forbidden by the npm
100 - [Code of Conduct](https://www.npmjs.com/policies/conduct) such as hateful
101 - language, pornographic content, or harassment.
102 -
103 -If you see bad behavior like this, please report it to <abuse@npmjs.com> right
104 -away. **You are never expected to resolve abusive behavior on your own. We are
105 -here to help.**
106 -
107 -### Trademarks
108 -
109 -If you think another npm publisher is infringing your trademark, such as by
110 -using a confusingly similar package name, email <abuse@npmjs.com> with a link to
111 -the package or user account on [https://www.npmjs.com/](https://www.npmjs.com/).
112 -Attach a copy of your trademark registration certificate.
113 -
114 -If we see that the package's publisher is intentionally misleading others by
115 -misusing your registered mark without permission, we will transfer the package
116 -name to you. Otherwise, we will contact the package publisher and ask them to
117 -clear up any confusion with changes to their package's `README` file or
118 -metadata.
119 -
120 -### Changes
121 -
122 -This is a living document and may be updated from time to time. Please refer to
123 -the [git history for this document](https://github.com/npm/cli/commits/latest/doc/misc/npm-disputes.md)
124 -to view the changes.
125 -
126 -### License
127 -
128 -Copyright (C) npm, Inc., All rights reserved
129 -
130 -This document may be reused under a Creative Commons Attribution-ShareAlike
131 -License.
132 -
133 -### See also
134 -
135 -* [npm registry](/cli/v7/using-npm/registry)
136 -* [npm owner](/cli/v7/commands/npm-owner)
content/cli/v7/using-npm/semver.md deleted
-418
@@ -1,418 +0,0 @@
1 ----
2 -title: semver
3 -section: 7
4 -description: The semantic versioner for npm
5 -github_repo: npm/cli
6 -github_branch: latest
7 -github_path: docs/content/using-npm/semver.md
8 ----
9 -
10 -## Install
11 -
12 -```bash
13 -npm install --save semver
14 -````
15 -
16 -## Usage
17 -
18 -As a node module:
19 -
20 -```js
21 -const semver = require('semver')
22 -
23 -semver.valid('1.2.3') // '1.2.3'
24 -semver.valid('a.b.c') // null
25 -semver.clean(' =v1.2.3 ') // '1.2.3'
26 -semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
27 -semver.gt('1.2.3', '9.8.7') // false
28 -semver.lt('1.2.3', '9.8.7') // true
29 -semver.minVersion('>=1.0.0') // '1.0.0'
30 -semver.valid(semver.coerce('v2')) // '2.0.0'
31 -semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
32 -```
33 -
34 -As a command-line utility:
35 -
36 -```
37 -$ semver -h
38 -
39 -A JavaScript implementation of the https://semver.org/ specification
40 -Copyright Isaac Z. Schlueter
41 -
42 -Usage: semver [options] <version> [<version> [...]]
43 -Prints valid versions sorted by SemVer precedence
44 -
45 -Options:
46 --r --range <range>
47 - Print versions that match the specified range.
48 -
49 --i --increment [<level>]
50 - Increment a version by the specified level. Level can
51 - be one of: major, minor, patch, premajor, preminor,
52 - prepatch, or prerelease. Default level is 'patch'.
53 - Only one version may be specified.
54 -
55 ---preid <identifier>
56 - Identifier to be used to prefix premajor, preminor,
57 - prepatch or prerelease version increments.
58 -
59 --l --loose
60 - Interpret versions and ranges loosely
61 -
62 --p --include-prerelease
63 - Always include prerelease versions in range matching
64 -
65 --c --coerce
66 - Coerce a string into SemVer if possible
67 - (does not imply --loose)
68 -
69 -Program exits successfully if any valid version satisfies
70 -all supplied ranges, and prints all satisfying versions.
71 -
72 -If no satisfying versions are found, then exits failure.
73 -
74 -Versions are printed in ascending order, so supplying
75 -multiple versions to the utility will just sort them.
76 -```
77 -
78 -## Versions
79 -
80 -A "version" is described by the `v2.0.0` specification found at
81 -<https://semver.org/>.
82 -
83 -A leading `"="` or `"v"` character is stripped off and ignored.
84 -
85 -## Ranges
86 -
87 -A `version range` is a set of `comparators` which specify versions
88 -that satisfy the range.
89 -
90 -A `comparator` is composed of an `operator` and a `version`. The set
91 -of primitive `operators` is:
92 -
93 -* `<` Less than
94 -* `<=` Less than or equal to
95 -* `>` Greater than
96 -* `>=` Greater than or equal to
97 -* `=` Equal. If no operator is specified, then equality is assumed,
98 - so this operator is optional, but MAY be included.
99 -
100 -For example, the comparator `>=1.2.7` would match the versions
101 -`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
102 -or `1.1.0`.
103 -
104 -Comparators can be joined by whitespace to form a `comparator set`,
105 -which is satisfied by the **intersection** of all of the comparators
106 -it includes.
107 -
108 -A range is composed of one or more comparator sets, joined by `||`. A
109 -version matches a range if and only if every comparator in at least
110 -one of the `||`-separated comparator sets is satisfied by the version.
111 -
112 -For example, the range `>=1.2.7 <1.3.0` would match the versions
113 -`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
114 -or `1.1.0`.
115 -
116 -The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
117 -`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
118 -
119 -### Prerelease Tags
120 -
121 -If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
122 -it will only be allowed to satisfy comparator sets if at least one
123 -comparator with the same `[major, minor, patch]` tuple also has a
124 -prerelease tag.
125 -
126 -For example, the range `>1.2.3-alpha.3` would be allowed to match the
127 -version `1.2.3-alpha.7`, but it would *not* be satisfied by
128 -`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
129 -than" `1.2.3-alpha.3` according to the SemVer sort rules. The version
130 -range only accepts prerelease tags on the `1.2.3` version. The
131 -version `3.4.5` *would* satisfy the range, because it does not have a
132 -prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
133 -
134 -The purpose for this behavior is twofold. First, prerelease versions
135 -frequently are updated very quickly, and contain many breaking changes
136 -that are (by the author's design) not yet fit for public consumption.
137 -Therefore, by default, they are excluded from range matching
138 -semantics.
139 -
140 -Second, a user who has opted into using a prerelease version has
141 -clearly indicated the intent to use *that specific* set of
142 -alpha/beta/rc versions. By including a prerelease tag in the range,
143 -the user is indicating that they are aware of the risk. However, it
144 -is still not appropriate to assume that they have opted into taking a
145 -similar risk on the *next* set of prerelease versions.
146 -
147 -Note that this behavior can be suppressed (treating all prerelease
148 -versions as if they were normal versions, for the purpose of range
149 -matching) by setting the `includePrerelease` flag on the options
150 -object to any
151 -[functions](https://github.com/npm/node-semver#functions) that do
152 -range matching.
153 -
154 -#### Prerelease Identifiers
155 -
156 -The method `.inc` takes an additional `identifier` string argument that
157 -will append the value of the string as a prerelease identifier:
158 -
159 -```javascript
160 -semver.inc('1.2.3', 'prerelease', 'beta')
161 -// '1.2.4-beta.0'
162 -```
163 -
164 -command-line example:
165 -
166 -```bash
167 -$ semver 1.2.3 -i prerelease --preid beta
168 -1.2.4-beta.0
169 -```
170 -
171 -Which then can be used to increment further:
172 -
173 -```bash
174 -$ semver 1.2.4-beta.0 -i prerelease
175 -1.2.4-beta.1
176 -```
177 -
178 -### Advanced Range Syntax
179 -
180 -Advanced range syntax desugars to primitive comparators in
181 -deterministic ways.
182 -
183 -Advanced ranges may be combined in the same way as primitive
184 -comparators using white space or `||`.
185 -
186 -#### Hyphen Ranges `X.Y.Z - A.B.C`
187 -
188 -Specifies an inclusive set.
189 -
190 -* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
191 -
192 -If a partial version is provided as the first version in the inclusive
193 -range, then the missing pieces are replaced with zeroes.
194 -
195 -* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
196 -
197 -If a partial version is provided as the second version in the
198 -inclusive range, then all versions that start with the supplied parts
199 -of the tuple are accepted, but nothing that would be greater than the
200 -provided tuple parts.
201 -
202 -* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
203 -* `1.2.3 - 2` := `>=1.2.3 <3.0.0`
204 -
205 -#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
206 -
207 -Any of `X`, `x`, or `*` may be used to "stand in" for one of the
208 -numeric values in the `[major, minor, patch]` tuple.
209 -
210 -* `*` := `>=0.0.0` (Any version satisfies)
211 -* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
212 -* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
213 -
214 -A partial version range is treated as an X-Range, so the special
215 -character is in fact optional.
216 -
217 -* `""` (empty string) := `*` := `>=0.0.0`
218 -* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
219 -* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
220 -
221 -#### Tilde Ranges `~1.2.3` `~1.2` `~1`
222 -
223 -Allows patch-level changes if a minor version is specified on the
224 -comparator. Allows minor-level changes if not.
225 -
226 -* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
227 -* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
228 -* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
229 -* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
230 -* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
231 -* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
232 -* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
233 - the `1.2.3` version will be allowed, if they are greater than or
234 - equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
235 - `1.2.4-beta.2` would not, because it is a prerelease of a
236 - different `[major, minor, patch]` tuple.
237 -
238 -#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
239 -
240 -Allows changes that do not modify the left-most non-zero digit in the
241 -`[major, minor, patch]` tuple. In other words, this allows patch and
242 -minor updates for versions `1.0.0` and above, patch updates for
243 -versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
244 -
245 -Many authors treat a `0.x` version as if the `x` were the major
246 -"breaking-change" indicator.
247 -
248 -Caret ranges are ideal when an author may make breaking changes
249 -between `0.2.4` and `0.3.0` releases, which is a common practice.
250 -However, it presumes that there will *not* be breaking changes between
251 -`0.2.4` and `0.2.5`. It allows for changes that are presumed to be
252 -additive (but non-breaking), according to commonly observed practices.
253 -
254 -* `^1.2.3` := `>=1.2.3 <2.0.0`
255 -* `^0.2.3` := `>=0.2.3 <0.3.0`
256 -* `^0.0.3` := `>=0.0.3 <0.0.4`
257 -* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
258 - the `1.2.3` version will be allowed, if they are greater than or
259 - equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
260 - `1.2.4-beta.2` would not, because it is a prerelease of a
261 - different `[major, minor, patch]` tuple.
262 -* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the
263 - `0.0.3` version *only* will be allowed, if they are greater than or
264 - equal to `beta`. So, `0.0.3-pr.2` would be allowed.
265 -
266 -When parsing caret ranges, a missing `patch` value desugars to the
267 -number `0`, but will allow flexibility within that value, even if the
268 -major and minor versions are both `0`.
269 -
270 -* `^1.2.x` := `>=1.2.0 <2.0.0`
271 -* `^0.0.x` := `>=0.0.0 <0.1.0`
272 -* `^0.0` := `>=0.0.0 <0.1.0`
273 -
274 -A missing `minor` and `patch` values will desugar to zero, but also
275 -allow flexibility within those values, even if the major version is
276 -zero.
277 -
278 -* `^1.x` := `>=1.0.0 <2.0.0`
279 -* `^0.x` := `>=0.0.0 <1.0.0`
280 -
281 -### Range Grammar
282 -
283 -Putting all this together, here is a Backus-Naur grammar for ranges,
284 -for the benefit of parser authors:
285 -
286 -```bnf
287 -range-set ::= range ( logical-or range ) *
288 -logical-or ::= ( ' ' ) * '||' ( ' ' ) *
289 -range ::= hyphen | simple ( ' ' simple ) * | ''
290 -hyphen ::= partial ' - ' partial
291 -simple ::= primitive | partial | tilde | caret
292 -primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
293 -partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
294 -xr ::= 'x' | 'X' | '*' | nr
295 -nr ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
296 -tilde ::= '~' partial
297 -caret ::= '^' partial
298 -qualifier ::= ( '-' pre )? ( '+' build )?
299 -pre ::= parts
300 -build ::= parts
301 -parts ::= part ( '.' part ) *
302 -part ::= nr | [-0-9A-Za-z]+
303 -```
304 -
305 -## Functions
306 -
307 -All methods and classes take a final `options` object argument. All
308 -options in this object are `false` by default. The options supported
309 -are:
310 -
311 -- `loose` Be more forgiving about not-quite-valid semver strings.
312 - (Any resulting output will always be 100% strict compliant, of
313 - course.) For backwards compatibility reasons, if the `options`
314 - argument is a boolean value instead of an object, it is interpreted
315 - to be the `loose` param.
316 -- `includePrerelease` Set to suppress the [default
317 - behavior](https://github.com/npm/node-semver#prerelease-tags) of
318 - excluding prerelease tagged versions from ranges unless they are
319 - explicitly opted into.
320 -
321 -Strict-mode Comparators and Ranges will be strict about the SemVer
322 -strings that they parse.
323 -
324 -* `valid(v)`: Return the parsed version, or null if it's not valid.
325 -* `inc(v, release)`: Return the version incremented by the release
326 - type (`major`, `premajor`, `minor`, `preminor`, `patch`,
327 - `prepatch`, or `prerelease`), or null if it's not valid
328 - * `premajor` in one call will bump the version up to the next major
329 - version and down to a prerelease of that major version.
330 - `preminor`, and `prepatch` work the same way.
331 - * If called from a non-prerelease version, the `prerelease` will work the
332 - same as `prepatch`. It increments the patch version, then makes a
333 - prerelease. If the input version is already a prerelease it simply
334 - increments it.
335 -* `prerelease(v)`: Returns an array of prerelease components, or null
336 - if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
337 -* `major(v)`: Return the major version number.
338 -* `minor(v)`: Return the minor version number.
339 -* `patch(v)`: Return the patch version number.
340 -* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
341 - or comparators intersect.
342 -* `parse(v)`: Attempt to parse a string as a semantic version, returning either
343 - a `SemVer` object or `null`.
344 -
345 -### Comparison
346 -
347 -* `gt(v1, v2)`: `v1 > v2`
348 -* `gte(v1, v2)`: `v1 >= v2`
349 -* `lt(v1, v2)`: `v1 < v2`
350 -* `lte(v1, v2)`: `v1 <= v2`
351 -* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
352 - even if they're not the exact same string. You already know how to
353 - compare strings.
354 -* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
355 -* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
356 - the corresponding function above. `"==="` and `"!=="` do simple
357 - string comparison, but are included for completeness. Throws if an
358 - invalid comparison string is provided.
359 -* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
360 - `v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
361 -* `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions
362 - in descending order when passed to `Array.sort()`.
363 -* `diff(v1, v2)`: Returns difference between two versions by the release type
364 - (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
365 - or null if the versions are the same.
366 -
367 -### Comparators
368 -
369 -* `intersects(comparator)`: Return true if the comparators intersect
370 -
371 -### Ranges
372 -
373 -* `validRange(range)`: Return the valid range or null if it's not valid
374 -* `satisfies(version, range)`: Return true if the version satisfies the
375 - range.
376 -* `maxSatisfying(versions, range)`: Return the highest version in the list
377 - that satisfies the range, or `null` if none of them do.
378 -* `minSatisfying(versions, range)`: Return the lowest version in the list
379 - that satisfies the range, or `null` if none of them do.
380 -* `minVersion(range)`: Return the lowest version that can possibly match
381 - the given range.
382 -* `gtr(version, range)`: Return `true` if version is greater than all the
383 - versions possible in the range.
384 -* `ltr(version, range)`: Return `true` if version is less than all the
385 - versions possible in the range.
386 -* `outside(version, range, hilo)`: Return true if the version is outside
387 - the bounds of the range in either the high or low direction. The
388 - `hilo` argument must be either the string `'>'` or `'<'`. (This is
389 - the function called by `gtr` and `ltr`.)
390 -* `intersects(range)`: Return true if any of the ranges comparators intersect
391 -
392 -Note that, since ranges may be non-contiguous, a version might not be
393 -greater than a range, less than a range, *or* satisfy a range! For
394 -example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
395 -until `2.0.0`, so the version `1.2.10` would not be greater than the
396 -range (because `2.0.1` satisfies, which is higher), nor less than the
397 -range (since `1.2.8` satisfies, which is lower), and it also does not
398 -satisfy the range.
399 -
400 -If you want to know if a version satisfies or does not satisfy a
401 -range, use the `satisfies(version, range)` function.
402 -
403 -### Coercion
404 -
405 -* `coerce(version)`: Coerces a string to semver if possible
406 -
407 -This aims to provide a very forgiving translation of a non-semver string to
408 -semver. It looks for the first digit in a string, and consumes all
409 -remaining characters which satisfy at least a partial semver (e.g., `1`,
410 -`1.2`, `1.2.3`) up to the max permitted length (256 characters). Longer
411 -versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`). All
412 -surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
413 -`3.4.0`). Only text which lacks digits will fail coercion (`version one`
414 -is not valid). The maximum length for any semver component considered for
415 -coercion is 16 characters; longer components will be ignored
416 -(`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any
417 -semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
418 -components are invalid (`9999999999999999.4.7.4` is likely invalid).