diff options
Diffstat (limited to 'deps/npm/html/doc/cli/npm-install.html')
-rw-r--r-- | deps/npm/html/doc/cli/npm-install.html | 123 |
1 files changed, 86 insertions, 37 deletions
diff --git a/deps/npm/html/doc/cli/npm-install.html b/deps/npm/html/doc/cli/npm-install.html index 655a7ac69f0..55eaabcfd33 100644 --- a/deps/npm/html/doc/cli/npm-install.html +++ b/deps/npm/html/doc/cli/npm-install.html @@ -16,16 +16,19 @@ 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: [-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] </code></pre><h2 id="description">DESCRIPTION</h2> <p>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 <a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p> +package has a package-lock or shrinkwrap file, the installation of dependencies +will be driven by that, with an <code>npm-shrinkwrap.json</code> taking precedence if both +files exist. See <a href="../files/package-lock.json.html">package-lock.json(5)</a> and <a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p> <p>A <code>package</code> is:</p> <ul> <li>a) a folder containing a program described by a <code><a href="../files/package.json.html">package.json(5)</a></code> file</li> @@ -53,12 +56,16 @@ after packing it up into a tarball (b).</p> <code>devDependencies</code>.</p> </li> <li><p><code>npm install <folder></code>:</p> -<p> Install a package that is sitting in a folder on the filesystem.</p> +<p> Install the package in the directory as a symlink in the current project. + Its dependencies will be installed before it's linked. If <code><folder></code> sits + inside the root of your project, its dependencies may be hoisted to the + toplevel <code>node_modules</code> as they would for other types of dependencies.</p> </li> <li><p><code>npm install <tarball file></code>:</p> <p> 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 <code>npm link</code>.</p> + using <code>npm link</code>. The filename <em>must</em> use <code>.tar</code>, <code>.tar.gz</code>, or <code>.tgz</code> as + the extension.</p> <p> Example:</p> <pre><code> npm install ./package.tgz </code></pre></li> @@ -68,21 +75,25 @@ after packing it up into a tarball (b).</p> <p> Example:</p> <pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6 </code></pre></li> -<li><p><code>npm install [<@scope>/]<name> [-S|--save|-D|--save-dev|-O|--save-optional]</code>:</p> +<li><p><code>npm install [<@scope>/]<name></code>:</p> <p> Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See <code><a href="../misc/npm-config.html">npm-config(7)</a></code>. The config's default value is <code>latest</code>.)</p> -<p> In most cases, this will install the latest version - of the module published on npm.</p> +<p> In most cases, this will install the version of the modules tagged as + <code>latest</code> on the npm registry.</p> <p> Example:</p> <pre><code> npm install sax -</code></pre><p> <code>npm install</code> takes 3 exclusive, optional flags which save or update - the package version in your main package.json:</p> +</code></pre><p> <code>npm install</code> saves any specified packages into <code>dependencies</code> by default. + Additionally, you can control where and how they get saved with some + additional flags:</p> <ul> -<li><p><code>-S, --save</code>: Package will appear in your <code>dependencies</code>.</p> -</li> +<li><p><code>-P, --save-prod</code>: Package will appear in your <code>dependencies</code>. This is the</p> +<pre><code> default unless `-D` or `-O` are present. +</code></pre></li> <li><p><code>-D, --save-dev</code>: Package will appear in your <code>devDependencies</code>.</p> </li> <li><p><code>-O, --save-optional</code>: Package will appear in your <code>optionalDependencies</code>.</p> +</li> +<li><p><code>--no-save</code>: Prevents saving to <code>dependencies</code>.</p> <p>When using any of the above options to save dependencies to your package.json, there are two additional, optional flags:</p> </li> @@ -91,8 +102,8 @@ exact version rather than using npm's default semver range operator.</p> </li> <li><p><code>-B, --save-bundle</code>: Saved dependencies will also be added to your <code>bundleDependencies</code> list.</p> -<p>Further, if you have an <code>npm-shrinkwrap.json</code> then it will be updated as -well.</p> +<p>Further, if you have an <code>npm-shrinkwrap.json</code> or <code>package-lock.json</code> then it +will be updated as well.</p> <p><code><scope></code> 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 <code><a href="../misc/npm-scope.html">npm-scope(7)</a></code>.</p> @@ -100,13 +111,13 @@ the given scope the default registry is assumed. See <code><a href="../misc/npm- interpret this as a GitHub repository instead, see below. Scopes names must also be followed by a slash.</p> <p>Examples:</p> -<pre><code>npm install sax --save +<pre><code>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 </code></pre></li> </ul> </li> @@ -140,16 +151,24 @@ fetch the package by name if it is not valid. npm install @myorg/privatepackage@">=0.1.0 <0.2.0" </code></pre></li> <li><p><code>npm install <git remote url></code>:</p> -<p> Installs the package from the hosted git provider, cloning it with - <code>git</code>. First it tries via the https (git with github) and if that fails, via ssh.</p> -<pre><code> <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish>] -</code></pre><p> <code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, <code>git+https</code>, - or <code>git+file</code>. - If no <code><commit-ish></code> is specified, then <code>master</code> is used.</p> -<p> If the repository makes use of submodules, those submodules will - be cloned as well.</p> -<p> The following git environment variables are recognized by npm and will be added - to the environment when running git:</p> +<p> Installs the package from the hosted git provider, cloning it with <code>git</code>. + For a full git remote url, only that URL will be attempted.</p> +<pre><code> <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>] +</code></pre><p> <code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, <code>git+https</code>, or + <code>git+file</code>.</p> +<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that + commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> 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 <code>#<commit-ish></code> or <code>#semver:<semver></code> is + specified, then <code>master</code> is used.</p> +<p> If the repository makes use of submodules, those submodules will be cloned + as well.</p> +<p> If the package being installed contains a <code>prepare</code> script, its + <code>dependencies</code> and <code>devDependencies</code> will be installed, and the prepare + script will be run, before the package is packaged and installed.</p> +<p> The following git environment variables are recognized by npm and will be + added to the environment when running git:</p> <ul> <li><code>GIT_ASKPASS</code></li> <li><code>GIT_EXEC_PATH</code></li> @@ -161,6 +180,7 @@ fetch the package by name if it is not valid. <p>See the git man page for details.</p> <p>Examples:</p> <pre><code>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 @@ -172,32 +192,59 @@ GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@g <li><p><code>npm install github:<githubname>/<githubrepo>[#<commit-ish>]</code>:</p> <p> Install the package at <code>https://github.com/githubname/githubrepo</code> by attempting to clone it using <code>git</code>.</p> -<p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p> +<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that + commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> 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 <code>#<commit-ish></code> or <code>#semver:<semver></code> is + specified, then <code>master</code> is used.</p> +<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will + be installed if the package has a <code>prepare</code> script, before the package is + done installing.</p> <p> Examples:</p> <pre><code> npm install mygithubuser/myproject npm install github:mygithubuser/myproject </code></pre></li> -<li><p><code>npm install gist:[<githubname>/]<gistID>[#<commit-ish>]</code>:</p> +<li><p><code>npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]</code>:</p> <p> Install the package at <code>https://gist.github.com/gistID</code> by attempting to clone it using <code>git</code>. The GitHub username associated with the gist is - optional and will not be saved in <code>package.json</code> if <code>-S</code> or <code>--save</code> is used.</p> -<p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p> + optional and will not be saved in <code>package.json</code>.</p> +<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will + be installed if the package has a <code>prepare</code> script, before the package is + done installing.</p> <p> Example:</p> <pre><code> npm install gist:101a11beef </code></pre></li> <li><p><code>npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]</code>:</p> <p> Install the package at <code>https://bitbucket.org/bitbucketname/bitbucketrepo</code> by attempting to clone it using <code>git</code>.</p> -<p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p> +<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that + commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> 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 <code>#<commit-ish></code> or <code>#semver:<semver></code> is + specified, then <code>master</code> is used.</p> +<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will + be installed if the package has a <code>prepare</code> script, before the package is + done installing.</p> <p> Example:</p> <pre><code> npm install bitbucket:mybitbucketuser/myproject </code></pre></li> <li><p><code>npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]</code>:</p> <p> Install the package at <code>https://gitlab.com/gitlabname/gitlabrepo</code> by attempting to clone it using <code>git</code>.</p> -<p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p> +<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that + commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> 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 <code>#<commit-ish></code> or <code>#semver:<semver></code> is + specified, then <code>master</code> is used.</p> +<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will + be installed if the package has a <code>prepare</code> script, before the package is + done installing.</p> <p> Example:</p> <pre><code> npm install gitlab:mygitlabuser/myproject + npm install gitlab:myusr/myproj#semver:^5.0 </code></pre></li> </ul> <p>You may combine multiple arguments, and even multiple types of arguments. @@ -218,7 +265,7 @@ your local <code>node_modules</code> folder with the same layout it uses with th global <code>node_modules</code> folder. Only your direct dependencies will show in <code>node_modules</code> and everything they depend on will be flattened in their <code>node_modules</code> folders. This obviously will eliminate some deduping.</p> -<p>The <code>--ignore-scripts</code> argument will cause npm to not execute any +<p>The <code>--ignore-scripts</code> argument will cause npm to not execute any scripts defined in the package.json. See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code>.</p> <p>The <code>--legacy-bundling</code> 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, @@ -230,7 +277,7 @@ any binaries the package might contain.</p> <p>The <code>--no-optional</code> argument will prevent optional dependencies from being installed.</p> <p>The <code>--no-shrinkwrap</code> argument, which will ignore an available -shrinkwrap file and use the package.json instead.</p> +package lock or shrinkwrap file and use the package.json instead.</p> <p>The <code>--nodedir=/path/to/node/source</code> argument will allow npm to find the node source code so that npm can compile native modules.</p> <p>The <code>--only={prod[uction]|dev[elopment]}</code> argument will cause either only @@ -265,7 +312,9 @@ at the top level because nothing conflicts with it.</p> `-- D@2 +-- D@1 </code></pre><p>Because B's D@1 will be installed in the top level, C now has to install D@2 -privately for itself.</p> +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> <p>See <a href="../files/npm-folders.html">npm-folders(5)</a> for a more detailed description of the specific folder structures that npm creates.</p> <h3 id="limitations-of-npm-s-install-algorithm">Limitations of npm's Install Algorithm</h3> @@ -316,5 +365,5 @@ affects a real use-case, it will be investigated.</p> <tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr> <tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr> </table> -<p id="footer">npm-install — npm@5.0.0-beta.56</p> +<p id="footer">npm-install — npm@5.0.0</p> |