diff options
Diffstat (limited to 'deps/npm/doc/cli')
| -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 |
4 files changed, 138 insertions, 235 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) |