diff options
author | Ruy Adorno <ruyadorno@hotmail.com> | 2021-01-29 01:38:39 +0300 |
---|---|---|
committer | Ruy Adorno <ruyadorno@hotmail.com> | 2021-01-30 07:49:44 +0300 |
commit | d3906ae29414430c5df28858e23783b91b15ab52 (patch) | |
tree | 93dbcc6025283827c2e88e92401a5102808c265b /deps/npm/docs/content | |
parent | 0a993e1f24beea678769bc07099f05a1ed27334d (diff) |
deps: upgrade npm to 7.5.0
PR-URL: https://github.com/nodejs/node/pull/37117
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Yongsheng Zhang <zyszys98@gmail.com>
Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>
Diffstat (limited to 'deps/npm/docs/content')
-rw-r--r-- | deps/npm/docs/content/commands/npm-diff.md | 237 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-exec.md | 22 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-init.md | 23 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-owner.md | 1 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-run-script.md | 39 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-search.md | 6 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-update.md | 29 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-version.md | 21 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm-view.md | 38 | ||||
-rw-r--r-- | deps/npm/docs/content/commands/npm.md | 105 | ||||
-rw-r--r-- | deps/npm/docs/content/configuring-npm/package-json.md | 12 | ||||
-rw-r--r-- | deps/npm/docs/content/using-npm/config.md | 57 | ||||
-rw-r--r-- | deps/npm/docs/content/using-npm/disputes.md | 133 | ||||
-rw-r--r-- | deps/npm/docs/content/using-npm/registry.md | 43 | ||||
-rw-r--r-- | deps/npm/docs/content/using-npm/removal.md | 2 | ||||
-rw-r--r-- | deps/npm/docs/content/using-npm/semver.md | 415 |
16 files changed, 486 insertions, 697 deletions
diff --git a/deps/npm/docs/content/commands/npm-diff.md b/deps/npm/docs/content/commands/npm-diff.md new file mode 100644 index 00000000000..0ce5e8dc8ba --- /dev/null +++ b/deps/npm/docs/content/commands/npm-diff.md @@ -0,0 +1,237 @@ +--- +title: npm-diff +section: 1 +description: The registry diff command +--- + +### Synopsis + +```bash +npm diff [...<paths>] +npm diff --diff=<pkg-name> [...<paths>] +npm diff --diff=<version-a> [--diff=<version-b>] [...<paths>] +npm diff --diff=<spec-a> [--diff=<spec-b>] [...<paths>] +npm diff [--diff-ignore-all-space] [--diff-name-only] [...<paths>] +``` + +### Description + +Similar to its `git diff` counterpart, this command will print diff patches +of files for packages published to the npm registry. + +* `npm diff --diff=<spec-a> --diff=<spec-b>` + + Compares two package versions using their registry specifiers, e.g: + `npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0`. It's also possible to + compare across forks of any package, + e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0`. + + Any valid spec can be used, so that it's also possible to compare + directories or git repositories, + e.g: `npm diff --diff=pkg@latest --diff=./packages/pkg` + + Here's an example comparing two different versions of a package named + `abbrev` from the registry: + + ```bash + npm diff --diff=abbrev@1.1.0 --diff=abbrev@1.1.1 + ``` + + On success, output looks like: + + ```bash + diff --git a/package.json b/package.json + index v1.1.0..v1.1.1 100644 + --- a/package.json + +++ b/package.json + @@ -1,6 +1,6 @@ + { + "name": "abbrev", + - "version": "1.1.0", + + "version": "1.1.1", + "description": "Like ruby's abbrev module, but in js", + "author": "Isaac Z. Schlueter <i@izs.me>", + "main": "abbrev.js", + ``` + + Given the flexible nature of npm specs, you can also target local + directories or git repos just like when using `npm install`: + + ```bash + npm diff --diff=https://github.com/npm/libnpmdiff --diff=./local-path + ``` + + In the example above we can compare the contents from the package installed + from the git repo at `github.com/npm/libnpmdiff` with the contents of the + `./local-path` that contains a valid package, such as a modified copy of + the original. + +* `npm diff` (in a package directory, no arguments): + + If the package is published to the registry, `npm diff` will fetch the + tarball version tagged as `latest` (this value can be configured using the + `tag` option) and proceed to compare the contents of files present in that + tarball, with the current files in your local file system. + + This workflow provides a handy way for package authors to see what + package-tracked files have been changed in comparison with the latest + published version of that package. + +* `npm diff --diff=<pkg-name>` (in a package directory): + + When using a single package name (with no version or tag specifier) as an + argument, `npm diff` will work in a similar way to + [`npm-outdated`](npm-outdated) and reach for the registry to figure out + what current published version of the package named <pkg-name> will satisfy + its dependent declared semver-range. Once that specific version is known + `npm diff` will print diff patches comparing the current version of + <pkg-name> found in the local file system with that specific version + returned by the registry. + + Given a package named `abbrev` that is currently installed: + + ```bash + npm diff --diff=abbrev + ``` + + That will request from the registry its most up to date version and + will print a diff output comparing the currently installed version to this + newer one if the version numbers are not the same. + +* `npm diff --diff=<spec-a>` (in a package directory): + + Similar to using only a single package name, it's also possible to declare + a full registry specifier version if you wish to compare the local version + of an installed package with the specific version/tag/semver-range provided + in `<spec-a>`. + + An example: assuming `pkg@1.0.0` is installed in the current `node_modules` + folder, running: + + ```bash + npm diff --diff=pkg@2.0.0 + ``` + + It will effectively be an alias to + `npm diff --diff=pkg@1.0.0 --diff=pkg@2.0.0`. + +* `npm diff --diff=<semver-a> [--diff=<semver-b>]` (in a package directory): + + Using `npm diff` along with semver-valid version numbers is a shorthand + to compare different versions of the current package. + + It needs to be run from a package directory, such that for a package named + `pkg` running `npm diff --diff=1.0.0 --diff=1.0.1` is the same as running + `npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1`. + + If only a single argument `<version-a>` is provided, then the current local + file system is going to be compared against that version. + + Here's an example comparing two specific versions (published to the + configured registry) of the current project directory: + + ```bash + npm diff --diff=1.0.0 --diff=1.1.0 + ``` + +Note that tag names are not valid `--diff` argument values, if you wish to +compare to a published tag, you must use the `pkg@tagname` syntax. + +#### Filtering files + +It's possible to also specify positional arguments using file names or globs +pattern matching in order to limit the result of diff patches to only a subset +of files for a given package, e.g: + + ```bash + npm diff --diff=pkg@2 ./lib/ CHANGELOG.md + ``` + +In the example above the diff output is only going to print contents of files +located within the folder `./lib/` and changed lines of code within the +`CHANGELOG.md` file. + +### Configuration + +#### diff + +* Type: Array<String> +* Default: null + +Defines npm package specifiers to compare using the `npm diff` command. + +This can be specified up to 2 times. + +#### diff-name-only + +* Type: Boolean +* Default: false + +When set to `true` running `npm diff` only returns the names of the files that +have any difference. + +#### diff-unified + +* Type: Number +* Default: `3` + +The number of lines of context to print in the unified diff format output. + +#### diff-ignore-all-space + +* Type: Boolean +* Default: false + +Ignore whitespace when comparing lines. This ignores differences even if one +line has whitespace where the other line has none. + +#### diff-no-prefix + +* Type: Boolean +* Default: false + +Do not show any source or destination prefix. + +#### diff-src-prefix + +* Type: String +* Default: `"a/"` + +Show the given source prefix in diff patches headers instead of using "a/". + +#### diff-dst-prefix + +* Type: String +* Default: `"b/"` + +Show the given source prefix in diff patches headers instead of using "b/". + +#### diff-text + +* Type: Boolean +* Default: false + +Treat all files as text. + +#### global + +* Default: false +* Type: Boolean + +Uses packages from the global space as a source for comparison. + +#### tag + +* Type: String +* Default: `"latest"` + +The tag used to fetch the tarball that will be compared with the local file +system files when running npm diff with no arguments. + + +## See Also + +* [npm outdated](/commands/npm-outdated) +* [npm install](/commands/npm-install) +* [npm config](/commands/npm-config) +* [npm registry](/using-npm/registry) diff --git a/deps/npm/docs/content/commands/npm-exec.md b/deps/npm/docs/content/commands/npm-exec.md index 3ae30fa0cba..cb3e51c8255 100644 --- a/deps/npm/docs/content/commands/npm-exec.md +++ b/deps/npm/docs/content/commands/npm-exec.md @@ -173,6 +173,28 @@ This resulted in some shifts in its functionality: - The `--shell` option is replaced with `--script-shell`, but maintained in the `npx` executable for backwards compatibility. +### A note on caching + +The npm cli utilizes its internal package cache when using the package +name specified. You can use the following to change how and when the +cli uses this cache. See [`npm cache`](/commands/npm-cache) for more on +how the cache works. + +#### prefer-online + +Forces staleness checks for packages, making the cli look for updates +immediately even if the package is already in the cache. + +#### prefer-offline + +Bypasses staleness checks for packages. Missing data will still be +requested from the server. To force full offline mode, use `offline`. + +#### offline + +Forces full offline mode. Any packages not locally cached will result in +an error. + ### See Also * [npm run-script](/commands/npm-run-script) diff --git a/deps/npm/docs/content/commands/npm-init.md b/deps/npm/docs/content/commands/npm-init.md index 3eac923175b..8a40d90e835 100644 --- a/deps/npm/docs/content/commands/npm-init.md +++ b/deps/npm/docs/content/commands/npm-init.md @@ -71,9 +71,32 @@ Generate it without having it ask any questions: $ npm init -y ``` +### A note on caching + +The npm cli utilizes its internal package cache when using the package +name specified. You can use the following to change how and when the +cli uses this cache. See [`npm cache`](/commands/npm-cache) for more on +how the cache works. + +#### prefer-online + +Forces staleness checks for packages, making the cli look for updates +immediately even if the package is already in the cache. + +#### prefer-offline + +Bypasses staleness checks for packages. Missing data will still be +requested from the server. To force full offline mode, use `offline`. + +#### offline + +Forces full offline mode. Any packages not locally cached will result in +an error. + ### See Also * [init-package-json module](http://npm.im/init-package-json) * [package.json](/configuring-npm/package-json) * [npm version](/commands/npm-version) * [npm scope](/using-npm/scope) +* [npm exec](/commands/npm-exec) diff --git a/deps/npm/docs/content/commands/npm-owner.md b/deps/npm/docs/content/commands/npm-owner.md index 6479f3bdd11..69eba56afd9 100644 --- a/deps/npm/docs/content/commands/npm-owner.md +++ b/deps/npm/docs/content/commands/npm-owner.md @@ -39,4 +39,3 @@ on the command line when changing ownership with `--otp`. * [npm publish](/commands/npm-publish) * [npm registry](/using-npm/registry) * [npm adduser](/commands/npm-adduser) -* [npm disputes](/using-npm/disputes) diff --git a/deps/npm/docs/content/commands/npm-run-script.md b/deps/npm/docs/content/commands/npm-run-script.md index b7ab20a73af..8b89435e1a9 100644 --- a/deps/npm/docs/content/commands/npm-run-script.md +++ b/deps/npm/docs/content/commands/npm-run-script.md @@ -32,7 +32,7 @@ npm run test -- --grep="pattern" ``` The arguments will only be passed to the script specified after ```npm run``` -and not to any pre or post script. +and not to any `pre` or `post` script. The `env` script is a special built-in command that can be used to list environment variables that will be available to the script at runtime. If an @@ -56,7 +56,8 @@ instead of ``` The actual shell your script is run within is platform dependent. By default, -on Unix-like systems it is the `/bin/sh` command, on Windows it is the `cmd.exe`. +on Unix-like systems it is the `/bin/sh` command, on Windows it is +`cmd.exe`. The actual shell referred to by `/bin/sh` also depends on the system. You can customize the shell with the `script-shell` configuration. @@ -73,15 +74,43 @@ If `--scripts-prepend-node-path=auto` is passed (which has been the default in `npm` v3), this is only performed when that `node` executable is not found in the `PATH`. -If you try to run a script without having a `node_modules` directory and it fails, -you will be given a warning to run `npm install`, just in case you've forgotten. +If you try to run a script without having a `node_modules` directory and it +fails, you will be given a warning to run `npm install`, just in case you've +forgotten. -You can use the `--silent` flag to prevent showing `npm ERR!` output on error. +### Configuration + +#### if-present + +* Type: Boolean +* Default: false You can use the `--if-present` flag to avoid exiting with a non-zero exit code when the script is undefined. This lets you run potentially undefined scripts without breaking the execution chain. +#### ignore-scripts + +* Type: Boolean +* Default: false + +Skips running `pre` and `post` scripts. + +#### script-shell + +* Type: String +* Default: `null` + +Optional custom script to use to execute the command. If not defined defaults +to `/bin/sh` on Unix, defaults to `env.comspec` or `cmd.exe` on Windows. + +#### silent + +* Type: Boolean +* Default: false + +You can use the `--silent` flag to prevent showing `npm ERR!` output on error. + ### See Also * [npm scripts](/using-npm/scripts) diff --git a/deps/npm/docs/content/commands/npm-search.md b/deps/npm/docs/content/commands/npm-search.md index 33864d472d4..35178bcb0a5 100644 --- a/deps/npm/docs/content/commands/npm-search.md +++ b/deps/npm/docs/content/commands/npm-search.md @@ -110,13 +110,13 @@ on how the cache works. #### prefer-online -Forced staleness checks for cached searches, making the cli look for +Forces staleness checks for cached searches, making the cli look for updates immediately even for fresh search results. #### prefer-offline -Bypasses staleness checks for cached. Missing data will still be -requested from the server. To force full offline mode, use `offline`. +Bypasses staleness checks for cached searches. Missing data will still +be requested from the server. To force full offline mode, use `offline`. #### offline diff --git a/deps/npm/docs/content/commands/npm-update.md b/deps/npm/docs/content/commands/npm-update.md index 424d686189d..012c8472c93 100644 --- a/deps/npm/docs/content/commands/npm-update.md +++ b/deps/npm/docs/content/commands/npm-update.md @@ -1,7 +1,7 @@ --- title: npm-update section: 1 -description: Update a package +description: Update packages --- ### Synopsis @@ -27,22 +27,11 @@ packages. If no package name is specified, all packages in the specified location (global or local) will be updated. -As of `npm@2.6.1`, the `npm update` will only inspect top-level packages. -Prior versions of `npm` would also recursively inspect all dependencies. -To get the old behavior, use `npm --depth 9999 update`. - -As of `npm@5.0.0`, the `npm update` will change `package.json` to save the -new version as the minimum required dependency. To get the old behavior, -use `npm update --no-save`. - ### Example -IMPORTANT VERSION NOTE: these examples assume `npm@2.6.1` or later. For -older versions of `npm`, you must specify `--depth 0` to get the behavior -described below. - For the examples below, assume that the current package is `app` and it depends -on dependencies, `dep1` (`dep2`, .. etc.). The published versions of `dep1` are: +on dependencies, `dep1` (`dep2`, .. etc.). The published versions of `dep1` +are: ```json { @@ -84,10 +73,10 @@ However, if `app`'s `package.json` contains: } ``` -In this case, running `npm update` will install `dep1@1.1.2`. Even though the `latest` -tag points to `1.2.2`, this version does not satisfy `~1.1.1`, which is equivalent -to `>=1.1.1 <1.2.0`. So the highest-sorting version that satisfies `~1.1.1` is used, -which is `1.1.2`. +In this case, running `npm update` will install `dep1@1.1.2`. Even though the +`latest` tag points to `1.2.2`, this version do not satisfy `~1.1.1`, which is +equivalent to `>=1.1.1 <1.2.0`. So the highest-sorting version that satisfies +`~1.1.1` is used, which is `1.1.2`. #### Caret Dependencies below 1.0.0 @@ -120,7 +109,9 @@ version that satisfies `^0.4.0` (`>= 0.4.0 <0.5.0`) package that is `outdated` -- that is, has a version that is different from `wanted`. -Note: Globally installed packages are treated as if they are installed with a caret semver range specified. So if you require to update to `latest` you may need to run `npm install -g [<pkg>...]` +Note: Globally installed packages are treated as if they are installed with a +caret semver range specified. So if you require to update to `latest` you may +need to run `npm install -g [<pkg>...]` NOTE: If a package has been upgraded to a version newer than `latest`, it will be _downgraded_. diff --git a/deps/npm/docs/content/commands/npm-version.md b/deps/npm/docs/content/commands/npm-version.md index 5f93ef44ae5..0eb814b9899 100644 --- a/deps/npm/docs/content/commands/npm-version.md +++ b/deps/npm/docs/content/commands/npm-version.md @@ -83,37 +83,37 @@ Take the following example: } ``` -This runs all your tests, and proceeds only if they pass. Then runs your `build` script, and +This runs all your tests and proceeds only if they pass. Then runs your `build` script, and adds everything in the `dist` directory to the commit. After the commit, it pushes the new commit and tag up to the server, and deletes the `build/temp` directory. ### Configuration -#### allow-same-version +#### `allow-same-version` -* Default: false +* Default: `false` * Type: Boolean -Prevents throwing an error when `npm version` is used to set the new version +Prevents throwing an error when `npm version` is used to set the new version to the same value as the current version. -#### git-tag-version +#### `git-tag-version` -* Default: true +* Default: `true` * Type: Boolean Commit and tag the version change. -#### commit-hooks +#### `commit-hooks` -* Default: true +* Default: `true` * Type: Boolean Run git commit hooks when committing the version change. -#### sign-git-tag +#### `sign-git-tag` -* Default: false +* Default: `false` * Type: Boolean Pass the `-s` flag to git to sign the tag. @@ -126,5 +126,4 @@ Note that you must have a default GPG key set up in your git config for this to * [npm run-script](/commands/npm-run-script) * [npm scripts](/using-npm/scripts) * [package.json](/configuring-npm/package-json) -* [semver](/using-npm/semver) * [config](/using-npm/config) diff --git a/deps/npm/docs/content/commands/npm-view.md b/deps/npm/docs/content/commands/npm-view.md index 3404c031433..bf09c2ba4f3 100644 --- a/deps/npm/docs/content/commands/npm-view.md +++ b/deps/npm/docs/content/commands/npm-view.md @@ -17,50 +17,48 @@ aliases: info, show, v This command shows data about a package and prints it to the stream referenced by the `outfd` config, which defaults to stdout. -To show the package registry entry for the `connect` package, you can do -this: +As an example, to view information about the `connect` package from the registry, you would run: ```bash npm view connect ``` -The default version is "latest" if unspecified. +The default version is `"latest"` if unspecified. Field names can be specified after the package descriptor. For example, to show the dependencies of the `ronn` package at version -0.3.5, you could do the following: +`0.3.5`, you could do the following: ```bash npm view ronn@0.3.5 dependencies ``` You can view child fields by separating them with a period. -To view the git repository URL for the latest version of npm, you could -do this: +To view the git repository URL for the latest version of `npm`, you would run the following command: ```bash npm view npm repository.url ``` This makes it easy to view information about a dependency with a bit of -shell scripting. For example, to view all the data about the version of -opts that ronn depends on, you can do this: +shell scripting. For example, to view all the data about the version of +`opts` that `ronn` depends on, you could write the following: ```bash npm view opts@$(npm view ronn dependencies.opts) ``` For fields that are arrays, requesting a non-numeric field will return -all of the values from the objects in the list. For example, to get all -the contributor names for the "express" project, you can do this: +all of the values from the objects in the list. For example, to get all +the contributor names for the `express` package, you would run: ```bash npm view express contributors.email ``` You may also use numeric indices in square braces to specifically select -an item in an array field. To just get the email address of the first -contributor in the list, you can do this: +an item in an array field. To just get the email address of the first +contributor in the list, you can run: ```bash npm view express contributors[0].email @@ -75,7 +73,7 @@ npm view express contributors.name contributors.email ``` "Person" fields are shown as a string if they would be shown as an -object. So, for example, this will show the list of npm contributors in +object. So, for example, this will show the list of `npm` contributors in the shortened string format. (See [`package.json`](/configuring-npm/package.json) for more on this.) ```bash @@ -83,12 +81,12 @@ npm view npm contributors ``` If a version range is provided, then data will be printed for every -matching version of the package. This will show which version of jsdom -was required by each matching version of yui3: +matching version of the package. This will show which version of `jsdom` +was required by each matching version of `yui3`: ```bash npm view yui3@'>0.5.4' dependencies.jsdom -``` +``` To show the `connect` package version history, you can do this: @@ -100,15 +98,15 @@ npm view connect versions ### Output If only a single string field for a single version is output, then it -will not be colorized or quoted, so as to enable piping the output to +will not be colorized or quoted, to enable piping the output to another command. If the field is an object, it will be output as a JavaScript object literal. -If the --json flag is given, the outputted fields will be JSON. +If the `--json` flag is given, the outputted fields will be JSON. -If the version range matches multiple versions, than each printed value +If the version range matches multiple versions then each printed value will be prefixed with the version it applies to. -If multiple fields are requested, than each of them are prefixed with +If multiple fields are requested, then each of them is prefixed with the field name. ### See Also diff --git a/deps/npm/docs/content/commands/npm.md b/deps/npm/docs/content/commands/npm.md index dd7da2f18aa..d01146d3704 100644 --- a/deps/npm/docs/content/commands/npm.md +++ b/deps/npm/docs/content/commands/npm.md @@ -20,36 +20,42 @@ npm is the package manager for the Node JavaScript platform. It puts modules in place so that node can find them, and manages dependency conflicts intelligently. -It is extremely configurable to support a wide variety of use cases. -Most commonly, it is used to publish, discover, install, and develop node +It is extremely configurable to support a variety of use cases. Most +commonly, you use it to publish, discover, install, and develop node programs. Run `npm help` to get a list of available commands. ### Important -npm is configured to use npm, Inc.'s public registry at +npm comes preconfigured to use npm's public registry at https://registry.npmjs.org by default. Use of the npm public registry is -subject to terms of use available at https://www.npmjs.com/policies/terms. +subject to terms of use available at +https://www.npmjs.com/policies/terms. -You can configure npm to use any compatible registry you like, and even run -your own registry. Use of someone else's registry may be governed by their -terms of use. +You can configure npm to use any compatible registry you like, and even +run your own registry. Use of someone else's registry is governed by +their terms of use. ### Introduction You probably got npm because you want to install stuff. -Use `npm install blerg` to install the latest version of "blerg". Check out -[`npm install`](/commands/npm-install) for more info. It can do a lot of stuff. +The very first thing you will most likely want to run in any node +program is `npm install` to install its dependencies. -Use the `npm search` command to show everything that's available. -Use `npm ls` to show everything you've installed. +You can also run `npm install blerg` to install the latest version of +"blerg". Check out [`npm install`](/commands/npm-install) for more +info. It can do a lot of stuff. + +Use the `npm search` command to show everything that's available in the +public registry. Use `npm ls` to show everything you've installed. ### Dependencies -If a package references to another package with a git URL, npm depends -on a preinstalled git. +If a package lists a dependency using a git URL, npm will install that +dependency using the [`git`](https://github.com/git-guides/install-git) +command and will generate an error if it is not installed. If one of the packages npm tries to install is a native node module and requires compiling of C++ Code, npm will use @@ -64,20 +70,22 @@ the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki). ### Directories -See [`folders`](/configuring-npm/folders) to learn about where npm puts stuff. +See [`folders`](/configuring-npm/folders) to learn about where npm puts +stuff. In particular, npm has two modes of operation: -* global mode: - npm installs packages into the install prefix at - `prefix/lib/node_modules` and bins are installed in `prefix/bin`. * local mode: npm installs packages into the current project directory, which - defaults to the current working directory. Packages are installed to - `./node_modules`, and bins are installed to `./node_modules/.bin`. + defaults to the current working directory. Packages install to + `./node_modules`, and bins to `./node_modules/.bin`. +* global mode: + npm installs packages into the install prefix at + `$npm_config_prefix/lib/node_modules` and bins to + `$npm_config_prefix/bin`. Local mode is the default. Use `-g` or `--global` on any command to -operate in global mode instead. +run in global mode instead. ### Developer Usage @@ -85,20 +93,22 @@ If you're using npm to develop and publish your code, check out the following help topics: * json: - Make a package.json file. See [`package.json`](/configuring-npm/package-json). + Make a package.json file. See + [`package.json`](/configuring-npm/package-json). * link: - For linking your current working code into Node's path, so that you - don't have to reinstall every time you make a change. Use - `npm link` to do this. + Links your current working code into Node's path, so that you don't + have to reinstall every time you make a change. Use [`npm + link`](/commands/npm-link) to do this. * install: - It's a good idea to install things if you don't need the symbolic link. - Especially, installing other peoples code from the registry is done via - `npm install` + It's a good idea to install things if you don't need the symbolic + link. Especially, installing other peoples code from the registry is + done via [`npm install`](/commands/npm-install) * adduser: - Create an account or log in. Credentials are stored in the - user config file. + Create an account or log in. When you do this, npm will store + credentials in the user config file config file. * publish: - Use the `npm publish` command to upload your code to the registry. + Use the [`npm publish`](/commands/npm-publish`) command to upload your + code to the registry. #### Configuration @@ -108,20 +118,20 @@ npm is extremely configurable. It reads its configuration options from * Command line switches: Set a config with `--key val`. All keys take a value, even if they are booleans (the config parser doesn't know what the options are at - the time of parsing). If no value is provided, then the option is set - to boolean `true`. + the time of parsing). If you do not provide a value (`--key`) then + the option is set to boolean `true`. * Environment Variables: Set any config by prefixing the name in an environment variable with `npm_config_`. For example, `export npm_config_key=val`. * User Configs: - The file at $HOME/.npmrc is an ini-formatted list of configs. If + The file at `$HOME/.npmrc` is an ini-formatted list of configs. If present, it is parsed. If the `userconfig` option is set in the cli - or env, then that will be used instead. + or env, that file will be used instead. * Global Configs: - The file found at ../etc/npmrc (from the node executable, by default - this resolves to /usr/local/etc/npmrc) will be parsed if it is found. - If the `globalconfig` option is set in the cli, env, or user config, - then that file is parsed instead. + The file found at `./etc/npmrc` (relative to the global prefix will be + parsed if it is found. See [`npm prefix`](/commands/npm-prefix) for + more info on the global prefix. If the `globalconfig` option is set + in the cli, env, or user config, then that file is parsed instead. * Defaults: npm's default configuration options are defined in lib/utils/config-defs.js. These must not be changed. @@ -132,15 +142,17 @@ See [`config`](/using-npm/config) for much much more information. Patches welcome! -If you would like to contribute, but don't know what to work on, read -the [contributing guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) -and check the issues list. +If you would like to help, but don't know what to work on, read the +[contributing +guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) and +check the issues list. ### Bugs -When you find issues, please report them: <https://github.com/npm/cli/issues> +When you find issues, please report them: +<https://github.com/npm/cli/issues> -Be sure to follow the template and bug reporting guidelines. +Please be sure to follow the template and bug reporting guidelines. ### Feature Requests @@ -153,8 +165,11 @@ Or suggest formal RFC proposals: * <https://github.com/npm/rfcs> ### See Also + * [npm help](/commands/npm-help) * [package.json](/configuring-npm/package-json) -* [npm install](/commands/npm-install) -* [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) +* [npm config](/commands/npm-config) +* [npm install](/commands/npm-install) +* [npm prefix](/commands/npm-prefix) +* [npm publish](/commands/npm-publish) diff --git a/deps/npm/docs/content/configuring-npm/package-json.md b/deps/npm/docs/content/configuring-npm/package-json.md index caa1e16a326..4b3fd2ba934 100644 --- a/deps/npm/docs/content/configuring-npm/package-json.md +++ b/deps/npm/docs/content/configuring-npm/package-json.md @@ -63,8 +63,6 @@ Version must be parseable by [node-semver](https://github.com/npm/node-semver), which is bundled with npm as a dependency. (`npm install semver` to use it yourself.) -More on version numbers and ranges at [semver](/using-npm/semver). - ### description Put a description in it. It's a string. This helps people discover your @@ -564,8 +562,8 @@ tarball or git URL. **Please do not put test harnesses or transpilers or other "development" time tools in your `dependencies` object.** See `devDependencies`, below. -See [semver](/using-npm/semver) for more details about specifying version -ranges. +See [semver]([/using-npm/semver](https://github.com/npm/node-semver#versions)) +for more details about specifying version ranges. * `version` Must match `version` exactly * `>version` Must be greater than `version` @@ -573,8 +571,8 @@ ranges. * `<version` * `<=version` * `~version` "Approximately equivalent to version" See - [semver](/using-npm/semver) -* `^version` "Compatible with version" See [semver](/using-npm/semver) + [semver](https://github.com/npm/node-semver#versions) +* `^version` "Compatible with version" See [semver](https://github.com/npm/node-semver#versions) * `1.2.x` 1.2.0, 1.2.1, etc., but not 1.3.0 * `http://...` See 'URLs as Dependencies' below * `*` Matches any version @@ -1027,7 +1025,7 @@ npm will default some values based on package contents. ### SEE ALSO -* [semver](/using-npm/semver) +* [semver](https://github.com/npm/node-semver#versions) * [workspaces](/using-npm/workspaces) * [npm init](/commands/npm-init) * [npm version](/commands/npm-version) diff --git a/deps/npm/docs/content/using-npm/config.md b/deps/npm/docs/content/using-npm/config.md index 3a2517d34ef..1e0b2035921 100644 --- a/deps/npm/docs/content/using-npm/config.md +++ b/deps/npm/docs/content/using-npm/config.md @@ -379,6 +379,63 @@ commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`. This is NOT currently honored by some network related commands, eg `dist-tags`, `owner`, etc. +#### diff + +* Default: null +* Type: String, Array, null + +Define arguments to compare in `npm diff`. + +#### diff-name-only + +* Default: false +* Type: Boolean + +Prints only filenames when using `npm diff`. + +#### diff-unified + +* Type: number +* Default: `3` + +The number of lines of context to print in `npm diff`. + +#### diff-ignore-all-space + +* Type: Boolean +* Default: false + +Ignore whitespace when comparing lines in `npm diff. + +#### diff-no-prefix + +* Type: Boolean +* Default: false + +Do not show any source or destination prefix in `npm diff` output. + +#### diff-src-prefix + +* Type: String +* Default: `"a/"` + +Source prefix to be used in `npm diff` output. + +#### diff-dst-prefix + +* Type: String +* Default: `"b/"` + +Destination prefix to be used in `npm diff` output. + +#### diff-text + +* Alias: `-a` +* Type: Boolean +* Default: false + +Treat all files as text in `npm diff`. + #### editor * Default: `EDITOR` environment variable if set, or `"vi"` on Posix, diff --git a/deps/npm/docs/content/using-npm/disputes.md b/deps/npm/docs/content/using-npm/disputes.md deleted file mode 100644 index 04246651592..00000000000 --- a/deps/npm/docs/content/using-npm/disputes.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: disputes -section: 7 -description: Handling Module Name Disputes ---- - -This document describes the steps that you should take to resolve module name -disputes with other npm publishers. It also describes special steps you should -take about names you think infringe your trademarks. - -This document is a clarification of the acceptable behavior outlined in the -[npm Code of Conduct](https://www.npmjs.com/policies/conduct), and nothing in -this document should be interpreted to contradict any aspect of the npm Code of -Conduct. - -### TL;DR - -1. Get the author email with `npm owner ls <pkgname>` -2. Email the author, CC <support@npmjs.com> -3. After a few weeks, if there's no resolution, we'll sort it out. - -Don't squat on package names. Publish code or move out of the way. - -### Description - -There sometimes arise cases where a user publishes a module, and then later, -some other user wants to use that name. Here are some common ways that happens -(each of these is based on actual events.) - -1. Alice writes a JavaScript module `foo`, which is not node-specific. Alice - doesn't use node at all. Yusuf wants to use `foo` in node, so he wraps it in - an npm module. Some time later, Alice starts using node, and wants to take - over management of her program. -2. Yusuf writes an npm module `foo`, and publishes it. Perhaps much later, Alice - finds a bug in `foo`, and fixes it. She sends a pull request to Yusuf, but - Yusuf doesn't have the time to deal with it, because he has a new job and a - new baby and is focused on his new Erlang project, and kind of not involved - with node any more. Alice would like to publish a new `foo`, but can't, - because the name is taken. -3. Yusuf writes a 10-line flow-control library, and calls it `foo`, and - publishes it to the npm registry. Being a simple little thing, it never - really has to be updated. Alice works for Foo Inc, the makers of the - critically acclaimed and widely-marketed `foo` JavaScript toolkit framework. - They publish it to npm as `foojs`, but people are routinely confused when - `npm install foo` is some different thing. -4. Yusuf writes a parser for the widely-known `foo` file format, because he - needs it for work. Then, he gets a new job, and never updates the prototype. - Later on, Alice writes a much more complete `foo` parser, but can't publish, - because Yusuf's `foo` is in the way. - -1. `npm owner ls foo`. This will tell Alice the email address of the owner - (Yusuf). -2. Alice emails Yusuf, explaining the situation **as respectfully as possible**, - and what she would like to do with the module name. She adds the npm support - staff <support@npmjs.com> to the CC list of the email. Mention in the email - that Yusuf can run npm owner `add alice foo` to add Alice as an owner of the - foo package. -3. After a reasonable amount of time, if Yusuf has not responded, or if Yusuf - and Alice can't come to any sort of resolution, email support - <support@npmjs.com> and we'll sort it out. ("Reasonable" is usually at least - 4 weeks.) - -### Reasoning - -In almost every case so far, the parties involved have been able to reach an -amicable resolution without any major intervention. Most people really do want -to be reasonable, and are probably not even aware that they're in your way. - -Module ecosystems are most vibrant and powerful when they are as self-directed -as possible. If an admin one day deletes something you had worked on, then that -is going to make most people quite upset, regardless of the justification. When -humans solve their problems by talking to other humans with respect, everyone -has the chance to end up feeling good about the interaction. - -### Exceptions - -Some things are not allowed, and will be removed without discussion if they are -brought to the attention of the npm registry admins, including but not limited -to: - -1. Malware (that is, a package designed to exploit or harm the machine on which - it is installed). -2. Violations of copyright or licenses (for example, cloning an MIT-licensed - program, and then removing or changing the copyright and license statement). -3. Illegal content. -4. "Squatting" on a package name that you plan to use, but aren't actually - using. Sorry, I don't care how great the name is, or how perfect a fit it is - for the thing that someday might happen. If someone wants to use it today, - and you're just taking up space with an empty tarball, you're going to be - evicted. -5. Putting empty packages in the registry. Packages must have SOME - functionality. It can be silly, but it can't be nothing. (See also: - squatting.) -6. Doing weird things with the registry, like using it as your own personal - application database or otherwise putting non-packagey things into it. -7. Other things forbidden by the npm - [Code of Conduct](https://www.npmjs.com/policies/conduct) such as hateful - language, pornographic content, or harassment. - -If you see bad behavior like this, please report it to <abuse@npmjs.com> right -away. **You are never expected to resolve abusive behavior on your own. We are -here to help.** - -### Trademarks - -If you think another npm publisher is infringing your trademark, such as by -using a confusingly similar package name, email <abuse@npmjs.com> with a link to -the package or user account on [https://www.npmjs.com/](https://www.npmjs.com/). -Attach a copy of your trademark registration certificate. - -If we see that the package's publisher is intentionally misleading others by -misusing your registered mark without permission, we will transfer the package -name to you. Otherwise, we will contact the package publisher and ask them to -clear up any confusion with changes to their package's `README` file or -metadata. - -### Changes - -This is a living document and may be updated from time to time. Please refer to -the [git history for this document](https://github.com/npm/cli/commits/latest/doc/misc/npm-disputes.md) -to view the changes. - -### License - -Copyright (C) npm, Inc., All rights reserved - -This document may be reused under a Creative Commons Attribution-ShareAlike -License. - -### See also - -* [npm registry](/using-npm/registry) -* [npm owner](/commands/npm-owner) diff --git a/deps/npm/docs/content/using-npm/registry.md b/deps/npm/docs/content/using-npm/registry.md index b7a18712f8b..c07fa7a48e8 100644 --- a/deps/npm/docs/content/using-npm/registry.md +++ b/deps/npm/docs/content/using-npm/registry.md @@ -10,7 +10,7 @@ To resolve packages by name and version, npm talks to a registry website that implements the CommonJS Package Registry specification for reading package info. -npm is configured to use npm, Inc.'s public registry at +npm is configured to use the **npm public registry** at <https://registry.npmjs.org> by default. Use of the npm public registry is subject to terms of use available at <https://www.npmjs.com/policies/terms>. @@ -23,9 +23,7 @@ write APIs as well, to allow for publishing packages and managing user account information. The npm public registry is powered by a CouchDB database, -of which there is a public mirror at -<https://skimdb.npmjs.com/registry>. The code for the couchapp is -available at <https://github.com/npm/npm-registry-couchapp>. +of which there is a public mirror at <https://skimdb.npmjs.com/registry>. The registry URL used is determined by the scope of the package (see [`scope`](/using-npm/scope). If no scope is specified, the default registry is used, which is @@ -55,44 +53,18 @@ about your environment: The npm registry does not try to correlate the information in these headers with any authenticated accounts that may be used in the same requests. -### Can I run my own private registry? +### How can I prevent my package from being published in the official registry? -Yes! - -The easiest way is to replicate the couch database, and use the same (or -similar) design doc to implement the APIs. - -If you set up continuous replication from the official CouchDB, and then -set your internal CouchDB as the registry config, then you'll be able -to read any published packages, in addition to your private ones, and by -default will only publish internally. - -If you then want to publish a package for the whole world to see, you can -simply override the `--registry` option for that `publish` command. - -### I don't want my package published in the official registry. It's private. - -Set `"private": true` in your package.json to prevent it from being +Set `"private": true` in your `package.json` to prevent it from being published at all, or `"publishConfig":{"registry":"http://my-internal-registry.local"}` -to force it to be published only to your internal registry. +to force it to be published only to your internal/private registry. See [`package.json`](/configuring-npm/package-json) for more info on what goes in the package.json file. -### Will you replicate from my registry into the public one? - -No. If you want things to be public, then publish them into the public -registry using npm. What little security there is would be for nought -otherwise. - -### Do I have to use couchdb to build a registry that npm can talk to? - -No, but it's way easier. Basically, yes, you do, or you have to -effectively implement the entire CouchDB API anyway. - -### Is there a website or something to see package docs and such? +### Where can I find my own, & other's, published packages? -Yes, head over to <https://www.npmjs.com/> +<https://www.npmjs.com/> ### See also @@ -100,4 +72,3 @@ Yes, head over to <https://www.npmjs.com/> * [config](/using-npm/config) * [npmrc](/configuring-npm/npmrc) * [npm developers](/using-npm/developers) -* [npm disputes](/using-npm/disputes) diff --git a/deps/npm/docs/content/using-npm/removal.md b/deps/npm/docs/content/using-npm/removal.md index 7b35460b595..c5e13b6741b 100644 --- a/deps/npm/docs/content/using-npm/removal.md +++ b/deps/npm/docs/content/using-npm/removal.md @@ -58,8 +58,6 @@ modules. To track those down, you can do the following: find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ; ``` -(This is also in the README file.) - ### See also * [npm uninstall](/commands/npm-uninstall) diff --git a/deps/npm/docs/content/using-npm/semver.md b/deps/npm/docs/content/using-npm/semver.md deleted file mode 100644 index 55141ed537c..00000000000 --- a/deps/npm/docs/content/using-npm/semver.md +++ /dev/null @@ -1,415 +0,0 @@ ---- -title: semver -section: 7 -description: The semantic versioner for npm ---- - -## Install - -```bash -npm install --save semver -```` - -## Usage - -As a node module: - -```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.minVersion('>=1.0.0') // '1.0.0' -semver.valid(semver.coerce('v2')) // '2.0.0' -semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7' -``` - -As a command-line utility: - -``` -$ semver -h - -A JavaScript implementation of the https://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 - --p --include-prerelease - Always include prerelease versions in range matching - --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. -``` - -## Versions - -A "version" is described by the `v2.0.0` specification found at -<https://semver.org/>. - -A leading `"="` or `"v"` character is stripped off and ignored. - -## Ranges - -A `version range` is a set of `comparators` which specify versions -that satisfy the range. - -A `comparator` is composed of an `operator` and a `version`. The set -of primitive `operators` is: - -* `<` Less than -* `<=` Less than or equal to -* `>` Greater than -* `>=` Greater than or equal to -* `=` Equal. If no operator is specified, then equality is assumed, - so this operator is optional, but MAY be included. - -For example, the comparator `>=1.2.7` would match the versions -`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6` -or `1.1.0`. - -Comparators can be joined by whitespace to form a `comparator set`, -which is satisfied by the **intersection** of all of the comparators -it includes. - -A range is composed of one or more comparator sets, joined by `||`. A -version matches a range if and only if every comparator in at least -one of the `||`-separated comparator sets is satisfied by the version. - -For example, the range `>=1.2.7 <1.3.0` would match the versions -`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`, -or `1.1.0`. - -The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`, -`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`. - -### Prerelease Tags - -If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then -it will only be allowed to satisfy comparator sets if at least one -comparator with the same `[major, minor, patch]` tuple also has a -prerelease tag. - -For example, the range `>1.2.3-alpha.3` would be allowed to match the -version `1.2.3-alpha.7`, but it would *not* be satisfied by -`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater -than" `1.2.3-alpha.3` according to the SemVer sort rules. The version -range only accepts prerelease tags on the `1.2.3` version. The -version `3.4.5` *would* satisfy the range, because it does not have a -prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`. - -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. - -Second, a user who has opted into using a prerelease version has -clearly indicated the intent to use *that specific* 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 *next* set of prerelease versions. - -Note that this behavior can be suppressed (treating all prerelease -versions as if they were normal versions, for the purpose of range -matching) by setting the `includePrerelease` flag on the options -object to any -[functions](https://github.com/npm/node-semver#functions) that do -range matching. - -#### Prerelease Identifiers - -The method `.inc` takes an additional `identifier` string argument that -will append the value of the string as a prerelease identifier: - -```javascript -semver.inc('1.2.3', 'prerelease', 'beta') -// '1.2.4-beta.0' -``` - -command-line example: - -```bash -$ semver 1.2.3 -i prerelease --preid beta -1.2.4-beta.0 -``` - -Which then can be used to increment further: - -```bash -$ semver 1.2.4-beta.0 -i prerelease -1.2.4-beta.1 -``` - -### Advanced Range Syntax - -Advanced range syntax desugars to primitive comparators in -deterministic ways. - -Advanced ranges may be combined in the same way as primitive -comparators using white space or `||`. - -#### Hyphen Ranges `X.Y.Z - A.B.C` - -Specifies an inclusive set. - -* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` - -If a partial version is provided as the first version in the inclusive -range, then the missing pieces are replaced with zeroes. - -* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4` - -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. - -* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0` -* `1.2.3 - 2` := `>=1.2.3 <3.0.0` - -#### X-Ranges `1.2.x` `1.X` `1.2.*` `*` - -Any of `X`, `x`, or `*` may be used to "stand in" for one of the -numeric values in the `[major, minor, patch]` tuple. - -* `*` := `>=0.0.0` (Any version satisfies) -* `1.x` := `>=1.0.0 <2.0.0` (Matching major version) -* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions) - -A partial version range is treated as an X-Range, so the special -character is in fact optional. - -* `""` (empty string) := `*` := `>=0.0.0` -* `1` := `1.x.x` := `>=1.0.0 <2.0.0` -* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0` - -#### Tilde Ranges `~1.2.3` `~1.2` `~1` - -Allows patch-level changes if a minor version is specified on the -comparator. Allows minor-level changes if not. - -* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0` -* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`) -* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`) -* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0` -* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`) -* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`) -* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in - the `1.2.3` version will be allowed, if they are greater than or - equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but - `1.2.4-beta.2` would not, because it is a prerelease of a - different `[major, minor, patch]` tuple. - -#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4` - -Allows changes that do not modify the left-most non-zero digit in the -`[major, minor, patch]` tuple. In other words, this allows patch and -minor updates for versions `1.0.0` and above, patch updates for -versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`. - -Many authors treat a `0.x` version as if the `x` were the major -"breaking-change" indicator. - -Caret ranges are ideal when an author may make breaking changes -between `0.2.4` and `0.3.0` releases, which is a common practice. -However, it presumes that there will *not* be breaking changes between -`0.2.4` and `0.2.5`. It allows for changes that are presumed to be -additive (but non-breaking), according to commonly observed practices. - -* `^1.2.3` := `>=1.2.3 <2.0.0` -* `^0.2.3` := `>=0.2.3 <0.3.0` -* `^0.0.3` := `>=0.0.3 <0.0.4` -* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in - the `1.2.3` version will be allowed, if they are greater than or - equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but - `1.2.4-beta.2` would not, because it is a prerelease of a - different `[major, minor, patch]` tuple. -* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the - `0.0.3` version *only* will be allowed, if they are greater than or - equal to `beta`. So, `0.0.3-pr.2` would be allowed. - -When parsing caret ranges, a missing `patch` value desugars to the -number `0`, but will allow flexibility within that value, even if the -major and minor versions are both `0`. - -* `^1.2.x` := `>=1.2.0 <2.0.0` -* `^0.0.x` := `>=0.0.0 <0.1.0` -* `^0.0` := `>=0.0.0 <0.1.0` - -A missing `minor` and `patch` values will desugar to zero, but also -allow flexibility within those values, even if the major version is -zero. - -* `^1.x` := `>=1.0.0 <2.0.0` -* `^0.x` := `>=0.0.0 <1.0.0` - -### Range Grammar - -Putting all this together, here is a Backus-Naur grammar for ranges, -for the benefit of parser authors: - -```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]+ -``` - -## Functions - -All methods and classes take a final `options` object argument. All -options in this object are `false` by default. The options supported -are: - -- `loose` Be more forgiving about not-quite-valid semver strings. - (Any resulting output will always be 100% strict compliant, of - course.) For backwards compatibility reasons, if the `options` - argument is a boolean value instead of an object, it is interpreted - to be the `loose` param. -- `includePrerelease` Set to suppress the [default - behavior](https://github.com/npm/node-semver#prerelease-tags) of - excluding prerelease tagged versions from ranges unless they are - explicitly opted into. - -Strict-mode Comparators and Ranges will be strict about the SemVer -strings that they parse. - -* `valid(v)`: Return the parsed version, or null if it's not valid. -* `inc(v, release)`: Return the version incremented by the release - type (`major`, `premajor`, `minor`, `preminor`, `patch`, - `prepatch`, or `prerelease`), or null if it's not valid - * `premajor` in one call will bump the version up to the next major - version and down to a prerelease of that major version. - `preminor`, and `prepatch` work the same way. - * If called from a non-prerelease version, the `prerelease` will work the - same as `prepatch`. It increments the patch version, then makes a - prerelease. If the input version is already a prerelease it simply - increments it. -* `prerelease(v)`: Returns an array of prerelease components, or null - if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]` -* `major(v)`: Return the major version number. -* `minor(v)`: Return the minor version number. -* `patch(v)`: Return the patch version number. -* `intersects(r1, r2, loose)`: Return true if the two supplied ranges - or comparators intersect. -* `parse(v)`: Attempt to parse a string as a semantic version, returning either - a `SemVer` object or `null`. - -### Comparison - -* `gt(v1, v2)`: `v1 > v2` -* `gte(v1, v2)`: `v1 >= v2` -* `lt(v1, v2)`: `v1 < v2` -* `lte(v1, v2)`: `v1 <= v2` -* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent, - even if they're not the exact same string. You already know how to - compare strings. -* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`. -* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call - the corresponding function above. `"==="` and `"!=="` do simple - string comparison, but are included for completeness. Throws if an - invalid comparison string is provided. -* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if - `v2` is greater. Sorts in ascending order if passed to `Array.sort()`. -* `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions - in descending order when passed to `Array.sort()`. -* `diff(v1, v2)`: Returns difference between two versions by the release type - (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`), - or null if the versions are the same. - -### Comparators - -* `intersects(comparator)`: Return true if the comparators intersect - -### Ranges - -* `validRange(range)`: Return the valid range or null if it's not valid -* `satisfies(version, range)`: Return true if the version satisfies the - range. -* `maxSatisfying(versions, range)`: Return the highest version in the list - that satisfies the range, or `null` if none of them do. -* `minSatisfying(versions, range)`: Return the lowest version in the list - that satisfies the range, or `null` if none of them do. -* `minVersion(range)`: Return the lowest version that can possibly match - the given range. -* `gtr(version, range)`: Return `true` if version is greater than all the - versions possible in the range. -* `ltr(version, range)`: Return `true` if version is less than all the - versions possible in the range. -* `outside(version, range, hilo)`: Return true if the version is outside - the bounds of the range in either the high or low direction. The - `hilo` argument must be either the string `'>'` or `'<'`. (This is - the function called by `gtr` and `ltr`.) -* `intersects(range)`: Return true if any of the ranges comparators intersect - -Note that, since ranges may be non-contiguous, a version might not be -greater than a range, less than a range, *or* satisfy a range! For -example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9` -until `2.0.0`, so the version `1.2.10` would not be greater than the -range (because `2.0.1` satisfies, which is higher), nor less than the -range (since `1.2.8` satisfies, which is lower), and it also does not -satisfy the range. - -If you want to know if a version satisfies or does not satisfy a -range, use the `satisfies(version, range)` function. - -### Coercion - -* `coerce(version)`: Coerces a string to semver if possible - -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., `1`, -`1.2`, `1.2.3`) up to the max permitted length (256 characters). Longer -versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`). All -surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes -`3.4.0`). Only text which lacks digits will fail coercion (`version one` -is not valid). The maximum length for any semver component considered for -coercion is 16 characters; longer components will be ignored -(`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any -semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value -components are invalid (`9999999999999999.4.7.4` is likely invalid). |