deps: upgrade npm to 3.6.0

PR-URL: https://github.com/nodejs/node/pull/4958
Reviewed-By: Myles Borins <mborins@us.ibm.com>
Reviewed-By: Kat Marchán <kzm@sykosomatic.org>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

16 files changed, 152 insertions, 35 deletions

diff --git a/deps/npm/doc/cli/npm-adduser.md b/deps/npm/doc/cli/npm-adduser.md
index 80d0f9855b..24d3611e61 100644
--- a/deps/npm/doc/cli/npm-adduser.md
+++ b/deps/npm/doc/cli/npm-adduser.md
@@ -28,7 +28,7 @@ your existing record.
 
 ### registry
 
-Default: http://registry.npmjs.org/
+Default: https://registry.npmjs.org/
 
 The base URL of the npm package registry. If `scope` is also specified,
 this registry will only be used for packages with that scope. See `npm-scope(7)`.
diff --git a/deps/npm/doc/cli/npm-dedupe.md b/deps/npm/doc/cli/npm-dedupe.md
index c963dfa8e9..ed8dca81f5 100644
--- a/deps/npm/doc/cli/npm-dedupe.md
+++ b/deps/npm/doc/cli/npm-dedupe.md
@@ -3,8 +3,8 @@ npm-dedupe(1) -- Reduce duplication
 
 ## SYNOPSIS
 
-    npm dedupe [package names...]
-    npm ddp [package names...]
+    npm dedupe
+    npm ddp
 
 ## DESCRIPTION
 
diff --git a/deps/npm/doc/cli/npm-dist-tag.md b/deps/npm/doc/cli/npm-dist-tag.md
index ce4f7ed4d5..06721bbae6 100644
--- a/deps/npm/doc/cli/npm-dist-tag.md
+++ b/deps/npm/doc/cli/npm-dist-tag.md
@@ -33,17 +33,30 @@ When installing dependencies, a preferred tagged version may be specified:
 
 This also applies to `npm dedupe`.
 
-Publishing a package sets the "latest" tag to the published version unless the
+Publishing a package sets the `latest` tag to the published version unless the
 `--tag` option is used. For example, `npm publish --tag=beta`.
 
+By default, `npm install <pkg>` (without any `@<version>` or `@<tag>`
+specifier) installs the `latest` tag.
+
 ## PURPOSE
 
-Tags can be used to provide an alias instead of version numbers.  For
-example, `npm` currently uses the tag "next" to identify the upcoming
-version, and the tag "latest" to identify the current version.
+Tags can be used to provide an alias instead of version numbers.
+
+For example, a project might choose to have multiple streams of development
+and use a different tag for each stream,
+e.g., `stable`, `beta`, `dev`, `canary`.
+
+By default, the `latest` tag is used by npm to identify the current version of
+a package, and `npm install <pkg>` (without any `@<version>` or `@<tag>`
+specifier) installs the `latest` tag. Typically, projects only use the `latest`
+tag for stable release versions, and use other tags for unstable versions such
+as prereleases.
+
+The `next` tag is used by some projects to identify the upcoming version.
 
-A project might choose to have multiple streams of development, e.g.,
-"stable", "canary".
+By default, other than `latest`, no tag has any special significance to npm
+itself.
 
 ## CAVEATS
 
@@ -69,5 +82,4 @@ begin with a number or the letter `v`.
 * npm-registry(7)
 * npm-config(1)
 * npm-config(7)
-* npm-tag(3)
 * npmrc(5)
diff --git a/deps/npm/doc/cli/npm-install-test.md b/deps/npm/doc/cli/npm-install-test.md
new file mode 100644
index 0000000000..471b36f16b
--- /dev/null
+++ b/deps/npm/doc/cli/npm-install-test.md
@@ -0,0 +1,25 @@
+# npm install-test(1) -- Install package(s) and run tests
+
+## SYNOPSIS
+
+    npm install-test (with no args, in package dir)
+    npm install-test [<@scope>/]<name>
+    npm install-test [<@scope>/]<name>@<tag>
+    npm install-test [<@scope>/]<name>@<version>
+    npm install-test [<@scope>/]<name>@<version range>
+    npm install-test <tarball file>
+    npm install-test <tarball url>
+    npm install-test <folder>
+
+    alias: npm it
+    common options: [--save|--save-dev|--save-optional] [--save-exact] [--dry-run]
+
+## DESCRIPTION
+
+This command runs an `npm install` followed immediately by an `npm test`. It
+takes exactly the same arguments as `npm install`.
+
+## SEE ALSO
+
+- npm-install(1)
+- npm-test(1)
diff --git a/deps/npm/doc/cli/npm-install.md b/deps/npm/doc/cli/npm-install.md
index 75e9e13fd9..36566af0df 100644
--- a/deps/npm/doc/cli/npm-install.md
+++ b/deps/npm/doc/cli/npm-install.md
@@ -23,11 +23,11 @@ by that. See npm-shrinkwrap(1).
 
 A `package` is:
 
-* a) a folder containing a program described by a package.json file
+* 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>` that points to (d)
+* 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)
 
@@ -45,7 +45,9 @@ after packing it up into a tarball (b).
     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.
+    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`.
@@ -76,7 +78,7 @@ after packing it up into a tarball (b).
 * `npm install [<@scope>/]<name> [-S|--save|-D|--save-dev|-O|--save-optional]`:
 
     Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See
-    `npm-config(7)`.)
+    `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.
@@ -257,6 +259,16 @@ local copy exists on disk.
 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 elminate some deduping.
+
+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.
 
@@ -353,5 +365,6 @@ affects a real use-case, it will be investigated.
 * npmrc(5)
 * npm-registry(7)
 * npm-tag(1)
-* npm-rm(1)
+* npm-uninstall(1)
 * npm-shrinkwrap(1)
+* package.json(5)
diff --git a/deps/npm/doc/cli/npm-logout.md b/deps/npm/doc/cli/npm-logout.md
index 411ea67e6c..59f49cc25a 100644
--- a/deps/npm/doc/cli/npm-logout.md
+++ b/deps/npm/doc/cli/npm-logout.md
@@ -22,7 +22,7 @@ connected to that scope, if set.
 
 ### registry
 
-Default: http://registry.npmjs.org/
+Default: https://registry.npmjs.org/
 
 The base URL of the npm package registry. If `scope` is also specified,
 it takes precedence.
diff --git a/deps/npm/doc/cli/npm-outdated.md b/deps/npm/doc/cli/npm-outdated.md
index bdc9b9b8ed..0792be24a7 100644
--- a/deps/npm/doc/cli/npm-outdated.md
+++ b/deps/npm/doc/cli/npm-outdated.md
@@ -10,9 +10,61 @@ npm-outdated(1) -- Check for outdated packages
 This command will check the registry to see if any (or, specific) installed
 packages are currently outdated.
 
-The resulting field 'wanted' shows the latest version according to the
-version specified in the package.json, the field 'latest' the very latest
-version of the package.
+In the output:
+
+* `wanted` is the maximum version of the package that satisfies the semver
+  range specified in `package.json`. If there's no available semver range (i.e.
+  you're running `npm outdated --global`, or the package isn't included in
+  `package.json`), then `wanted` shows the currently-installed version.
+* `latest` is the version of the package tagged as latest in the registry.
+  Running `npm publish` with no special configuration will publish the package
+  with a dist-tag of `latest`. This may or may not be the maximum version of
+  the package, or the most-recently published version of the package, depending
+  on how the package's developer manages the latest dist-tag(1).
+* `location` is where in the dependency tree the package is located. Note that
+  `npm outdated` defaults to a depth of 0, so unless you override that, you'll
+  always be seeing only top-level dependencies that are outdated.
+* `package type` (when using `--long` / `-l`) tells you whether this package is
+  a `dependency` or a `devDependency`. Packages not included in `package.json`
+  are always marked `dependencies`.
+
+### An example
+
+```
+$ npm outdated
+Package      Current   Wanted   Latest  Location
+glob          5.0.15   5.0.15    6.0.1  test-outdated-output
+nothingness    0.0.3      git      git  test-outdated-output
+npm            3.5.1    3.5.2    3.5.1  test-outdated-output
+local-dev      0.0.3   linked   linked  test-outdated-output
+once           1.3.2    1.3.3    1.3.3  test-outdated-output
+```
+
+With these `dependencies`:
+```json
+{
+  "glob": "^5.0.15",
+  "nothingness": "github:othiym23/nothingness#master",
+  "npm": "^3.5.1",
+  "once": "^1.3.1"
+}
+```
+
+A few things to note:
+
+* `glob` requires `^5`, which prevents npm from installing `glob@6`, which is
+  outside the semver range.
+* Git dependencies will always be reinstalled, because of how they're specified.
+  The installed committish might satisfy the dependency specifier (if it's
+  something immutable, like a commit SHA), or it might not, so `npm outdated` and
+  `npm update` have to fetch Git repos to check. This is why currently doing a
+  reinstall of a Git dependency always forces a new clone and install.
+* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because npm
+  uses dist-tags to manage its `latest` and `next` release channels. `npm update`
+  will install the _newest_ version, but `npm install npm` (with no semver range)
+  will install whatever's tagged as `latest`.
+* `once` is just plain out of date. Reinstalling `node_modules` from scratch or
+  running `npm update` will bring it up to spec.
 
 ## CONFIGURATION
 
@@ -47,6 +99,7 @@ project.
 
 ### depth
 
+* Default: 0
 * Type: Int
 
 Max depth for checking dependency tree.
@@ -54,5 +107,6 @@ Max depth for checking dependency tree.
 ## SEE ALSO
 
 * npm-update(1)
+* npm-dist-tag(1)
 * npm-registry(7)
 * npm-folders(5)
diff --git a/deps/npm/doc/cli/npm-prune.md b/deps/npm/doc/cli/npm-prune.md
index 9089122117..c7f340ca7b 100644
--- a/deps/npm/doc/cli/npm-prune.md
+++ b/deps/npm/doc/cli/npm-prune.md
@@ -21,6 +21,6 @@ negate `NODE_ENV` being set to `production`.
 
 ## SEE ALSO
 
-* npm-rm(1)
+* npm-uninstall(1)
 * npm-folders(5)
 * npm-ls(1)
diff --git a/deps/npm/doc/cli/npm-publish.md b/deps/npm/doc/cli/npm-publish.md
index 8e4da32cd5..4ffefb8823 100644
--- a/deps/npm/doc/cli/npm-publish.md
+++ b/deps/npm/doc/cli/npm-publish.md
@@ -11,9 +11,12 @@ npm-publish(1) -- Publish a package
 
 ## DESCRIPTION
 
-Publishes a package to the registry so that it can be installed by name. See
-`npm-developers(7)` for details on what's included in the published package, as
-well as details on how the package is built.
+Publishes a package to the registry so that it can be installed by name. All
+files in the package directory are included if no local `.gitignore` or
+`.npmignore` file exists. If both files exist and a file is ignored by
+`.gitignore` but not by `.npmignore` then it will be included.  See
+`npm-developers(7)` for full details on what's included in the published
+package, as well as details on how the package is built.
 
 By default npm will publish to the public registry. This can be overridden by
 specifying a different default registry or using a `npm-scope(7)` in the name
@@ -29,7 +32,8 @@ specifying a different default registry or using a `npm-scope(7)` in the name
 * `[--tag <tag>]`
   Registers the published package with the given tag, such that `npm install
   <name>@<tag>` will install this version.  By default, `npm publish` updates
-  and `npm install` installs the `latest` tag.
+  and `npm install` installs the `latest` tag. See `npm-dist-tag(1)` for
+  details about tags.
 
 * `[--access <public|restricted>]`
   Tells the registry whether this package should be published as public or
diff --git a/deps/npm/doc/cli/npm-run-script.md b/deps/npm/doc/cli/npm-run-script.md
index 1e956adcc0..b8da1f09f3 100644
--- a/deps/npm/doc/cli/npm-run-script.md
+++ b/deps/npm/doc/cli/npm-run-script.md
@@ -40,6 +40,9 @@ you should write:
 
 instead of `"scripts": {"test": "node_modules/.bin/tap test/\*.js"}` to run your tests.
 
+If you try to run a script without having a `node_modules` directory and it fails,
+you will be given a warning to run `npm install`, just in case you've forgotten.
+
 ## SEE ALSO
 
 * npm-scripts(7)
diff --git a/deps/npm/doc/cli/npm-start.md b/deps/npm/doc/cli/npm-start.md
index 759de221f3..94c468c296 100644
--- a/deps/npm/doc/cli/npm-start.md
+++ b/deps/npm/doc/cli/npm-start.md
@@ -7,7 +7,13 @@ npm-start(1) -- Start a package
 
 ## DESCRIPTION
 
-This runs a package's "start" script, if one was provided.
+This runs an arbitrary command specified in the package's `"start"` property of
+its `"scripts"` object. If no `"start"` property is specified on the
+`"scripts"` object, it will run `node server.js`.
+
+As of [`npm@2.0.0`](http://blog.npmjs.org/post/98131109725/npm-2-0-0), you can
+use custom arguments when executing scripts. Refer to npm-run-script(1) for
+more details.
 
 ## SEE ALSO
 
diff --git a/deps/npm/doc/cli/npm-team.md b/deps/npm/doc/cli/npm-team.md
index 08856ed3ec..5a8b4b63e3 100644
--- a/deps/npm/doc/cli/npm-team.md
+++ b/deps/npm/doc/cli/npm-team.md
@@ -21,7 +21,7 @@ handle permissions for packages.
 Teams must always be fully qualified with the organization/scope they belong to
 when operating on them, separated by a colon (`:`). That is, if you have a
 `developers` team on a `foo` organization, you must always refer to that team as
-`developers:foo` in these commands.
+`foo:developers` in these commands.
 
 * create / destroy:
   Create a new team, or destroy an existing one.
diff --git a/deps/npm/doc/cli/npm-uninstall.md b/deps/npm/doc/cli/npm-uninstall.md
index 97d72d2c5c..e870b23d5c 100644
--- a/deps/npm/doc/cli/npm-uninstall.md
+++ b/deps/npm/doc/cli/npm-uninstall.md
@@ -1,4 +1,4 @@
-npm-rm(1) -- Remove a package
+npm-uninstall(1) -- Remove a package
 =============================
 
 ## SYNOPSIS
diff --git a/deps/npm/doc/cli/npm-update.md b/deps/npm/doc/cli/npm-update.md
index 72719670dd..f79752fae9 100644
--- a/deps/npm/doc/cli/npm-update.md
+++ b/deps/npm/doc/cli/npm-update.md
@@ -22,7 +22,7 @@ or local) will be updated.
 
 As of `npm@2.6.1`, the `npm update` will only inspect top-level packages.
 Prior versions of `npm` would also recursively inspect all dependencies.
-To get the old behavior, use `npm --depth 9999 update`, but be warned that
+To get the old behavior, use `npm --depth Infinity update`, but be warned that
 simultaneous asynchronous update of all packages, including `npm` itself
 and packages that `npm` depends on, often causes problems up to and including
 the uninstallation of `npm` itself.
diff --git a/deps/npm/doc/cli/npm-version.md b/deps/npm/doc/cli/npm-version.md
index 6bd550659d..2932516bb6 100644
--- a/deps/npm/doc/cli/npm-version.md
+++ b/deps/npm/doc/cli/npm-version.md
@@ -3,7 +3,7 @@ npm-version(1) -- Bump a package version
 
 ## SYNOPSIS
 
-    npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease]
+    npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]
 
     'npm [-v | --version]' to print npm version
     'npm view <pkg> version' to view a package's published version
@@ -14,10 +14,11 @@ npm-version(1) -- Bump a package version
 Run this in a package directory to bump the version and write the new
 data back to `package.json` and, if present, `npm-shrinkwrap.json`.
 
-The `newversion` argument should be a valid semver string, *or* a
-valid second argument to semver.inc (one of `patch`, `minor`, `major`,
-`prepatch`, `preminor`, `premajor`, `prerelease`). In the second case,
+The `newversion` argument should be a valid semver string, a
+valid second argument to [semver.inc](https://github.com/npm/node-semver#functions) (one of `patch`, `minor`, `major`,
+`prepatch`, `preminor`, `premajor`, `prerelease`), or `from-git`. In the second case,
 the existing version will be incremented by 1 in the specified field.
+`from-git` will try to read the latest git tag, and use that as the new npm version.
 
 If run in a git repo, it will also create a version commit and tag.
 This behavior is controlled by `git-tag-version` (see below), and can
diff --git a/deps/npm/doc/cli/npm.md b/deps/npm/doc/cli/npm.md
index 8a05d0605a..9746a15fc0 100644
--- a/deps/npm/doc/cli/npm.md
+++ b/deps/npm/doc/cli/npm.md
@@ -130,7 +130,7 @@ easily by doing `npm view npm contributors`.
 If you would like to contribute, but don't know what to work on, check
 the issues list or ask on the mailing list.
 
-* <http://github.com/npm/npm/issues>
+* <https://github.com/npm/npm/issues>
 * <npm-@googlegroups.com>
 
 ## BUGS
@@ -138,7 +138,7 @@ the issues list or ask on the mailing list.
 When you find issues, please report them:
 
 * web:
-  <http://github.com/npm/npm/issues>
+  <https://github.com/npm/npm/issues>
 * email:
   <npm-@googlegroups.com>
 
@@ -166,4 +166,3 @@ will no doubt tell you to put the output in a gist or email.
 * npm-config(7)
 * npmrc(5)
 * npm-index(7)
-* npm(3)