diff options
Diffstat (limited to 'deps/node/deps/npm/doc/cli/npm-install.md')
| -rw-r--r-- | deps/node/deps/npm/doc/cli/npm-install.md | 457 |
1 files changed, 0 insertions, 457 deletions
diff --git a/deps/node/deps/npm/doc/cli/npm-install.md b/deps/node/deps/npm/doc/cli/npm-install.md deleted file mode 100644 index 336311db..00000000 --- a/deps/node/deps/npm/doc/cli/npm-install.md +++ /dev/null @@ -1,457 +0,0 @@ -npm-install(1) -- Install a package -=================================== - -## SYNOPSIS - - npm install (with no args, in package dir) - npm install [<@scope>/]<name> - 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: [-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 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: - -* a) a folder containing a program described by a `package.json(5)` file -* b) a gzipped tarball containing (a) -* c) a url that resolves to (b) -* d) a `<name>@<version>` that is published on the registry (see `npm-registry(7)`) with (c) -* e) a `<name>@<tag>` (see `npm-dist-tag(1)`) that points to (d) -* f) a `<name>` that has a "latest" tag satisfying (e) -* g) a `<git remote url>` that resolves to (a) - -Even if you never publish your package, you can still get a lot of -benefits of using npm if you just want to write a node program (a), and -perhaps if you also want to be able to easily install it elsewhere -after packing it up into a tarball (b). - - -* `npm install` (in package directory, no arguments): - - Install the dependencies in the local node_modules folder. - - In global mode (ie, with `-g` or `--global` appended to the command), - it installs the current package context (ie, the current working - directory) as a global package. - - By default, `npm install` will install all modules listed as dependencies - in `package.json(5)`. - - With the `--production` flag (or when the `NODE_ENV` environment variable - is set to `production`), npm will not install modules listed in - `devDependencies`. - - > NOTE: The `--production` flag has no particular meaning when adding a - dependency to a project. - -* `npm install <folder>`: - - 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`. - - Tarball requirements: - * The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as - the extension. - * The package contents should reside in a subfolder inside the tarball (usually it is called `package/`). npm strips one directory layer when installing the package (an equivalent of `tar x --strip-components=1` is run). - * The package must contain a `package.json` file with `name` and `version` properties. - - Example: - - npm install ./package.tgz - -* `npm install <tarball url>`: - - Fetch the tarball url, and then install it. In order to distinguish between - this and other options, the argument must start with "http://" or "https://" - - Example: - - npm install https://github.com/indexzero/forever/tarball/v0.5.6 - -* `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 version of the modules tagged as - `latest` on the npm registry. - - Example: - - npm install sax - - `npm install` saves any specified packages into `dependencies` by default. - Additionally, you can control where and how they get saved with some - additional flags: - - * `-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: - - * `-E, --save-exact`: Saved dependencies will be configured with an - exact version rather than using npm's default semver range - operator. - - * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list. - - 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 - the given scope the default registry is assumed. See `npm-scope(7)`. - - Note: if you do not include the @-symbol on your scope name, npm will - interpret this as a GitHub repository instead, see below. Scopes names - must also be followed by a slash. - - Examples: - - 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-exact - npm install ansi-regex --save-bundle - - - **Note**: If there is a file or folder named `<name>` in the current - working directory, then it will try to install that, and only try to - fetch the package by name if it is not valid. - -* `npm install [<@scope>/]<name>@<tag>`: - - Install the version of the package that is referenced by the specified tag. - If the tag does not exist in the registry data for that package, then this - will fail. - - Example: - - npm install sax@latest - npm install @myorg/mypackage@latest - -* `npm install [<@scope>/]<name>@<version>`: - - Install the specified version of the package. This will fail if the - version has not been published to the registry. - - Example: - - npm install sax@0.1.1 - npm install @myorg/privatepackage@1.5.0 - -* `npm install [<@scope>/]<name>@<version range>`: - - Install a version of the package matching the specified version range. This - will follow the same rules for resolving dependencies described in `package.json(5)`. - - Note that most version ranges must be put in quotes so that your shell will - treat it as a single argument. - - Example: - - npm install sax@">=0.1.0 <0.2.0" - npm install @myorg/privatepackage@">=0.1.0 <0.2.0" - -* `npm install <git remote url>`: - - 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`. - - 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 the default branch of the repository is used. - - 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: - - * `GIT_ASKPASS` - * `GIT_EXEC_PATH` - * `GIT_PROXY_COMMAND` - * `GIT_SSH` - * `GIT_SSH_COMMAND` - * `GIT_SSL_CAINFO` - * `GIT_SSL_NO_VERIFY` - - See the git man page for details. - - Examples: - - npm install git+ssh://git@github.com:npm/cli.git#v1.0.27 - npm install git+ssh://git@github.com:npm/cli#semver:^5.0 - npm install git+https://isaacs@github.com/npm/cli.git - npm install git://github.com/npm/cli.git#v1.0.27 - GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git - -* `npm install <githubname>/<githubrepo>[#<commit-ish>]`: -* `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`: - - Install the package at `https://github.com/githubname/githubrepo` by - attempting to clone it using `git`. - - 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>|#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`. - - 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 gist:101a11beef - -* `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`: - - Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo` - by attempting to clone it using `git`. - - 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 bitbucket:mybitbucketuser/myproject - -* `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`: - - Install the package at `https://gitlab.com/gitlabname/gitlabrepo` - by attempting to clone it using `git`. - - 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: - - npm install sax@">=0.1.0 <0.2.0" bench supervisor - -The `--tag` argument will apply to all of the specified install targets. If a -tag with the given name exists, the tagged version is preferred over newer -versions. - -The `--dry-run` argument will report in the usual way what the install would -have done without actually installing anything. - -The `--package-lock-only` argument will only update the `package-lock.json`, -instead of checking `node_modules` and downloading dependencies. - -The `-f` or `--force` argument will force npm to fetch remote resources even if a -local copy exists on disk. - - npm install sax --force - -The `-g` or `--global` argument will cause npm to install the package globally -rather than locally. See `npm-folders(5)`. - -The `--global-style` argument will cause npm to install the package into -your local `node_modules` folder with the same layout it uses with the -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 -scripts defined in the package.json. See `npm-scripts(7)`. - -The `--legacy-bundling` argument will cause npm to install the package such -that versions of npm prior to 1.4, such as the one included with node 0.8, -can install the package. This eliminates all automatic deduping. - -The `--link` argument will cause npm to link global installs into the -local space in some cases. - -The `--no-bin-links` argument will prevent npm from creating symlinks for -any binaries the package might contain. - -The `--no-optional` argument will prevent optional dependencies from -being installed. - -The `--no-shrinkwrap` argument, which will ignore an available -package lock or shrinkwrap file and use the package.json instead. - -The `--no-package-lock` argument will prevent npm from creating a -`package-lock.json` file. When running with package-lock's disabled npm -will not automatically prune your node modules when installing. - -The `--nodedir=/path/to/node/source` argument will allow npm to find the -node source code so that npm can compile native modules. - -The `--only={prod[uction]|dev[elopment]}` argument will cause either only -`devDependencies` or only non-`devDependencies` to be installed regardless of the `NODE_ENV`. - -The `--no-audit` argument can be used to disable sending of audit reports to -the configured registries. See `npm-audit(1)` for details on what is sent. - -See `npm-config(7)`. Many of the configuration params have some -effect on installation, since that's most of what npm does. - -## ALGORITHM - -To install a package, npm uses the following algorithm: - - load the existing node_modules tree from disk - clone the tree - fetch the package.json and assorted metadata and add it to the clone - walk the clone and add any missing dependencies - dependencies will be added as close to the top as is possible - without breaking any other modules - compare the original tree with the cloned tree and make a list of - actions to take to convert one to the other - execute all of the actions, deepest first - kinds of actions are install, update, remove and move - -For this `package{dep}` structure: `A{B,C}, B{C}, C{D}`, -this algorithm produces: - - A - +-- B - +-- C - +-- D - -That is, the dependency from B to C is satisfied by the fact that A -already caused C to be installed at a higher level. D is still installed -at the top level because nothing conflicts with it. - -For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces: - - A - +-- B - +-- C - `-- D@2 - +-- D@1 - -Because B's D@1 will be installed in the top level, C now has to install D@2 -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. - -### Limitations of npm's Install Algorithm - -npm will refuse to install any package with an identical name to the -current package. This can be overridden with the `--force` flag, but in -most cases can simply be addressed by changing the local package name. - -There are some very rare and pathological edge-cases where a cycle can -cause npm to try to install a never-ending tree of packages. Here is -the simplest case: - - A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ... - -where `A` is some version of a package, and `A'` is a different version -of the same package. Because `B` depends on a different version of `A` -than the one that is already in the tree, it must install a separate -copy. The same is true of `A'`, which must install `B'`. Because `B'` -depends on the original version of `A`, which has been overridden, the -cycle falls into infinite regress. - -To avoid this situation, npm flat-out refuses to install any -`name@version` that is already present anywhere in the tree of package -folder ancestors. A more correct, but more complex, solution would be -to symlink the existing version into the new location. If this ever -affects a real use-case, it will be investigated. - -## SEE ALSO - -* npm-folders(5) -* npm-update(1) -* npm-audit(1) -* npm-link(1) -* npm-rebuild(1) -* npm-scripts(7) -* npm-build(1) -* npm-config(1) -* npm-config(7) -* npmrc(5) -* npm-registry(7) -* npm-dist-tag(1) -* npm-uninstall(1) -* npm-shrinkwrap(1) -* package.json(5) |