summaryrefslogtreecommitdiff
path: root/deps/node/deps/npm/man/man1/npm-install.1
diff options
context:
space:
mode:
Diffstat (limited to 'deps/node/deps/npm/man/man1/npm-install.1')
-rw-r--r--deps/node/deps/npm/man/man1/npm-install.1545
1 files changed, 0 insertions, 545 deletions
diff --git a/deps/node/deps/npm/man/man1/npm-install.1 b/deps/node/deps/npm/man/man1/npm-install.1
deleted file mode 100644
index f2cdfeda..00000000
--- a/deps/node/deps/npm/man/man1/npm-install.1
+++ /dev/null
@@ -1,545 +0,0 @@
-.TH "NPM\-INSTALL" "1" "January 2019" "" ""
-.SH "NAME"
-\fBnpm-install\fR \- Install a package
-.SH SYNOPSIS
-.P
-.RS 2
-.nf
-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]
-.fi
-.RE
-.SH DESCRIPTION
-.P
-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 \fBnpm\-shrinkwrap\.json\fP taking precedence if both
-files exist\. See npm help 5 package\-lock\.json and npm help shrinkwrap\.
-.P
-A \fBpackage\fP is:
-.RS 0
-.IP \(bu 2
-a) a folder containing a program described by a npm help 5 \fBpackage\.json\fP file
-.IP \(bu 2
-b) a gzipped tarball containing (a)
-.IP \(bu 2
-c) a url that resolves to (b)
-.IP \(bu 2
-d) a \fB<name>@<version>\fP that is published on the registry (see npm help 7 \fBnpm\-registry\fP) with (c)
-.IP \(bu 2
-e) a \fB<name>@<tag>\fP (see npm help \fBnpm\-dist\-tag\fP) that points to (d)
-.IP \(bu 2
-f) a \fB<name>\fP that has a "latest" tag satisfying (e)
-.IP \(bu 2
-g) a \fB<git remote url>\fP that resolves to (a)
-
-.RE
-.P
-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)\.
-.RS 0
-.IP \(bu 2
-\fBnpm install\fP (in package directory, no arguments):
- Install the dependencies in the local node_modules folder\.
- In global mode (ie, with \fB\-g\fP or \fB\-\-global\fP appended to the command),
- it installs the current package context (ie, the current working
- directory) as a global package\.
- By default, \fBnpm install\fP will install all modules listed as dependencies
- in npm help 5 \fBpackage\.json\fP\|\.
- With the \fB\-\-production\fP flag (or when the \fBNODE_ENV\fP environment variable
- is set to \fBproduction\fP), npm will not install modules listed in
- \fBdevDependencies\fP\|\.
-.QP
-NOTE: The \fB\-\-production\fP flag has no particular meaning when adding a
- dependency to a project\.
-
-.
-.IP \(bu 2
-\fBnpm install <folder>\fP:
- Install the package in the directory as a symlink in the current project\.
- Its dependencies will be installed before it's linked\. If \fB<folder>\fP sits
- inside the root of your project, its dependencies may be hoisted to the
- toplevel \fBnode_modules\fP as they would for other types of dependencies\.
-.IP \(bu 2
-\fBnpm install <tarball file>\fP:
- Install a package that is sitting on the filesystem\. Note: if you just want
- to link a dev directory into your npm root, you can do this more easily by
- using \fBnpm link\fP\|\.
- Tarball requirements:
-.RS 0
-.IP \(bu 2
-The filename \fImust\fR use \fB\|\.tar\fP, \fB\|\.tar\.gz\fP, or \fB\|\.tgz\fP as
-the extension\.
-.IP \(bu 2
-The package contents should reside in a subfolder inside the tarball (usually it is called \fBpackage/\fP)\. npm strips one directory layer when installing the package (an equivalent of \fBtar x \-\-strip\-components=1\fP is run)\.
-.IP \(bu 2
-The package must contain a \fBpackage\.json\fP file with \fBname\fP and \fBversion\fP properties\.
-Example:
-.P
-.RS 2
-.nf
-npm install \./package\.tgz
-.fi
-.RE
-
-.RE
-.IP \(bu 2
-\fBnpm install <tarball url>\fP:
- 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:
-.P
-.RS 2
-.nf
- npm install https://github\.com/indexzero/forever/tarball/v0\.5\.6
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install [<@scope>/]<name>\fP:
- Do a \fB<name>@<tag>\fP install, where \fB<tag>\fP is the "tag" config\. (See
- npm help 7 \fBnpm\-config\fP\|\. The config's default value is \fBlatest\fP\|\.)
- In most cases, this will install the version of the modules tagged as
- \fBlatest\fP on the npm registry\.
- Example:
-.P
-.RS 2
-.nf
- npm install sax
-.fi
-.RE
- \fBnpm install\fP saves any specified packages into \fBdependencies\fP by default\.
- Additionally, you can control where and how they get saved with some
- additional flags:
-.RS 0
-.IP \(bu 2
-\fB\-P, \-\-save\-prod\fP: Package will appear in your \fBdependencies\fP\|\. This is the
-.P
-.RS 2
-.nf
- default unless `\-D` or `\-O` are present\.
-.fi
-.RE
-.IP \(bu 2
-\fB\-D, \-\-save\-dev\fP: Package will appear in your \fBdevDependencies\fP\|\.
-.IP \(bu 2
-\fB\-O, \-\-save\-optional\fP: Package will appear in your \fBoptionalDependencies\fP\|\.
-.IP \(bu 2
-\fB\-\-no\-save\fP: Prevents saving to \fBdependencies\fP\|\.
-When using any of the above options to save dependencies to your
-package\.json, there are two additional, optional flags:
-.IP \(bu 2
-\fB\-E, \-\-save\-exact\fP: Saved dependencies will be configured with an
-exact version rather than using npm's default semver range
-operator\.
-.IP \(bu 2
-\fB\-B, \-\-save\-bundle\fP: Saved dependencies will also be added to your \fBbundleDependencies\fP list\.
-Further, if you have an \fBnpm\-shrinkwrap\.json\fP or \fBpackage\-lock\.json\fP then it
-will be updated as well\.
-\fB<scope>\fP is optional\. The package will be downloaded from the registry
-associated with the specified scope\. If no registry is associated with
-the given scope the default registry is assumed\. See npm help 7 \fBnpm\-scope\fP\|\.
-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:
-.P
-.RS 2
-.nf
-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
-.fi
-.RE
-
-.RE
-
-.RE
-.P
-.RS 2
-.nf
-**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\.
-.fi
-.RE
-.RS 0
-.IP \(bu 2
-\fBnpm install [<@scope>/]<name>@<tag>\fP:
- 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:
-.P
-.RS 2
-.nf
- npm install sax@latest
- npm install @myorg/mypackage@latest
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install [<@scope>/]<name>@<version>\fP:
- Install the specified version of the package\. This will fail if the
- version has not been published to the registry\.
- Example:
-.P
-.RS 2
-.nf
- npm install sax@0\.1\.1
- npm install @myorg/privatepackage@1\.5\.0
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install [<@scope>/]<name>@<version range>\fP:
- Install a version of the package matching the specified version range\. This
- will follow the same rules for resolving dependencies described in npm help 5 \fBpackage\.json\fP\|\.
- Note that most version ranges must be put in quotes so that your shell will
- treat it as a single argument\.
- Example:
-.P
-.RS 2
-.nf
- npm install sax@">=0\.1\.0 <0\.2\.0"
- npm install @myorg/privatepackage@">=0\.1\.0 <0\.2\.0"
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install <git remote url>\fP:
- Installs the package from the hosted git provider, cloning it with \fBgit\fP\|\.
- For a full git remote url, only that URL will be attempted\.
-.P
-.RS 2
-.nf
- <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit\-ish> | #semver:<semver>]
-.fi
-.RE
- \fB<protocol>\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, \fBgit+https\fP, or
- \fBgit+file\fP\|\.
- If \fB#<commit\-ish>\fP is provided, it will be used to clone exactly that
- commit\. If the commit\-ish has the format \fB#semver:<semver>\fP, \fB<semver>\fP can
- be any valid semver range or exact version, and npm will look for any tags
- or refs matching that range in the remote repository, much as it would for a
- registry dependency\. If neither \fB#<commit\-ish>\fP or \fB#semver:<semver>\fP 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 \fBprepare\fP script, its
- \fBdependencies\fP and \fBdevDependencies\fP will be installed, and the prepare
- script will be run, before the package is packaged and installed\.
- The following git environment variables are recognized by npm and will be
- added to the environment when running git:
-.RS 0
-.IP \(bu 2
-\fBGIT_ASKPASS\fP
-.IP \(bu 2
-\fBGIT_EXEC_PATH\fP
-.IP \(bu 2
-\fBGIT_PROXY_COMMAND\fP
-.IP \(bu 2
-\fBGIT_SSH\fP
-.IP \(bu 2
-\fBGIT_SSH_COMMAND\fP
-.IP \(bu 2
-\fBGIT_SSL_CAINFO\fP
-.IP \(bu 2
-\fBGIT_SSL_NO_VERIFY\fP
-See the git man page for details\.
-Examples:
-.P
-.RS 2
-.nf
-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
-.fi
-.RE
-
-.RE
-.IP \(bu 2
-\fBnpm install <githubname>/<githubrepo>[#<commit\-ish>]\fP:
-.IP \(bu 2
-\fBnpm install github:<githubname>/<githubrepo>[#<commit\-ish>]\fP:
- Install the package at \fBhttps://github\.com/githubname/githubrepo\fP by
- attempting to clone it using \fBgit\fP\|\.
- If \fB#<commit\-ish>\fP is provided, it will be used to clone exactly that
- commit\. If the commit\-ish has the format \fB#semver:<semver>\fP, \fB<semver>\fP can
- be any valid semver range or exact version, and npm will look for any tags
- or refs matching that range in the remote repository, much as it would for a
- registry dependency\. If neither \fB#<commit\-ish>\fP or \fB#semver:<semver>\fP is
- specified, then \fBmaster\fP is used\.
- As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will
- be installed if the package has a \fBprepare\fP script, before the package is
- done installing\.
- Examples:
-.P
-.RS 2
-.nf
- npm install mygithubuser/myproject
- npm install github:mygithubuser/myproject
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install gist:[<githubname>/]<gistID>[#<commit\-ish>|#semver:<semver>]\fP:
- Install the package at \fBhttps://gist\.github\.com/gistID\fP by attempting to
- clone it using \fBgit\fP\|\. The GitHub username associated with the gist is
- optional and will not be saved in \fBpackage\.json\fP\|\.
- As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will
- be installed if the package has a \fBprepare\fP script, before the package is
- done installing\.
- Example:
-.P
-.RS 2
-.nf
- npm install gist:101a11beef
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit\-ish>]\fP:
- Install the package at \fBhttps://bitbucket\.org/bitbucketname/bitbucketrepo\fP
- by attempting to clone it using \fBgit\fP\|\.
- If \fB#<commit\-ish>\fP is provided, it will be used to clone exactly that
- commit\. If the commit\-ish has the format \fB#semver:<semver>\fP, \fB<semver>\fP can
- be any valid semver range or exact version, and npm will look for any tags
- or refs matching that range in the remote repository, much as it would for a
- registry dependency\. If neither \fB#<commit\-ish>\fP or \fB#semver:<semver>\fP is
- specified, then \fBmaster\fP is used\.
- As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will
- be installed if the package has a \fBprepare\fP script, before the package is
- done installing\.
- Example:
-.P
-.RS 2
-.nf
- npm install bitbucket:mybitbucketuser/myproject
-.fi
-.RE
-.IP \(bu 2
-\fBnpm install gitlab:<gitlabname>/<gitlabrepo>[#<commit\-ish>]\fP:
- Install the package at \fBhttps://gitlab\.com/gitlabname/gitlabrepo\fP
- by attempting to clone it using \fBgit\fP\|\.
- If \fB#<commit\-ish>\fP is provided, it will be used to clone exactly that
- commit\. If the commit\-ish has the format \fB#semver:<semver>\fP, \fB<semver>\fP can
- be any valid semver range or exact version, and npm will look for any tags
- or refs matching that range in the remote repository, much as it would for a
- registry dependency\. If neither \fB#<commit\-ish>\fP or \fB#semver:<semver>\fP is
- specified, then \fBmaster\fP is used\.
- As with regular git dependencies, \fBdependencies\fP and \fBdevDependencies\fP will
- be installed if the package has a \fBprepare\fP script, before the package is
- done installing\.
- Example:
-.P
-.RS 2
-.nf
- npm install gitlab:mygitlabuser/myproject
- npm install gitlab:myusr/myproj#semver:^5\.0
-.fi
-.RE
-
-.RE
-.P
-You may combine multiple arguments, and even multiple types of arguments\.
-For example:
-.P
-.RS 2
-.nf
-npm install sax@">=0\.1\.0 <0\.2\.0" bench supervisor
-.fi
-.RE
-.P
-The \fB\-\-tag\fP 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\.
-.P
-The \fB\-\-dry\-run\fP argument will report in the usual way what the install would
-have done without actually installing anything\.
-.P
-The \fB\-\-package\-lock\-only\fP argument will only update the \fBpackage\-lock\.json\fP,
-instead of checking \fBnode_modules\fP and downloading dependencies\.
-.P
-The \fB\-f\fP or \fB\-\-force\fP argument will force npm to fetch remote resources even if a
-local copy exists on disk\.
-.P
-.RS 2
-.nf
-npm install sax \-\-force
-.fi
-.RE
-.P
-The \fB\-g\fP or \fB\-\-global\fP argument will cause npm to install the package globally
-rather than locally\. See npm help 5 \fBnpm\-folders\fP\|\.
-.P
-The \fB\-\-global\-style\fP argument will cause npm to install the package into
-your local \fBnode_modules\fP folder with the same layout it uses with the
-global \fBnode_modules\fP folder\. Only your direct dependencies will show in
-\fBnode_modules\fP and everything they depend on will be flattened in their
-\fBnode_modules\fP folders\. This obviously will eliminate some deduping\.
-.P
-The \fB\-\-ignore\-scripts\fP argument will cause npm to not execute any
-scripts defined in the package\.json\. See npm help 7 \fBnpm\-scripts\fP\|\.
-.P
-The \fB\-\-legacy\-bundling\fP argument will cause npm to install the package such
-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\.
-.P
-The \fB\-\-link\fP argument will cause npm to link global installs into the
-local space in some cases\.
-.P
-The \fB\-\-no\-bin\-links\fP argument will prevent npm from creating symlinks for
-any binaries the package might contain\.
-.P
-The \fB\-\-no\-optional\fP argument will prevent optional dependencies from
-being installed\.
-.P
-The \fB\-\-no\-shrinkwrap\fP argument, which will ignore an available
-package lock or shrinkwrap file and use the package\.json instead\.
-.P
-The \fB\-\-no\-package\-lock\fP argument will prevent npm from creating a
-\fBpackage\-lock\.json\fP file\. When running with package\-lock's disabled npm
-will not automatically prune your node modules when installing\.
-.P
-The \fB\-\-nodedir=/path/to/node/source\fP argument will allow npm to find the
-node source code so that npm can compile native modules\.
-.P
-The \fB\-\-only={prod[uction]|dev[elopment]}\fP argument will cause either only
-\fBdevDependencies\fP or only non\-\fBdevDependencies\fP to be installed regardless of the \fBNODE_ENV\fP\|\.
-.P
-The \fB\-\-no\-audit\fP argument can be used to disable sending of audit reports to
-the configured registries\. See npm help \fBnpm\-audit\fP for details on what is sent\.
-.P
-See npm help 7 \fBnpm\-config\fP\|\. Many of the configuration params have some
-effect on installation, since that's most of what npm does\.
-.SH ALGORITHM
-.P
-To install a package, npm uses the following algorithm:
-.P
-.RS 2
-.nf
-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
-.fi
-.RE
-.P
-For this \fBpackage{dep}\fP structure: \fBA{B,C}, B{C}, C{D}\fP,
-this algorithm produces:
-.P
-.RS 2
-.nf
-A
-+\-\- B
-+\-\- C
-+\-\- D
-.fi
-.RE
-.P
-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\.
-.P
-For \fBA{B,C}, B{C,D@1}, C{D@2}\fP, this algorithm produces:
-.P
-.RS 2
-.nf
-A
-+\-\- B
-+\-\- C
- `\-\- D@2
-+\-\- D@1
-.fi
-.RE
-.P
-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\.
-.P
-See npm help 5 folders for a more detailed description of the specific
-folder structures that npm creates\.
-.SS Limitations of npm's Install Algorithm
-.P
-npm will refuse to install any package with an identical name to the
-current package\. This can be overridden with the \fB\-\-force\fP flag, but in
-most cases can simply be addressed by changing the local package name\.
-.P
-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:
-.P
-.RS 2
-.nf
-A \-> B \-> A' \-> B' \-> A \-> B \-> A' \-> B' \-> A \-> \.\.\.
-.fi
-.RE
-.P
-where \fBA\fP is some version of a package, and \fBA'\fP is a different version
-of the same package\. Because \fBB\fP depends on a different version of \fBA\fP
-than the one that is already in the tree, it must install a separate
-copy\. The same is true of \fBA'\fP, which must install \fBB'\fP\|\. Because \fBB'\fP
-depends on the original version of \fBA\fP, which has been overridden, the
-cycle falls into infinite regress\.
-.P
-To avoid this situation, npm flat\-out refuses to install any
-\fBname@version\fP 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\.
-.SH SEE ALSO
-.RS 0
-.IP \(bu 2
-npm help 5 folders
-.IP \(bu 2
-npm help update
-.IP \(bu 2
-npm help audit
-.IP \(bu 2
-npm help link
-.IP \(bu 2
-npm help rebuild
-.IP \(bu 2
-npm help 7 scripts
-.IP \(bu 2
-npm help build
-.IP \(bu 2
-npm help config
-.IP \(bu 2
-npm help 7 config
-.IP \(bu 2
-npm help 5 npmrc
-.IP \(bu 2
-npm help 7 registry
-.IP \(bu 2
-npm help dist\-tag
-.IP \(bu 2
-npm help uninstall
-.IP \(bu 2
-npm help shrinkwrap
-.IP \(bu 2
-npm help 5 package\.json
-
-.RE
-