diff options
author | Kat Marchán <kzm@sykosomatic.org> | 2017-05-28 21:04:08 -0700 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2017-05-29 18:06:04 +0200 |
commit | c58cea5a163cd5d7133e00fdf257325ce3807c09 (patch) | |
tree | 1b7f97c0474f1990450a54e82b4432ec37de1956 /deps/npm/doc | |
parent | 88fe7e84e56e44a727169c07ee040cbf67f9c0a8 (diff) | |
download | node-new-c58cea5a163cd5d7133e00fdf257325ce3807c09.tar.gz |
deps: upgrade npm to 5.0.0
PR-URL: https://github.com/nodejs/node/pull/13276
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Diffstat (limited to 'deps/npm/doc')
-rw-r--r-- | deps/npm/doc/cli/npm-cache.md | 60 | ||||
-rw-r--r-- | deps/npm/doc/cli/npm-install.md | 124 | ||||
-rw-r--r-- | deps/npm/doc/cli/npm-publish.md | 4 | ||||
-rw-r--r-- | deps/npm/doc/cli/npm-shrinkwrap.md | 185 | ||||
-rw-r--r-- | deps/npm/doc/files/npm-package-locks.md | 145 | ||||
-rw-r--r-- | deps/npm/doc/files/npm-shrinkwrap.json.md | 27 | ||||
-rw-r--r-- | deps/npm/doc/files/package-lock.json.md | 132 | ||||
-rw-r--r-- | deps/npm/doc/misc/npm-config.md | 28 | ||||
-rw-r--r-- | deps/npm/doc/misc/npm-index.md | 14 | ||||
-rw-r--r-- | deps/npm/doc/misc/npm-scripts.md | 16 |
10 files changed, 492 insertions, 243 deletions
diff --git a/deps/npm/doc/cli/npm-cache.md b/deps/npm/doc/cli/npm-cache.md index ea8cb1b991..92a6236c0c 100644 --- a/deps/npm/doc/cli/npm-cache.md +++ b/deps/npm/doc/cli/npm-cache.md @@ -8,11 +8,11 @@ npm-cache(1) -- Manipulates packages cache npm cache add <tarball url> npm cache add <name>@<version> - npm cache ls [<path>] - npm cache clean [<path>] aliases: npm cache clear, npm cache rm + npm cache verify + ## DESCRIPTION Used to add, list, or clean the npm cache folder. @@ -22,35 +22,45 @@ Used to add, list, or clean the npm cache folder. intended to be used internally by npm, but it can provide a way to add data to the local installation cache explicitly. -* ls: - Show the data in the cache. Argument is a path to show in the cache - folder. Works a bit like the `find` program, but limited by the - `depth` config. - * 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. + +* 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. ## DETAILS -npm stores cache data in the directory specified in `npm config get cache`. -For each package that is added to the cache, three pieces of information are -stored in `{cache}/{name}/{version}`: +npm stores cache data in an opaque directory within the configured `cache`, +named `_cacache`. This directory is a `cacache`-based content-addressable cache +that stores all http request data as well as other package-related data. This +directory is primarily accessed through `pacote`, the library responsible for +all package fetching as of npm@5. + +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 `pacote` 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 `clean` now requires +`--force` to run. + +There is currently no method exposed through npm to inspect or directly manage +the contents of this cache. In order to access it, `cacache` must be used +directly. + +npm will not remove data by itself: the cache will grow as new packages are +installed. -* .../package/package.json: - The package.json file, as npm sees it. -* .../package.tgz: - The tarball for that version. +## A NOTE ABOUT THE CACHE'S DESIGN -Additionally, whenever a registry request is made, a `.cache.json` file -is placed at the corresponding URI, to store the ETag and the requested -data. This is stored in `{cache}/{hostname}/{path}/.cache.json`. +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. -Commands that make non-essential registry requests (such as `search` and -`view`, or the completion scripts) generally specify a minimum timeout. -If the `.cache.json` file is younger than the specified timeout, then -they do not make an HTTP request to the registry. +To run an offline verification of existing cache contents, use `npm cache +verify`. ## CONFIGURATION @@ -69,3 +79,5 @@ The root cache folder. * npm-install(1) * npm-publish(1) * npm-pack(1) +* https://npm.im/cacache +* https://npm.im/pacote diff --git a/deps/npm/doc/cli/npm-install.md b/deps/npm/doc/cli/npm-install.md index 6a37fcc76b..44cb68792b 100644 --- a/deps/npm/doc/cli/npm-install.md +++ b/deps/npm/doc/cli/npm-install.md @@ -8,18 +8,21 @@ npm-install(1) -- Install a package npm install [<@scope>/]<name>@<tag> npm install [<@scope>/]<name>@<version> npm install [<@scope>/]<name>@<version range> + npm install <git-host>:<git-user>/<repo-name> + npm install <git repo url> npm install <tarball file> npm install <tarball url> npm install <folder> 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] ## DESCRIPTION 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-shrinkwrap(1). +package has a package-lock or shrinkwrap file, the installation of dependencies +will be driven by that, with an `npm-shrinkwrap.json` taking precedence if both +files exist. See package-lock.json(5) and npm-shrinkwrap(1). A `package` is: @@ -54,13 +57,17 @@ after packing it up into a tarball (b). * `npm install <folder>`: - 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 `<folder>` sits + inside the root of your project, its dependencies may be hoisted to the + toplevel `node_modules` as they would for other types of dependencies. * `npm install <tarball file>`: 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 `npm link`. + using `npm link`. The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as + the extension. Example: @@ -75,27 +82,31 @@ after packing it up into a tarball (b). npm install https://github.com/indexzero/forever/tarball/v0.5.6 -* `npm install [<@scope>/]<name> [-S|--save|-D|--save-dev|-O|--save-optional]`: +* `npm install [<@scope>/]<name>`: Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See `npm-config(7)`. The config's default value is `latest`.) - 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 + `latest` on the npm registry. Example: npm install sax - `npm install` takes 3 exclusive, optional flags which save or update - the package version in your main package.json: + `npm install` saves any specified packages into `dependencies` by default. + Additionally, you can control where and how they get saved with some + additional flags: - * `-S, --save`: Package will appear in your `dependencies`. + * `-P, --save-prod`: Package will appear in your `dependencies`. This is the + default unless `-D` or `-O` are present. * `-D, --save-dev`: Package will appear in your `devDependencies`. * `-O, --save-optional`: Package will appear in your `optionalDependencies`. + * `--no-save`: Prevents saving to `dependencies`. + When using any of the above options to save dependencies to your package.json, there are two additional, optional flags: @@ -105,8 +116,8 @@ after packing it up into a tarball (b). * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list. - Further, if you have an `npm-shrinkwrap.json` then it will be updated as - well. + Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it + will be updated as well. `<scope>` is optional. The package will be downloaded from the registry associated with the specified scope. If no registry is associated with @@ -118,13 +129,13 @@ after packing it up into a tarball (b). Examples: - 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 **Note**: If there is a file or folder named `<name>` in the current @@ -167,20 +178,30 @@ after packing it up into a tarball (b). * `npm install <git remote url>`: - Installs the package from the hosted git provider, cloning it with - `git`. 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 `git`. + For a full git remote url, only that URL will be attempted. + + <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>] + + `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or + `git+file`. - <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish>] + If `#<commit-ish>` is provided, it will be used to clone exactly that + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` 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 `#<commit-ish>` or `#semver:<semver>` is + specified, then `master` is used. - `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, - or `git+file`. - If no `<commit-ish>` is specified, then `master` is used. + If the repository makes use of submodules, those submodules will be cloned + as well. - If the repository makes use of submodules, those submodules will - be cloned as well. + If the package being installed contains a `prepare` script, its + `dependencies` and `devDependencies` 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: + The following git environment variables are recognized by npm and will be + added to the environment when running git: * `GIT_ASKPASS` * `GIT_EXEC_PATH` @@ -195,6 +216,7 @@ after packing it up into a tarball (b). Examples: 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 @@ -205,20 +227,31 @@ after packing it up into a tarball (b). Install the package at `https://github.com/githubname/githubrepo` by attempting to clone it using `git`. - If you don't specify a *commit-ish* then `master` will be used. + If `#<commit-ish>` is provided, it will be used to clone exactly that + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` 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 `#<commit-ish>` or `#semver:<semver>` is + specified, then `master` is used. + + As with regular git dependencies, `dependencies` and `devDependencies` will + be installed if the package has a `prepare` script, before the package is + done installing. Examples: npm install mygithubuser/myproject npm install github:mygithubuser/myproject -* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>]`: +* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]`: Install the package at `https://gist.github.com/gistID` by attempting to clone it using `git`. The GitHub username associated with the gist is - optional and will not be saved in `package.json` if `-S` or `--save` is used. + optional and will not be saved in `package.json`. - If you don't specify a *commit-ish* then `master` will be used. + As with regular git dependencies, `dependencies` and `devDependencies` will + be installed if the package has a `prepare` script, before the package is + done installing. Example: @@ -229,7 +262,16 @@ after packing it up into a tarball (b). Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo` by attempting to clone it using `git`. - If you don't specify a *commit-ish* then `master` will be used. + If `#<commit-ish>` is provided, it will be used to clone exactly that + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` 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 `#<commit-ish>` or `#semver:<semver>` is + specified, then `master` is used. + + As with regular git dependencies, `dependencies` and `devDependencies` will + be installed if the package has a `prepare` script, before the package is + done installing. Example: @@ -240,11 +282,21 @@ after packing it up into a tarball (b). Install the package at `https://gitlab.com/gitlabname/gitlabrepo` by attempting to clone it using `git`. - If you don't specify a *commit-ish* then `master` will be used. + If `#<commit-ish>` is provided, it will be used to clone exactly that + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` 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 `#<commit-ish>` or `#semver:<semver>` is + specified, then `master` is used. + + As with regular git dependencies, `dependencies` and `devDependencies` will + be installed if the package has a `prepare` script, before the package is + done installing. Example: npm install gitlab:mygitlabuser/myproject + npm install gitlab:myusr/myproj#semver:^5.0 You may combine multiple arguments, and even multiple types of arguments. For example: @@ -272,7 +324,7 @@ global `node_modules` folder. Only your direct dependencies will show in `node_modules` and everything they depend on will be flattened in their `node_modules` folders. This obviously will eliminate some deduping. -The `--ignore-scripts` argument will cause npm to not execute any +The `--ignore-scripts` argument will cause npm to not execute any scripts defined in the package.json. See `npm-scripts(7)`. The `--legacy-bundling` argument will cause npm to install the package such @@ -289,7 +341,7 @@ The `--no-optional` argument will prevent optional dependencies from being installed. The `--no-shrinkwrap` 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. The `--nodedir=/path/to/node/source` argument will allow npm to find the node source code so that npm can compile native modules. @@ -336,7 +388,9 @@ For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces: +-- D@1 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. See npm-folders(5) for a more detailed description of the specific folder structures that npm creates. diff --git a/deps/npm/doc/cli/npm-publish.md b/deps/npm/doc/cli/npm-publish.md index caf1fd2430..892786b61d 100644 --- a/deps/npm/doc/cli/npm-publish.md +++ b/deps/npm/doc/cli/npm-publish.md @@ -48,6 +48,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-unpublish(1). +As of `npm@5`, 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. + For a "dry run" that does everything except actually publishing to the registry, see `npm-pack(1)`, 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/doc/cli/npm-shrinkwrap.md b/deps/npm/doc/cli/npm-shrinkwrap.md index ae04bd02bb..4c223a86cc 100644 --- a/deps/npm/doc/cli/npm-shrinkwrap.md +++ b/deps/npm/doc/cli/npm-shrinkwrap.md @@ -1,4 +1,4 @@ -npm-shrinkwrap(1) -- Lock down dependency versions +npm-shrinkwrap(1) -- Lock down dependency versions for publication ===================================================== ## SYNOPSIS @@ -7,181 +7,11 @@ npm-shrinkwrap(1) -- Lock down dependency versions ## DESCRIPTION -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 `package.json` file is still -required if you want to use `npm install`. - -By default, `npm install` recursively installs the target's -dependencies (as specified in `package.json`), 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 `package.json` 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. - -As an example, consider package A: - - { - "name": "A", - "version": "0.1.0", - "dependencies": { - "B": "<0.1.0" - } - } - -package B: - - { - "name": "B", - "version": "0.0.1", - "dependencies": { - "C": "<0.1.0" - } - } - -and package C: - - { - "name": "C", - "version": "0.0.1" - } - -If these are the only versions of A, B, and C available in the -registry, then a normal `npm install A` will install: - - A@0.1.0 - `-- B@0.0.1 - `-- C@0.0.1 - -However, if B@0.0.2 is published, then a fresh `npm install A` will -install: - - A@0.1.0 - `-- B@0.0.2 - `-- C@0.0.1 - -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. - -In this case, A's author can run - - npm shrinkwrap - -This generates `npm-shrinkwrap.json`, which will look something like this: - - { - "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" - } - } - } - } - } - -The shrinkwrap command has locked down the dependencies based on what's -currently installed in `node_modules`. The installation behavior is changed to: - -1. 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. - -2. The tree is walked and any missing dependencies are installed in the usual fashion. - -If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts` property of the -`package.json`, they will be executed by running `npm shrinkwrap`. -`preshrinkwrap` and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is -executed afterwards. For example to run some postprocessing on the generated file: - - "scripts": { "postshrinkwrap": "node fix-shrinkwrap.js" } - - -### Using shrinkwrapped packages - -Using a shrinkwrapped package is no different than using any other -package: you can `npm install` it by hand, or add a dependency to your -`package.json` file and `npm install` it. - -### Building shrinkwrapped packages - -To shrinkwrap an existing package: - -1. Run `npm install` in the package root to install the current - versions of all dependencies. -2. Validate that the package works as expected with these versions. -3. Run `npm shrinkwrap`, add `npm-shrinkwrap.json` to git, and publish - your package. - -To add or update a dependency in a shrinkwrapped package: - -1. Run `npm install` in the package root to install the current - versions of all dependencies. -2. Add or update dependencies. `npm install --save` or `npm install --save-dev` - each new or updated package individually to update the `package.json` and - the shrinkwrap. Note that they must be explicitly named in order to be - installed: running `npm install` with no arguments will merely reproduce - the existing shrinkwrap. -3. Validate that the package works as expected with the new - dependencies. -4. Commit the new `npm-shrinkwrap.json`, and publish your package. - -You can use npm-outdated(1) to view dependencies with newer versions -available. - -### Other Notes - -A shrinkwrap file must be consistent with the package's `package.json` -file. `npm shrinkwrap` 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 `package.json`), since that would -indicate that `package.json` is not correct. - -Starting with npm v4.0.1, `devDependencies` are included when you run -`npm shrinkwrap` and follow the usual rules as to when they're installed. -As of npm v3.10.8, if you run `npm install --only=production` or -`npm install --production` with a shrinkwrap including your development -dependencies they won't be installed. Similarly, if the environment -variable `NODE_ENV` is `production` 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: -`npm shrinkwrap --only=prod` or `npm shrinkwrap --production`. - -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. - -### Caveats - -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 `package-lock.json` into a publishable +`npm-shrinkwrap.json` or simply creates a new one. The file created and updated +by this command will then take precedence over any other existing or future +`package-lock.json` files. For a detailed explanation of the design and purpose +of package locks in npm, see npm-package-locks(5). ## SEE ALSO @@ -189,4 +19,7 @@ contents rather than versions. * npm-run-script(1) * npm-scripts(7) * package.json(5) +* npm-package-locks(5) +* package-lock.json(5) +* npm-shrinkwrap.json(5) * npm-ls(1) diff --git a/deps/npm/doc/files/npm-package-locks.md b/deps/npm/doc/files/npm-package-locks.md new file mode 100644 index 0000000000..73786dc91a --- /dev/null +++ b/deps/npm/doc/files/npm-package-locks.md @@ -0,0 +1,145 @@ +npm-package-locks(5) -- An explanation of npm lockfiles +===================================================== + +## DESCRIPTION + +Conceptually, the "input" to npm-install(1) is a package.json(5), while its +"output" is a fully-formed `node_modules` tree: a representation of the +dependencies you declared. In an ideal world, npm would work like a pure +function: the same `package.json` should produce the exact same `node_modules` +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: + +* different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms. + +* 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. + +* A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (`1.2.3` instead of `^1.2.3`) + +* 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. + +As an example, consider package A: + + { + "name": "A", + "version": "0.1.0", + "dependencies": { + "B": "<0.1.0" + } + } + +package B: + + { + "name": "B", + "version": "0.0.1", + "dependencies": { + "C": "<0.1.0" + } + } + +and package C: + + { + "name": "C", + "version": "0.0.1" + } + +If these are the only versions of A, B, and C available in the +registry, then a normal `npm install A` will install: + + A@0.1.0 + `-- B@0.0.1 + `-- C@0.0.1 + +However, if B@0.0.2 is published, then a fresh `npm install A` will +install: + + A@0.1.0 + `-- B@0.0.2 + `-- C@0.0.1 + +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. + +To prevent this potential issue, npm uses package-lock.json(5) or, if present, +npm-shrinkwrap.json(5). These files are called package locks, or lockfiles. + +Whenever you run `npm install`, npm generates or updates your package lock, +which will look something like this: + + { + "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" + } + } + } + } + } + +This file describes an *exact*, and more importantly *reproducible* +`node_modules` tree. Once it's present, and future installation will base its +work off this file, instead of recalculating dependency versions off +package.json(5). + +The presence of a package lock changes the installation behavior such that: + +1. 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. + +2. The tree is walked and any missing dependencies are installed in the usual +fashion. + +If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts` +property of the `package.json`, they will be executed in order. `preshrinkwrap` +and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is +executed afterwards. These scripts run for both `package-lock.json` and +`npm-shrinkwrap.json`. For example to run some postprocessing on the generated +file: + + "scripts": { + "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\"" + } + + +### Using locked packages + +Using a locked package is no different than using any package without a package +lock: any commands that update `node_modules` and/or `package.json`'s +dependencies will automatically sync the existing lockfile. This includes `npm +install`, `npm rm`, `npm update`, etc. To prevent this update from happening, +you can use the `--no-save` option to prevent saving altogether, or +`--no-shrinkwrap` to allow `package.json` to be updated while leaving +`package-lock.json` or `npm-shrinkwrap.json` intact. + +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 `npm install` 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 `node_modules`, so you can notice +if any transitive dependencies were updated, hoisted, etc. + +## SEE ALSO + +* https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527 +* package.json(5) +* package-lock.json(5) +* npm-shrinkwrap.json(5) +* npm-shrinkwrap(1) diff --git a/deps/npm/doc/files/npm-shrinkwrap.json.md b/deps/npm/doc/files/npm-shrinkwrap.json.md new file mode 100644 index 0000000000..8256398e86 --- /dev/null +++ b/deps/npm/doc/files/npm-shrinkwrap.json.md @@ -0,0 +1,27 @@ +npm-shrinkwrap.json(5) -- A publishable lockfile +===================================================== + +## DESCRIPTION + +`npm-shrinkwrap.json` is a file created by npm-shrinkwrap(1). It is identical to +`package-lock.json`, with one major caveat: Unlike `package-lock.json`, +`npm-shrinwkrap.json` may be included when publishing a package. + +The recommended use-case for `npm-shrinkwrap.json` is applications deployed +through the publishing process on the registry: for example, daemons and +command-line tools intended as global installs or `devDependencies`. It's +strongly discouraged for library authors to publish this file, since that would +prevent end users from having control over transitive dependency updates. + +Additionally, if both `package-lock.json` and `npm-shrinwkrap.json` are present +in a package root, `package-lock.json` will be ignored in favor of this file. + +For full details and description of the `npm-shrinkwrap.json` file format, refer +to the manual page for package-lock.json(5). + +## SEE ALSO + +* npm-shrinkwrap(1) +* package-lock.json(5) +* package.json(5) +* npm-install(1) diff --git a/deps/npm/doc/files/package-lock.json.md b/deps/npm/doc/files/package-lock.json.md new file mode 100644 index 0000000000..dad219b4a1 --- /dev/null +++ b/deps/npm/doc/files/package-lock.json.md @@ -0,0 +1,132 @@ +package-lock.json(5) -- A manifestation of the manifest +===================================================== + +## DESCRIPTION + +`package-lock.json` is automatically generated for any operations where npm +modifies either the `node_modules` tree, or `package.json`. It describes the +exact tree that was generated, such that subsequent installs are able to +generate identical trees, regardless of intermediate dependency updates. + +This file is intended to be committed into source repositories, and serves +various purposes: + +* Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies. + +* Provide a facility for users to "time-travel" to previous states of `node_modules` without having to commit the directory itself. + +* To facilitate greater visibility of tree changes through readable source control diffs. + +* And optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages. + +One key detail about `package-lock.json` 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-shrinkwrap.json(5), 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. + +If both `package-lock.json` and `npm-shrinkwrap.json` are present in the root of +a package, `package-lock.json` will be completely ignored. + + +## FILE FORMAT + +### name + +The name of the package this is a package-lock for. This must match what's in +`package.json`. + +### version + +The version of the package this is a package-lock for. This must match what's in +`package.json`. + +### lockfileVersion + +An integer version, starting at `1` with the version number of this document +whose semantics were used when generating this `package-lock.json`. + +### packageIntegrity + +This is a [subresource +integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) value +created from the `pacakge.json`. No preprocessing of the `package.json` should +be done. Subresource integrity strings can be produced by modules like +[`ssri`](https://www.npmjs.com/package/ssri). + +### preserveSymlinks + +Indicates that the install was done with the environment variable +`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of +this property match that environment variable. + +### dependencies + +A mapping of package name to dependency object. Dependency objects have the +following properties: + +#### version + +This is a specifier that uniquely identifies this package and should be +usable in fetching a new copy of it. + +* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes. +* registry sources: This is a version number. (eg, `1.2.3`) +* git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`) +* http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`) +* local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`) +* local link sources: This is the file URL of the link. (eg `file:libs/our-module`) + +#### integrity + +This is a [Standard Subresource +Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for this +resource. + +* For bundled dependencies this is not included, regardless of source. +* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`. +* For git sources this is the specific commit hash we cloned from. +* For remote tarball sources this is an integrity based on a SHA512 of + the file. +* For local tarball sources: This is an integrity field based on the SHA512 of the file. + +#### resolved + +* For bundled dependencies this is not included, regardless of source. +* 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. + +#### bundled + +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. + +#### dev + +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. + +#### optional + +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. + +All optional dependencies should be included even if they're uninstallable +on the current platform. + +#### dependencies + +The dependencies of this dependency, exactly as at the top level. + +## SEE ALSO + +* npm-shrinkwrap(1) +* package-lock.json(5) +* package.json(5) +* npm-install(1) diff --git a/deps/npm/doc/misc/npm-config.md b/deps/npm/doc/misc/npm-config.md index 0b7db2e0e5..6fee98a90c 100644 --- a/deps/npm/doc/misc/npm-config.md +++ b/deps/npm/doc/misc/npm-config.md @@ -63,6 +63,7 @@ The following shorthands are parsed on the command-line: * `-f`: `--force` * `-desc`: `--description` * `-S`: `--save` +* `-P`: `--save-prod` * `-D`: `--save-dev` * `-O`: `--save-optional` * `-B`: `--save-bundle` @@ -682,6 +683,16 @@ Attempt to install packages in the `optionalDependencies` object. Note that if these packages fail to install, the overall installation process is not aborted. +### package-lock + +* Default: true +* Type: Boolean + +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +This option is an alias for `--shrinkwrap`. + ### parseable * Default: false @@ -803,6 +814,17 @@ If a package would be saved at install time by the use of `--save`, When used with the `npm rm` command, it removes it from the bundledDependencies list. +### save-prod + +* Default: false +* Type: Boolean + +Makes sure that a package will be saved into `dependencies` specifically. This +is useful if a package already exists in `devDependencies` or +`optionalDependencies`, but you want to move it to be a production dep. This is +also the default behavior if `--save` is true, and neither `--save-dev` or +`--save-optional` are true. + ### save-dev * Default: false @@ -934,8 +956,10 @@ The shell to run for the `npm explore` command. * Default: true * Type: Boolean -If set to false, then ignore `npm-shrinkwrap.json` files when -installing. +If set to false, then ignore `npm-shrinkwrap.json` files when installing. This +will also prevent _writing_ `npm-shrinkwrap.json` if `save` is true. + +This option is an alias for `--package-lock`. ### sign-git-tag diff --git a/deps/npm/doc/misc/npm-index.md b/deps/npm/doc/misc/npm-index.md index 7569a225c7..ed478d84ad 100644 --- a/deps/npm/doc/misc/npm-index.md +++ b/deps/npm/doc/misc/npm-index.md @@ -163,7 +163,7 @@ Search for packages ### npm-shrinkwrap(1) -Lock down dependency versions +Lock down dependency versions for publication ### npm-star(1) @@ -225,10 +225,22 @@ File system structures npm uses Folder Structures Used by npm +### npm-package-locks(5) + +An explanation of npm lockfiles + +### npm-shrinkwrap.json(5) + +A publishable lockfile + ### npmrc(5) The npm config files +### package-lock.json(5) + +A manifestation of the manifest + ### package.json(5) Specifics of npm's package.json handling diff --git a/deps/npm/doc/misc/npm-scripts.md b/deps/npm/doc/misc/npm-scripts.md index 3f048716de..0e9c3bc6e7 100644 --- a/deps/npm/doc/misc/npm-scripts.md +++ b/deps/npm/doc/misc/npm-scripts.md @@ -7,14 +7,20 @@ npm supports the "scripts" property of the package.json script, for the following scripts: * prepublish: - Run BEFORE the package is published. (Also run on local `npm - install` without any arguments. See below.) + Run BEFORE the package is packed and published, as well as on local `npm + install` without any arguments. (See below) * prepare: - Run both BEFORE the package is published, and on local `npm - install` without any arguments. (See below.) This is run + Run both BEFORE the package is packed and published, and on local `npm + install` without any arguments (See below). This is run AFTER `prepublish`, but BEFORE `prepublishOnly`. * prepublishOnly: - Run BEFORE the package is published. (See below.) + Run BEFORE the package is prepared and packed, ONLY on `npm publish`. (See + below.) +* prepack: + run BEFORE a tarball is packed (on `npm pack`, `npm publish`, and when + installing git dependencies) +* postpack: + Run AFTER the tarball has been generated and moved to its final destination. * publish, postpublish: Run AFTER the package is published. * preinstall: |