From c58cea5a163cd5d7133e00fdf257325ce3807c09 Mon Sep 17 00:00:00 2001 From: Kat Marchán Date: Sun, 28 May 2017 21:04:08 -0700 Subject: deps: upgrade npm to 5.0.0 PR-URL: https://github.com/nodejs/node/pull/13276 Reviewed-By: James M Snell Reviewed-By: Colin Ihrig Reviewed-By: Jeremiah Senkpiel --- deps/npm/man/man1/npm-cache.1 | 67 ++++++---- deps/npm/man/man1/npm-install.1 | 124 ++++++++++++----- deps/npm/man/man1/npm-ls.1 | 2 +- deps/npm/man/man1/npm-publish.1 | 4 + deps/npm/man/man1/npm-shrinkwrap.1 | 229 ++------------------------------ deps/npm/man/man1/npm.1 | 2 +- deps/npm/man/man5/npm-package-locks.5 | 183 +++++++++++++++++++++++++ deps/npm/man/man5/npm-shrinkwrap.json.5 | 32 +++++ deps/npm/man/man5/package-lock.json.5 | 144 ++++++++++++++++++++ deps/npm/man/man7/npm-config.7 | 35 ++++- deps/npm/man/man7/npm-index.7 | 11 +- deps/npm/man/man7/npm-scripts.7 | 18 ++- 12 files changed, 560 insertions(+), 291 deletions(-) create mode 100644 deps/npm/man/man5/npm-package-locks.5 create mode 100644 deps/npm/man/man5/npm-shrinkwrap.json.5 create mode 100644 deps/npm/man/man5/package-lock.json.5 (limited to 'deps/npm/man') diff --git a/deps/npm/man/man1/npm-cache.1 b/deps/npm/man/man1/npm-cache.1 index 2da4282950..cc8b1e2fae 100644 --- a/deps/npm/man/man1/npm-cache.1 +++ b/deps/npm/man/man1/npm-cache.1 @@ -10,10 +10,10 @@ npm cache add npm cache add npm cache add @ -npm cache ls [] - npm cache clean [] aliases: npm cache clear, npm cache rm + +npm cache verify .fi .RE .SH DESCRIPTION @@ -26,40 +26,45 @@ Add the specified package to the local cache\. This command is primarily intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly\. .IP \(bu 2 -ls: -Show the data in the cache\. Argument is a path to show in the cache -folder\. Works a bit like the \fBfind\fP program, but limited by the -\fBdepth\fP config\. -.IP \(bu 2 clean: -Delete data out of the cache folder\. If an argument is provided, then -it specifies a subpath to delete\. If no argument is provided, then -the entire cache is deleted\. +Delete all data out of the cache folder\. +.IP \(bu 2 +verify: +Verify the contents of the cache folder, garbage collecting any unneeded data, +and verifying the integrity of the cache index and all cached data\. .RE .SH DETAILS .P -npm stores cache data in the directory specified in \fBnpm config get cache\fP\|\. -For each package that is added to the cache, three pieces of information are -stored in \fB{cache}/{name}/{version}\fP: -.RS 0 -.IP \(bu 2 -\|\.\.\./package/package\.json: -The package\.json file, as npm sees it\. -.IP \(bu 2 -\|\.\.\./package\.tgz: -The tarball for that version\. - -.RE +npm stores cache data in an opaque directory within the configured \fBcache\fP, +named \fB_cacache\fP\|\. This directory is a \fBcacache\fP\-based content\-addressable cache +that stores all http request data as well as other package\-related data\. This +directory is primarily accessed through \fBpacote\fP, the library responsible for +all package fetching as of npm@5\. +.P +All data that passes through the cache is fully verified for integrity on both +insertion and extraction\. Cache corruption will either trigger an error, or +signal to \fBpacote\fP that the data must be refetched, which it will do +automatically\. For this reason, it should never be necessary to clear the cache +for any reason other than reclaiming disk space, thus why \fBclean\fP now requires +\fB\-\-force\fP to run\. +.P +There is currently no method exposed through npm to inspect or directly manage +the contents of this cache\. In order to access it, \fBcacache\fP must be used +directly\. .P -Additionally, whenever a registry request is made, a \fB\|\.cache\.json\fP file -is placed at the corresponding URI, to store the ETag and the requested -data\. This is stored in \fB{cache}/{hostname}/{path}/\.cache\.json\fP\|\. +npm will not remove data by itself: the cache will grow as new packages are +installed\. +.SH A NOTE ABOUT THE CACHE'S DESIGN .P -Commands that make non\-essential registry requests (such as \fBsearch\fP and -\fBview\fP, or the completion scripts) generally specify a minimum timeout\. -If the \fB\|\.cache\.json\fP file is younger than the specified timeout, then -they do not make an HTTP request to the registry\. +The npm cache is strictly a cache: it should not be relied upon as a persistent +and reliable data store for package data\. npm makes no guarantee that a +previously\-cached piece of data will be available later, and will automatically +delete corrupted contents\. The primary guarantee that the cache makes is that, +if it does return data, that data will be exactly the data that was inserted\. +.P +To run an offline verification of existing cache contents, use \fBnpm cache +verify\fP\|\. .SH CONFIGURATION .SS cache .P @@ -82,6 +87,10 @@ npm help install npm help publish .IP \(bu 2 npm help pack +.IP \(bu 2 +https://npm\.im/cacache +.IP \(bu 2 +https://npm\.im/pacote .RE diff --git a/deps/npm/man/man1/npm-install.1 b/deps/npm/man/man1/npm-install.1 index 2bacec4055..2dca6a4b8f 100644 --- a/deps/npm/man/man1/npm-install.1 +++ b/deps/npm/man/man1/npm-install.1 @@ -10,19 +10,22 @@ npm install [<@scope>/] npm install [<@scope>/]@ npm install [<@scope>/]@ npm install [<@scope>/]@ +npm install :/ +npm install npm install npm install npm install alias: npm i -common options: [\-S|\-\-save|\-D|\-\-save\-dev|\-O|\-\-save\-optional] [\-E|\-\-save\-exact] [\-B|\-\-save\-bundle] [\-\-dry\-run] +common options: [\-P|\-\-save\-prod|\-D|\-\-save\-dev|\-O|\-\-save\-optional] [\-E|\-\-save\-exact] [\-B|\-\-save\-bundle] [\-\-no\-save] [\-\-dry\-run] .fi .RE .SH DESCRIPTION .P This command installs a package, and any packages that it depends on\. If the -package has a shrinkwrap file, the installation of dependencies will be driven -by that\. See npm help shrinkwrap\. +package has a package\-lock or shrinkwrap file, the installation of dependencies +will be driven by that, with an \fBnpm\-shrinkwrap\.json\fP taking precedence if both +files exist\. See npm help 5 package\-lock\.json and npm help shrinkwrap\. .P A \fBpackage\fP is: .RS 0 @@ -61,12 +64,16 @@ after packing it up into a tarball (b)\. \fBdevDependencies\fP\|\. .IP \(bu 2 \fBnpm install \fP: - Install a package that is sitting in a folder on the filesystem\. + Install the package in the directory as a symlink in the current project\. + Its dependencies will be installed before it's linked\. If \fB\fP sits + inside the root of your project, its dependencies may be hoisted to the + toplevel \fBnode_modules\fP as they would for other types of dependencies\. .IP \(bu 2 \fBnpm install \fP: Install a package that is sitting on the filesystem\. Note: if you just want to link a dev directory into your npm root, you can do this more easily by - using \fBnpm link\fP\|\. + using \fBnpm link\fP\|\. The filename \fImust\fR use \fB\|\.tar\fP, \fB\|\.tar\.gz\fP, or \fB\|\.tgz\fP as + the extension\. Example: .P .RS 2 @@ -86,11 +93,11 @@ after packing it up into a tarball (b)\. .fi .RE .IP \(bu 2 -\fBnpm install [<@scope>/] [\-S|\-\-save|\-D|\-\-save\-dev|\-O|\-\-save\-optional]\fP: +\fBnpm install [<@scope>/]\fP: Do a \fB@\fP install, where \fB\fP is the "tag" config\. (See npm help 7 \fBnpm\-config\fP\|\. The config's default value is \fBlatest\fP\|\.) - In most cases, this will install the latest version - of the module published on npm\. + In most cases, this will install the version of the modules tagged as + \fBlatest\fP on the npm registry\. Example: .P .RS 2 @@ -98,15 +105,24 @@ after packing it up into a tarball (b)\. npm install sax .fi .RE - \fBnpm install\fP takes 3 exclusive, optional flags which save or update - the package version in your main package\.json: + \fBnpm install\fP saves any specified packages into \fBdependencies\fP by default\. + Additionally, you can control where and how they get saved with some + additional flags: .RS 0 .IP \(bu 2 -\fB\-S, \-\-save\fP: Package will appear in your \fBdependencies\fP\|\. +\fB\-P, \-\-save\-prod\fP: Package will appear in your \fBdependencies\fP\|\. This is the +.P +.RS 2 +.nf + default unless `\-D` or `\-O` are present\. +.fi +.RE .IP \(bu 2 \fB\-D, \-\-save\-dev\fP: Package will appear in your \fBdevDependencies\fP\|\. .IP \(bu 2 \fB\-O, \-\-save\-optional\fP: Package will appear in your \fBoptionalDependencies\fP\|\. +.IP \(bu 2 +\fB\-\-no\-save\fP: Prevents saving to \fBdependencies\fP\|\. When using any of the above options to save dependencies to your package\.json, there are two additional, optional flags: .IP \(bu 2 @@ -115,8 +131,8 @@ exact version rather than using npm's default semver range operator\. .IP \(bu 2 \fB\-B, \-\-save\-bundle\fP: Saved dependencies will also be added to your \fBbundleDependencies\fP list\. -Further, if you have an \fBnpm\-shrinkwrap\.json\fP then it will be updated as -well\. +Further, if you have an \fBnpm\-shrinkwrap\.json\fP or \fBpackage\-lock\.json\fP then it +will be updated as well\. \fB\fP is optional\. The package will be downloaded from the registry associated with the specified scope\. If no registry is associated with the given scope the default registry is assumed\. See npm help 7 \fBnpm\-scope\fP\|\. @@ -127,13 +143,13 @@ Examples: .P .RS 2 .nf -npm install sax \-\-save +npm install sax npm install githubname/reponame npm install @myorg/privatepackage npm install node\-tap \-\-save\-dev npm install dtrace\-provider \-\-save\-optional -npm install readable\-stream \-\-save \-\-save\-exact -npm install ansi\-regex \-\-save \-\-save\-bundle +npm install readable\-stream \-\-save\-exact +npm install ansi\-regex \-\-save\-bundle .fi .RE @@ -190,21 +206,29 @@ fetch the package by name if it is not valid\. .RE .IP \(bu 2 \fBnpm install \fP: - Installs the package from the hosted git provider, cloning it with - \fBgit\fP\|\. First it tries via the https (git with github) and if that fails, via ssh\. + Installs the package from the hosted git provider, cloning it with \fBgit\fP\|\. + For a full git remote url, only that URL will be attempted\. .P .RS 2 .nf - ://[[:]@][:][:][/][#] + ://[[:]@][:][:][/][# | #semver:] .fi .RE - \fB\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, \fBgit+https\fP, - or \fBgit+file\fP\|\. - If no \fB\fP is specified, then \fBmaster\fP is used\. - If the repository makes use of submodules, those submodules will - be cloned as well\. - The following git environment variables are recognized by npm and will be added - to the environment when running git: + \fB\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, \fBgit+https\fP, or + \fBgit+file\fP\|\. + If \fB#\fP is provided, it will be used to clone exactly that + commit\. If the commit\-ish has the format \fB#semver:\fP, \fB\fP can + be any valid semver range or exact version, and npm will look for any tags + or refs matching that range in the remote repository, much as it would for a + registry dependency\. If neither \fB#\fP or \fB#semver:\fP is + specified, then \fBmaster\fP is used\. + If the repository makes use of submodules, those submodules will be cloned + as well\. + If the package being installed contains a \fBprepare\fP script, its + \fBdependencies\fP and \fBdevDependencies\fP will be installed, and the prepare + script will be run, before the package is packaged and installed\. + The following git environment variables are recognized by npm and will be + added to the environment when running git: .RS 0 .IP \(bu 2 \fBGIT_ASKPASS\fP @@ -226,6 +250,7 @@ Examples: .RS 2 .nf npm install git+ssh://git@github\.com:npm/npm\.git#v1\.0\.27 +npm install git+ssh://git@github\.com:npm/npm#semver:^5\.0 npm install git+https://isaacs@github\.com/npm/npm\.git npm install git://github\.com/npm/npm\.git#v1\.0\.27 GIT_SSH_COMMAND='ssh \-i ~/\.ssh/custom_ident' npm install git+ssh://git@github\.com:npm/npm\.git @@ -239,7 +264,15 @@ GIT_SSH_COMMAND='ssh \-i ~/\.ssh/custom_ident' npm install git+ssh://git@github\ \fBnpm install github:/[#]\fP: Install the package at \fBhttps://github\.com/githubname/githubrepo\fP by attempting to clone it using \fBgit\fP\|\. - If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\. + If \fB#\fP is provided, it will be used to clone exactly that + commit\. If the commit\-ish has the format \fB#semver:\fP, \fB\fP can + be any valid semver range or exact version, and npm will look for any tags + or refs matching that range in the remote repository, much as it would for a + registry dependency\. If neither \fB#\fP or \fB#semver:\fP is + specified, then \fBmaster\fP is used\. + As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will + be installed if the package has a \fBprepare\fP script, before the package is + done installing\. Examples: .P .RS 2 @@ -249,11 +282,13 @@ GIT_SSH_COMMAND='ssh \-i ~/\.ssh/custom_ident' npm install git+ssh://git@github\ .fi .RE .IP \(bu 2 -\fBnpm install gist:[/][#]\fP: +\fBnpm install gist:[/][#|#semver:]\fP: Install the package at \fBhttps://gist\.github\.com/gistID\fP by attempting to clone it using \fBgit\fP\|\. The GitHub username associated with the gist is - optional and will not be saved in \fBpackage\.json\fP if \fB\-S\fP or \fB\-\-save\fP is used\. - If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\. + optional and will not be saved in \fBpackage\.json\fP\|\. + As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will + be installed if the package has a \fBprepare\fP script, before the package is + done installing\. Example: .P .RS 2 @@ -265,7 +300,15 @@ GIT_SSH_COMMAND='ssh \-i ~/\.ssh/custom_ident' npm install git+ssh://git@github\ \fBnpm install bitbucket:/[#]\fP: Install the package at \fBhttps://bitbucket\.org/bitbucketname/bitbucketrepo\fP by attempting to clone it using \fBgit\fP\|\. - If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\. + If \fB#\fP is provided, it will be used to clone exactly that + commit\. If the commit\-ish has the format \fB#semver:\fP, \fB\fP can + be any valid semver range or exact version, and npm will look for any tags + or refs matching that range in the remote repository, much as it would for a + registry dependency\. If neither \fB#\fP or \fB#semver:\fP is + specified, then \fBmaster\fP is used\. + As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will + be installed if the package has a \fBprepare\fP script, before the package is + done installing\. Example: .P .RS 2 @@ -277,12 +320,21 @@ GIT_SSH_COMMAND='ssh \-i ~/\.ssh/custom_ident' npm install git+ssh://git@github\ \fBnpm install gitlab:/[#]\fP: Install the package at \fBhttps://gitlab\.com/gitlabname/gitlabrepo\fP by attempting to clone it using \fBgit\fP\|\. - If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\. + If \fB#\fP is provided, it will be used to clone exactly that + commit\. If the commit\-ish has the format \fB#semver:\fP, \fB\fP can + be any valid semver range or exact version, and npm will look for any tags + or refs matching that range in the remote repository, much as it would for a + registry dependency\. If neither \fB#\fP or \fB#semver:\fP is + specified, then \fBmaster\fP is used\. + As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will + be installed if the package has a \fBprepare\fP script, before the package is + done installing\. Example: .P .RS 2 .nf npm install gitlab:mygitlabuser/myproject + npm install gitlab:myusr/myproj#semver:^5\.0 .fi .RE @@ -322,7 +374,7 @@ global \fBnode_modules\fP folder\. Only your direct dependencies will show in \fBnode_modules\fP and everything they depend on will be flattened in their \fBnode_modules\fP folders\. This obviously will eliminate some deduping\. .P -The \fB\-\-ignore\-scripts\fP argument will cause npm to not execute any +The \fB\-\-ignore\-scripts\fP argument will cause npm to not execute any scripts defined in the package\.json\. See npm help 7 \fBnpm\-scripts\fP\|\. .P The \fB\-\-legacy\-bundling\fP argument will cause npm to install the package such @@ -339,7 +391,7 @@ The \fB\-\-no\-optional\fP argument will prevent optional dependencies from being installed\. .P The \fB\-\-no\-shrinkwrap\fP argument, which will ignore an available -shrinkwrap file and use the package\.json instead\. +package lock or shrinkwrap file and use the package\.json instead\. .P The \fB\-\-nodedir=/path/to/node/source\fP argument will allow npm to find the node source code so that npm can compile native modules\. @@ -397,7 +449,9 @@ A .RE .P Because B's D@1 will be installed in the top level, C now has to install D@2 -privately for itself\. +privately for itself\. This algorithm is deterministic, but different trees may +be produced if two dependencies are requested for installation in a different +order\. .P See npm help 5 folders for a more detailed description of the specific folder structures that npm creates\. diff --git a/deps/npm/man/man1/npm-ls.1 b/deps/npm/man/man1/npm-ls.1 index c886db5dc4..31cbd387aa 100644 --- a/deps/npm/man/man1/npm-ls.1 +++ b/deps/npm/man/man1/npm-ls.1 @@ -22,7 +22,7 @@ For example, running \fBnpm ls promzard\fP in npm's source tree will show: .P .RS 2 .nf -npm@5.0.0-beta.56 /path/to/npm +npm@5.0.0 /path/to/npm └─┬ init\-package\-json@0\.0\.4 └── promzard@0\.1\.5 .fi diff --git a/deps/npm/man/man1/npm-publish.1 b/deps/npm/man/man1/npm-publish.1 index 603031a4e6..603c79da7f 100644 --- a/deps/npm/man/man1/npm-publish.1 +++ b/deps/npm/man/man1/npm-publish.1 @@ -53,6 +53,10 @@ Once a package is published with a given name and version, that specific name and version combination can never be used again, even if it is removed with npm help unpublish\. .P +As of \fBnpm@5\fP, both a sha1sum and an integrity field with a sha512sum of the +tarball will be submitted to the registry during publication\. Subsequent +installs will use the strongest supported algorithm to verify downloads\. +.P For a "dry run" that does everything except actually publishing to the registry, see npm help \fBnpm\-pack\fP, which figures out the files to be included and packs them into a tarball to be uploaded to the registry\. diff --git a/deps/npm/man/man1/npm-shrinkwrap.1 b/deps/npm/man/man1/npm-shrinkwrap.1 index e36981c421..08ce497d20 100644 --- a/deps/npm/man/man1/npm-shrinkwrap.1 +++ b/deps/npm/man/man1/npm-shrinkwrap.1 @@ -1,6 +1,6 @@ .TH "NPM\-SHRINKWRAP" "1" "May 2017" "" "" .SH "NAME" -\fBnpm-shrinkwrap\fR \- Lock down dependency versions +\fBnpm-shrinkwrap\fR \- Lock down dependency versions for publication .SH SYNOPSIS .P .RS 2 @@ -10,222 +10,11 @@ npm shrinkwrap .RE .SH DESCRIPTION .P -This command locks down the versions of a package's dependencies so -that you can control exactly which versions of each dependency will be -used when your package is installed\. The \fBpackage\.json\fP file is still -required if you want to use \fBnpm install\fP\|\. -.P -By default, \fBnpm install\fP recursively installs the target's -dependencies (as specified in \fBpackage\.json\fP), choosing the latest -available version that satisfies the dependency's semver pattern\. In -some situations, particularly when shipping software where each change -is tightly managed, it's desirable to fully specify each version of -each dependency recursively so that subsequent builds and deploys do -not inadvertently pick up newer versions of a dependency that satisfy -the semver pattern\. Specifying specific semver patterns in each -dependency's \fBpackage\.json\fP would facilitate this, but that's not always -possible or desirable, as when another author owns the npm package\. -It's also possible to check dependencies directly into source control, -but that may be undesirable for other reasons\. -.P -As an example, consider package A: -.P -.RS 2 -.nf -{ - "name": "A", - "version": "0\.1\.0", - "dependencies": { - "B": "<0\.1\.0" - } -} -.fi -.RE -.P -package B: -.P -.RS 2 -.nf -{ - "name": "B", - "version": "0\.0\.1", - "dependencies": { - "C": "<0\.1\.0" - } -} -.fi -.RE -.P -and package C: -.P -.RS 2 -.nf -{ - "name": "C", - "version": "0\.0\.1" -} -.fi -.RE -.P -If these are the only versions of A, B, and C available in the -registry, then a normal \fBnpm install A\fP will install: -.P -.RS 2 -.nf -A@0\.1\.0 -`\-\- B@0\.0\.1 - `\-\- C@0\.0\.1 -.fi -.RE -.P -However, if B@0\.0\.2 is published, then a fresh \fBnpm install A\fP will -install: -.P -.RS 2 -.nf -A@0\.1\.0 -`\-\- B@0\.0\.2 - `\-\- C@0\.0\.1 -.fi -.RE -.P -assuming the new version did not modify B's dependencies\. Of course, -the new version of B could include a new version of C and any number -of new dependencies\. If such changes are undesirable, the author of A -could specify a dependency on B@0\.0\.1\. However, if A's author and B's -author are not the same person, there's no way for A's author to say -that he or she does not want to pull in newly published versions of C -when B hasn't changed at all\. -.P -In this case, A's author can run -.P -.RS 2 -.nf -npm shrinkwrap -.fi -.RE -.P -This generates \fBnpm\-shrinkwrap\.json\fP, which will look something like this: -.P -.RS 2 -.nf -{ - "name": "A", - "version": "0\.1\.0", - "dependencies": { - "B": { - "version": "0\.0\.1", - "from": "B@^0\.0\.1", - "resolved": "https://registry\.npmjs\.org/B/\-/B\-0\.0\.1\.tgz", - "dependencies": { - "C": { - "version": "0\.0\.1", - "from": "org/C#v0\.0\.1", - "resolved": "git://github\.com/org/C\.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4" - } - } - } - } -} -.fi -.RE -.P -The shrinkwrap command has locked down the dependencies based on what's -currently installed in \fBnode_modules\fP\|\. The installation behavior is changed to: -.RS 0 -.IP 1. 3 -The module tree described by the shrinkwrap is reproduced\. This means -reproducing the structure described in the file, using the specific files -referenced in "resolved" if available, falling back to normal package -resolution using "version" if one isn't\. -.IP 2. 3 -The tree is walked and any missing dependencies are installed in the usual fashion\. - -.RE -.P -If \fBpreshrinkwrap\fP, \fBshrinkwrap\fP or \fBpostshrinkwrap\fP are in the \fBscripts\fP property of the -\fBpackage\.json\fP, they will be executed by running \fBnpm shrinkwrap\fP\|\. -\fBpreshrinkwrap\fP and \fBshrinkwrap\fP are executed before the shrinkwrap, \fBpostshrinkwrap\fP is -executed afterwards\. For example to run some postprocessing on the generated file: -.P -.RS 2 -.nf -"scripts": { "postshrinkwrap": "node fix\-shrinkwrap\.js" } -.fi -.RE -.SS Using shrinkwrapped packages -.P -Using a shrinkwrapped package is no different than using any other -package: you can \fBnpm install\fP it by hand, or add a dependency to your -\fBpackage\.json\fP file and \fBnpm install\fP it\. -.SS Building shrinkwrapped packages -.P -To shrinkwrap an existing package: -.RS 0 -.IP 1. 3 -Run \fBnpm install\fP in the package root to install the current -versions of all dependencies\. -.IP 2. 3 -Validate that the package works as expected with these versions\. -.IP 3. 3 -Run \fBnpm shrinkwrap\fP, add \fBnpm\-shrinkwrap\.json\fP to git, and publish -your package\. - -.RE -.P -To add or update a dependency in a shrinkwrapped package: -.RS 0 -.IP 1. 3 -Run \fBnpm install\fP in the package root to install the current -versions of all dependencies\. -.IP 2. 3 -Add or update dependencies\. \fBnpm install \-\-save\fP or \fBnpm install \-\-save\-dev\fP -each new or updated package individually to update the \fBpackage\.json\fP and -the shrinkwrap\. Note that they must be explicitly named in order to be -installed: running \fBnpm install\fP with no arguments will merely reproduce -the existing shrinkwrap\. -.IP 3. 3 -Validate that the package works as expected with the new -dependencies\. -.IP 4. 3 -Commit the new \fBnpm\-shrinkwrap\.json\fP, and publish your package\. - -.RE -.P -You can use npm help outdated to view dependencies with newer versions -available\. -.SS Other Notes -.P -A shrinkwrap file must be consistent with the package's \fBpackage\.json\fP -file\. \fBnpm shrinkwrap\fP will fail if required dependencies are not -already installed, since that would result in a shrinkwrap that -wouldn't actually work\. Similarly, the command will fail if there are -extraneous packages (not referenced by \fBpackage\.json\fP), since that would -indicate that \fBpackage\.json\fP is not correct\. -.P -Starting with npm v4\.0\.1, \fBdevDependencies\fP are included when you run -\fBnpm shrinkwrap\fP and follow the usual rules as to when they're installed\. -As of npm v3\.10\.8, if you run \fBnpm install \-\-only=production\fP or -\fBnpm install \-\-production\fP with a shrinkwrap including your development -dependencies they won't be installed\. Similarly, if the environment -variable \fBNODE_ENV\fP is \fBproduction\fP then they won't be installed\. If you -need compatibility with versions of npm prior to v3\.10\.8 or otherwise -don't want them in your shrinkwrap you can exclude development -dependencies with: -\fBnpm shrinkwrap \-\-only=prod\fP or \fBnpm shrinkwrap \-\-production\fP\|\. -.P -If shrinkwrapped package A depends on shrinkwrapped package B, B's -shrinkwrap will not be used as part of the installation of A\. However, -because A's shrinkwrap is constructed from a valid installation of B -and recursively specifies all dependencies, the contents of B's -shrinkwrap will implicitly be included in A's shrinkwrap\. -.SS Caveats -.P -If you wish to lock down the specific bytes included in a package, for -example to have 100% confidence in being able to reproduce a -deployment or build, then you ought to check your dependencies into -source control, or pursue some other mechanism that can verify -contents rather than versions\. +This command repurposes \fBpackage\-lock\.json\fP into a publishable +\fBnpm\-shrinkwrap\.json\fP or simply creates a new one\. The file created and updated +by this command will then take precedence over any other existing or future +\fBpackage\-lock\.json\fP files\. For a detailed explanation of the design and purpose +of package locks in npm, see npm help 5 package\-locks\. .SH SEE ALSO .RS 0 .IP \(bu 2 @@ -237,6 +26,12 @@ npm help 7 scripts .IP \(bu 2 npm help 5 package\.json .IP \(bu 2 +npm help 5 package\-locks +.IP \(bu 2 +npm help 5 package\-lock\.json +.IP \(bu 2 +npm help 5 shrinkwrap\.json +.IP \(bu 2 npm help ls .RE diff --git a/deps/npm/man/man1/npm.1 b/deps/npm/man/man1/npm.1 index f2d5d75d66..8ce03075f1 100644 --- a/deps/npm/man/man1/npm.1 +++ b/deps/npm/man/man1/npm.1 @@ -10,7 +10,7 @@ npm [args] .RE .SH VERSION .P -5.0.0-beta.56 +5.0.0 .SH DESCRIPTION .P npm is the package manager for the Node JavaScript platform\. It puts diff --git a/deps/npm/man/man5/npm-package-locks.5 b/deps/npm/man/man5/npm-package-locks.5 new file mode 100644 index 0000000000..d751dc5566 --- /dev/null +++ b/deps/npm/man/man5/npm-package-locks.5 @@ -0,0 +1,183 @@ +.TH "NPM\-PACKAGE\-LOCKS" "5" "May 2017" "" "" +.SH "NAME" +\fBnpm-package-locks\fR \- An explanation of npm lockfiles +.SH DESCRIPTION +.P +Conceptually, the "input" to npm help install is a npm help 5 package\.json, while its +"output" is a fully\-formed \fBnode_modules\fP tree: a representation of the +dependencies you declared\. In an ideal world, npm would work like a pure +function: the same \fBpackage\.json\fP should produce the exact same \fBnode_modules\fP +tree, any time\. In some cases, this is indeed true\. But in many others, npm is +unable to do this\. There are multiple reasons for this: +.RS 0 +.IP \(bu 2 +different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms\. +.IP \(bu 2 +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\. +.IP \(bu 2 +A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (\fB1\.2\.3\fP instead of \fB^1\.2\.3\fP) +.IP \(bu 2 +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\. + +.RE +.P +As an example, consider package A: +.P +.RS 2 +.nf +{ + "name": "A", + "version": "0\.1\.0", + "dependencies": { + "B": "<0\.1\.0" + } +} +.fi +.RE +.P +package B: +.P +.RS 2 +.nf +{ + "name": "B", + "version": "0\.0\.1", + "dependencies": { + "C": "<0\.1\.0" + } +} +.fi +.RE +.P +and package C: +.P +.RS 2 +.nf +{ + "name": "C", + "version": "0\.0\.1" +} +.fi +.RE +.P +If these are the only versions of A, B, and C available in the +registry, then a normal \fBnpm install A\fP will install: +.P +.RS 2 +.nf +A@0\.1\.0 +`\-\- B@0\.0\.1 + `\-\- C@0\.0\.1 +.fi +.RE +.P +However, if B@0\.0\.2 is published, then a fresh \fBnpm install A\fP will +install: +.P +.RS 2 +.nf +A@0\.1\.0 +`\-\- B@0\.0\.2 + `\-\- C@0\.0\.1 +.fi +.RE +.P +assuming the new version did not modify B's dependencies\. Of course, +the new version of B could include a new version of C and any number +of new dependencies\. If such changes are undesirable, the author of A +could specify a dependency on B@0\.0\.1\. However, if A's author and B's +author are not the same person, there's no way for A's author to say +that he or she does not want to pull in newly published versions of C +when B hasn't changed at all\. +.P +To prevent this potential issue, npm uses npm help 5 package\-lock\.json or, if present, +npm help 5 shrinkwrap\.json\. These files are called package locks, or lockfiles\. +.P +Whenever you run \fBnpm install\fP, npm generates or updates your package lock, +which will look something like this: +.P +.RS 2 +.nf +{ + "name": "A", + "version": "0\.1\.0", + \.\.\.metadata fields\.\.\. + "dependencies": { + "B": { + "version": "0\.0\.1", + "resolved": "https://registry\.npmjs\.org/B/\-/B\-0\.0\.1\.tgz", + "integrity": "sha512\-DeAdb33F+" + "dependencies": { + "C": { + "version": "git://github\.com/org/C\.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4" + } + } + } + } +} +.fi +.RE +.P +This file describes an \fIexact\fR, and more importantly \fIreproducible\fR +\fBnode_modules\fP tree\. Once it's present, and future installation will base its +work off this file, instead of recalculating dependency versions off +npm help 5 package\.json\. +.P +The presence of a package lock changes the installation behavior such that: +.RS 0 +.IP 1. 3 +The module tree described by the package lock is reproduced\. This means +reproducing the structure described in the file, using the specific files +referenced in "resolved" if available, falling back to normal package resolution +using "version" if one isn't\. +.IP 2. 3 +The tree is walked and any missing dependencies are installed in the usual +fashion\. + +.RE +.P +If \fBpreshrinkwrap\fP, \fBshrinkwrap\fP or \fBpostshrinkwrap\fP are in the \fBscripts\fP +property of the \fBpackage\.json\fP, they will be executed in order\. \fBpreshrinkwrap\fP +and \fBshrinkwrap\fP are executed before the shrinkwrap, \fBpostshrinkwrap\fP is +executed afterwards\. These scripts run for both \fBpackage\-lock\.json\fP and +\fBnpm\-shrinkwrap\.json\fP\|\. For example to run some postprocessing on the generated +file: +.P +.RS 2 +.nf +"scripts": { + "postshrinkwrap": "json \-I \-e \\"this\.myMetadata = $MY_APP_METADATA\\"" +} +.fi +.RE +.SS Using locked packages +.P +Using a locked package is no different than using any package without a package +lock: any commands that update \fBnode_modules\fP and/or \fBpackage\.json\fP\|'s +dependencies will automatically sync the existing lockfile\. This includes \fBnpm +install\fP, \fBnpm rm\fP, \fBnpm update\fP, etc\. To prevent this update from happening, +you can use the \fB\-\-no\-save\fP option to prevent saving altogether, or +\fB\-\-no\-shrinkwrap\fP to allow \fBpackage\.json\fP to be updated while leaving +\fBpackage\-lock\.json\fP or \fBnpm\-shrinkwrap\.json\fP intact\. +.P +It is highly recommended you commit the generated package lock to source +control: this will allow anyone else on your team, your deployments, your +CI/continuous integration, and anyone else who runs \fBnpm install\fP in your +package source to get the exact same dependency tree that you were developing +on\. Additionally, the diffs from these changes are human\-readable and will +inform you of any changes npm has made to your \fBnode_modules\fP, so you can notice +if any transitive dependencies were updated, hoisted, etc\. +.SH SEE ALSO +.RS 0 +.IP \(bu 2 +https://medium\.com/@sdboyer/so\-you\-want\-to\-write\-a\-package\-manager\-4ae9c17d9527 +.IP \(bu 2 +npm help 5 package\.json +.IP \(bu 2 +npm help 5 package\-lock\.json +.IP \(bu 2 +npm help 5 shrinkwrap\.json +.IP \(bu 2 +npm help shrinkwrap + +.RE diff --git a/deps/npm/man/man5/npm-shrinkwrap.json.5 b/deps/npm/man/man5/npm-shrinkwrap.json.5 new file mode 100644 index 0000000000..deb06a7244 --- /dev/null +++ b/deps/npm/man/man5/npm-shrinkwrap.json.5 @@ -0,0 +1,32 @@ +.TH "NPM\-SHRINKWRAP\.JSON" "5" "May 2017" "" "" +.SH "NAME" +\fBnpm-shrinkwrap.json\fR \- A publishable lockfile +.SH DESCRIPTION +.P +\fBnpm\-shrinkwrap\.json\fP is a file created by npm help shrinkwrap\. It is identical to +\fBpackage\-lock\.json\fP, with one major caveat: Unlike \fBpackage\-lock\.json\fP, +\fBnpm\-shrinwkrap\.json\fP may be included when publishing a package\. +.P +The recommended use\-case for \fBnpm\-shrinkwrap\.json\fP is applications deployed +through the publishing process on the registry: for example, daemons and +command\-line tools intended as global installs or \fBdevDependencies\fP\|\. It's +strongly discouraged for library authors to publish this file, since that would +prevent end users from having control over transitive dependency updates\. +.P +Additionally, if both \fBpackage\-lock\.json\fP and \fBnpm\-shrinwkrap\.json\fP are present +in a package root, \fBpackage\-lock\.json\fP will be ignored in favor of this file\. +.P +For full details and description of the \fBnpm\-shrinkwrap\.json\fP file format, refer +to the manual page for npm help 5 package\-lock\.json\. +.SH SEE ALSO +.RS 0 +.IP \(bu 2 +npm help shrinkwrap +.IP \(bu 2 +npm help 5 package\-lock\.json +.IP \(bu 2 +npm help 5 package\.json +.IP \(bu 2 +npm help install + +.RE diff --git a/deps/npm/man/man5/package-lock.json.5 b/deps/npm/man/man5/package-lock.json.5 new file mode 100644 index 0000000000..fb86d4d0c5 --- /dev/null +++ b/deps/npm/man/man5/package-lock.json.5 @@ -0,0 +1,144 @@ +.TH "PACKAGE\-LOCK\.JSON" "5" "May 2017" "" "" +.SH "NAME" +\fBpackage-lock.json\fR \- A manifestation of the manifest +.SH DESCRIPTION +.P +\fBpackage\-lock\.json\fP is automatically generated for any operations where npm +modifies either the \fBnode_modules\fP tree, or \fBpackage\.json\fP\|\. It describes the +exact tree that was generated, such that subsequent installs are able to +generate identical trees, regardless of intermediate dependency updates\. +.P +This file is intended to be committed into source repositories, and serves +various purposes: +.RS 0 +.IP \(bu 2 +Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies\. +.IP \(bu 2 +Provide a facility for users to "time\-travel" to previous states of \fBnode_modules\fP without having to commit the directory itself\. +.IP \(bu 2 +To facilitate greater visibility of tree changes through readable source control diffs\. +.IP \(bu 2 +And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously\-installed packages\. + +.RE +.P +One key detail about \fBpackage\-lock\.json\fP is that it cannot be published, and it +will be ignored if found in any place other than the toplevel package\. It shares +a format with npm help 5 shrinkwrap\.json, which is essentially the same file, but +allows publication\. This is not recommended unless deploying a CLI tool or +otherwise using the publication process for producing production packages\. +.P +If both \fBpackage\-lock\.json\fP and \fBnpm\-shrinkwrap\.json\fP are present in the root of +a package, \fBpackage\-lock\.json\fP will be completely ignored\. +.SH FILE FORMAT +.SS name +.P +The name of the package this is a package\-lock for\. This must match what's in +\fBpackage\.json\fP\|\. +.SS version +.P +The version of the package this is a package\-lock for\. This must match what's in +\fBpackage\.json\fP\|\. +.SS lockfileVersion +.P +An integer version, starting at \fB1\fP with the version number of this document +whose semantics were used when generating this \fBpackage\-lock\.json\fP\|\. +.SS packageIntegrity +.P +This is a subresource +integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR value +created from the \fBpacakge\.json\fP\|\. No preprocessing of the \fBpackage\.json\fP should +be done\. Subresource integrity strings can be produced by modules like +\fBssri\fP \fIhttps://www\.npmjs\.com/package/ssri\fR\|\. +.SS preserveSymlinks +.P +Indicates that the install was done with the environment variable +\fBNODE_PRESERVE_SYMLINKS\fP enabled\. The installer should insist that the value of +this property match that environment variable\. +.SS dependencies +.P +A mapping of package name to dependency object\. Dependency objects have the +following properties: +.SS version +.P +This is a specifier that uniquely identifies this package and should be +usable in fetching a new copy of it\. +.RS 0 +.IP \(bu 2 +bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes\. +.IP \(bu 2 +registry sources: This is a version number\. (eg, \fB1\.2\.3\fP) +.IP \(bu 2 +git sources: This is a git specifier with resolved committish\. (eg, \fBgit+https://example\.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e\fP) +.IP \(bu 2 +http tarball sources: This is the URL of the tarball\. (eg, \fBhttps://example\.com/example\-1\.3\.0\.tgz\fP) +.IP \(bu 2 +local tarball sources: This is the file URL of the tarball\. (eg \fBfile:///opt/storage/example\-1\.3\.0\.tgz\fP) +.IP \(bu 2 +local link sources: This is the file URL of the link\. (eg \fBfile:libs/our\-module\fP) + +.RE +.SS integrity +.P +This is a Standard Subresource +Integrity \fIhttps://w3c\.github\.io/webappsec/specs/subresourceintegrity/\fR for this +resource\. +.RS 0 +.IP \(bu 2 +For bundled dependencies this is not included, regardless of source\. +.IP \(bu 2 +For registry sources, this is the \fBintegrity\fP that the registry provided, or if one wasn't provided the SHA1 in \fBshasum\fP\|\. +.IP \(bu 2 +For git sources this is the specific commit hash we cloned from\. +.IP \(bu 2 +For remote tarball sources this is an integrity based on a SHA512 of +the file\. +.IP \(bu 2 +For local tarball sources: This is an integrity field based on the SHA512 of the file\. + +.RE +.SS resolved +.RS 0 +.IP \(bu 2 +For bundled dependencies this is not included, regardless of source\. +.IP \(bu 2 +For registry sources this is path of the tarball relative to the registry +URL\. If the tarball URL isn't on the same server as the registry URL then +this is a complete URL\. + +.RE +.SS bundled +.P +If true, this is the bundled dependency and will be installed by the parent +module\. When installing, this module will be extracted from the parent +module during the extract phase, not installed as a separate dependency\. +.SS dev +.P +If true then this dependency is either a development dependency ONLY of the +top level module or a transitive dependency of one\. This is false for +dependencies that are both a development dependency of the top level and a +transitive dependency of a non\-development dependency of the top level\. +.SS optional +.P +If true then this dependency is either an optional dependency ONLY of the +top level module or a transitive dependency of one\. This is false for +dependencies that are both an optional dependency of the top level and a +transitive dependency of a non\-optional dependency of the top level\. +.P +All optional dependencies should be included even if they're uninstallable +on the current platform\. +.SS dependencies +.P +The dependencies of this dependency, exactly as at the top level\. +.SH SEE ALSO +.RS 0 +.IP \(bu 2 +npm help shrinkwrap +.IP \(bu 2 +npm help 5 package\-lock\.json +.IP \(bu 2 +npm help 5 package\.json +.IP \(bu 2 +npm help install + +.RE diff --git a/deps/npm/man/man7/npm-config.7 b/deps/npm/man/man7/npm-config.7 index 30a42afec6..67e8880659 100644 --- a/deps/npm/man/man7/npm-config.7 +++ b/deps/npm/man/man7/npm-config.7 @@ -81,6 +81,8 @@ The following shorthands are parsed on the command\-line: .IP \(bu 2 \fB\-S\fP: \fB\-\-save\fP .IP \(bu 2 +\fB\-P\fP: \fB\-\-save\-prod\fP +.IP \(bu 2 \fB\-D\fP: \fB\-\-save\-dev\fP .IP \(bu 2 \fB\-O\fP: \fB\-\-save\-optional\fP @@ -943,6 +945,19 @@ Type: Boolean Attempt to install packages in the \fBoptionalDependencies\fP object\. Note that if these packages fail to install, the overall installation process is not aborted\. +.SS package\-lock +.RS 0 +.IP \(bu 2 +Default: true +.IP \(bu 2 +Type: Boolean + +.RE +.P +If set to false, then ignore \fBpackage\-lock\.json\fP files when installing\. This +will also prevent \fIwriting\fR \fBpackage\-lock\.json\fP if \fBsave\fP is true\. +.P +This option is an alias for \fB\-\-shrinkwrap\fP\|\. .SS parseable .RS 0 .IP \(bu 2 @@ -1107,6 +1122,20 @@ If a package would be saved at install time by the use of \fB\-\-save\fP, .P When used with the \fBnpm rm\fP command, it removes it from the bundledDependencies list\. +.SS save\-prod +.RS 0 +.IP \(bu 2 +Default: false +.IP \(bu 2 +Type: Boolean + +.RE +.P +Makes sure that a package will be saved into \fBdependencies\fP specifically\. This +is useful if a package already exists in \fBdevDependencies\fP or +\fBoptionalDependencies\fP, but you want to move it to be a production dep\. This is +also the default behavior if \fB\-\-save\fP is true, and neither \fB\-\-save\-dev\fP or +\fB\-\-save\-optional\fP are true\. .SS save\-dev .RS 0 .IP \(bu 2 @@ -1278,8 +1307,10 @@ Type: Boolean .RE .P -If set to false, then ignore \fBnpm\-shrinkwrap\.json\fP files when -installing\. +If set to false, then ignore \fBnpm\-shrinkwrap\.json\fP files when installing\. This +will also prevent \fIwriting\fR \fBnpm\-shrinkwrap\.json\fP if \fBsave\fP is true\. +.P +This option is an alias for \fB\-\-package\-lock\fP\|\. .SS sign\-git\-tag .RS 0 .IP \(bu 2 diff --git a/deps/npm/man/man7/npm-index.7 b/deps/npm/man/man7/npm-index.7 index 2ed9981eb3..8ec9c15976 100644 --- a/deps/npm/man/man7/npm-index.7 +++ b/deps/npm/man/man7/npm-index.7 @@ -123,7 +123,7 @@ Run arbitrary package scripts Search for packages .SS npm help shrinkwrap .P -Lock down dependency versions +Lock down dependency versions for publication .SS npm help star .P Mark your favorite packages @@ -169,9 +169,18 @@ File system structures npm uses .SS npm help 5 folders .P Folder Structures Used by npm +.SS npm help 5 package\-locks +.P +An explanation of npm lockfiles +.SS npm help 5 shrinkwrap\.json +.P +A publishable lockfile .SS npm help 5 npmrc .P The npm config files +.SS npm help 5 package\-lock\.json +.P +A manifestation of the manifest .SS npm help 5 package\.json .P Specifics of npm's package\.json handling diff --git a/deps/npm/man/man7/npm-scripts.7 b/deps/npm/man/man7/npm-scripts.7 index 666953c5ce..f57a4c221f 100644 --- a/deps/npm/man/man7/npm-scripts.7 +++ b/deps/npm/man/man7/npm-scripts.7 @@ -8,16 +8,24 @@ following scripts: .RS 0 .IP \(bu 2 prepublish: -Run BEFORE the package is published\. (Also run on local \fBnpm -install\fP without any arguments\. See below\.) +Run BEFORE the package is packed and published, as well as on local \fBnpm +install\fP without any arguments\. (See below) .IP \(bu 2 prepare: -Run both BEFORE the package is published, and on local \fBnpm -install\fP without any arguments\. (See below\.) This is run +Run both BEFORE the package is packed and published, and on local \fBnpm +install\fP without any arguments (See below)\. This is run AFTER \fBprepublish\fP, but BEFORE \fBprepublishOnly\fP\|\. .IP \(bu 2 prepublishOnly: -Run BEFORE the package is published\. (See below\.) +Run BEFORE the package is prepared and packed, ONLY on \fBnpm publish\fP\|\. (See +below\.) +.IP \(bu 2 +prepack: +run BEFORE a tarball is packed (on \fBnpm pack\fP, \fBnpm publish\fP, and when +installing git dependencies) +.IP \(bu 2 +postpack: +Run AFTER the tarball has been generated and moved to its final destination\. .IP \(bu 2 publish, postpublish: Run AFTER the package is published\. -- cgit v1.2.3