--- /dev/null
+.TH "NPM\-INSTALL" "1" "October 2016" "" ""
+.SH "NAME"
+\fBnpm-install\fR \- Install a package
+.SH SYNOPSIS
+.P
+.RS 2
+.nf
+npm install (with no args in a package dir)
+npm install <tarball file>
+npm install <tarball url>
+npm install <folder>
+npm install [@<scope>/]<name> [\-\-save|\-\-save\-dev|\-\-save\-optional] [\-\-save\-exact] [\-\-save\-bundle]
+npm install [@<scope>/]<name>@<tag>
+npm install [@<scope>/]<name>@<version>
+npm install [@<scope>/]<name>@<version range>
+npm i (with any of the previous argument usage)
+.fi
+.RE
+.SH DESCRIPTION
+.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 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 (b)
+
+.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\|\.
+.IP \(bu 2
+\fBnpm install <folder>\fP:
+ Install a package that is sitting in a folder on the filesystem\.
+.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\|\.
+ Example:
+.P
+.RS 2
+.nf
+ npm install \./package\.tgz
+.fi
+.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> [\-\-save|\-\-save\-dev|\-\-save\-optional]\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 latest version
+ of the module published on npm\.
+ Example:
+.P
+.RS 2
+.nf
+ npm install sax
+.fi
+.RE
+ \fBnpm install\fP takes 3 exclusive, optional flags which save or update
+ the package version in your main package\.json:
+.RS 0
+.IP \(bu 2
+\fB\-\-save\fP: Package will appear in your \fBdependencies\fP\|\.
+.IP \(bu 2
+\fB\-\-save\-dev\fP: Package will appear in your \fBdevDependencies\fP\|\.
+.IP \(bu 2
+\fB\-\-save\-optional\fP: Package will appear in your \fBoptionalDependencies\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\-\-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\.
+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 \-\-save
+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
+.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:
+ Install a package by cloning a git remote url\. The format of the git
+ url is:
+.P
+.RS 2
+.nf
+ <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit\-ish>]
+.fi
+.RE
+ \fB<protocol>\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, or
+ \fBgit+https\fP\|\. If no \fB<commit\-ish>\fP is specified, then \fBmaster\fP is
+ used\.
+ 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/npm\.git#v1\.0\.27
+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
+.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 you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
+ 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>]\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 if \fB\-\-save\fP is used\.
+ If you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
+ 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 you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
+ 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 you don't specify a \fIcommit\-ish\fR then \fBmaster\fP will be used\.
+ Example:
+.P
+.RS 2
+.nf
+ npm install gitlab:mygitlabuser/myproject
+.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\-\-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\-\-global\fP argument will cause npm to install the package globally
+rather than locally\. See npm help 5 \fBnpm\-folders\fP\|\.
+.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\-\-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
+shrinkwrap file and use the package\.json instead\.
+.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
+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
+install(where, what, family, ancestors)
+fetch what, unpack to <where>/node_modules/<what>
+for each dep in what\.dependencies
+ resolve dep to precise version
+for each dep@version in what\.dependencies
+ not in <where>/node_modules/<what>/node_modules/*
+ and not in <family>
+ add precise version deps to <family>
+ install(<where>/node_modules/<what>, dep, family)
+.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\.
+.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
+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 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 tag
+.IP \(bu 2
+npm help uninstall
+.IP \(bu 2
+npm help shrinkwrap
+.IP \(bu 2
+npm help 5 package\.json
+
+.RE
+
Code Review / simantics / district.git / blobdiff