diff options
Diffstat (limited to 'deps/npm/doc/cli/npm-install.md')
| -rw-r--r-- | deps/npm/doc/cli/npm-install.md | 124 |
1 files changed, 89 insertions, 35 deletions
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. |