Update documentation

8 files changed, 70 insertions, 81 deletions

diff --git a/doc/cli/npm-dedupe.md b/doc/cli/npm-dedupe.md
index d3be01050..c963dfa8e 100644
--- a/doc/cli/npm-dedupe.md
+++ b/doc/cli/npm-dedupe.md
@@ -31,25 +31,20 @@ Because of the hierarchical nature of node's module lookup, b and d
 will both get their dependency met by the single c package at the root
 level of the tree.
 
+The deduplication algorithm walks the tree, moving each dependency as far
+up in the tree as possible, even if duplicates are not found. This will
+result in both a flat and deduplicated tree.
+
 If a suitable version exists at the target location in the tree
 already, then it will be left untouched, but the other duplicates will
 be deleted.
 
-If no suitable version can be found, then a warning is printed, and
-nothing is done.
-
-If any arguments are supplied, then they are filters, and only the
-named packages will be touched.
-
-Note that this operation transforms the dependency tree, and may
-result in packages getting updated versions, perhaps from the npm
-registry.
+Arguments are ignored. Dedupe always acts on the entire tree.
 
-This feature is experimental, and may change in future versions.
+Modules
 
-The `--tag` argument will apply to all of the affected dependencies. If a
-tag with the given name exists, the tagged version is preferred over newer
-versions.
+Note that this operation transforms the dependency tree, but will never
+result in new modules being installed.
 
 ## SEE ALSO
 
diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md
index be32f7b29..2ccde25e0 100644
--- a/doc/cli/npm-install.md
+++ b/doc/cli/npm-install.md
@@ -27,7 +27,7 @@ A `package` is:
 * d) a `<name>@<version>` that is published on the registry (see `npm-registry(7)`) with (c)
 * e) a `<name>@<tag>` that points to (d)
 * f) a `<name>` that has a "latest" tag satisfying (e)
-* g) a `<git remote url>` that resolves to (b)
+* 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
@@ -99,6 +99,9 @@ after packing it up into a tarball (b).
       exact version rather than using npm's default semver range
       operator.
 
+    Further, if you have an `npm-shrinkwrap.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)`.
@@ -157,10 +160,10 @@ after packing it up into a tarball (b).
 
 * `npm install <git remote url>`:
 
-    Install a package by cloning a git remote url.  The format of the git
-    url is:
+    Installs the package from the hosted git provider, cloning it with
+    `git`. First it tries via the https (git with github) and if that fails, via ssh.
 
-          <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit-ish>]
+          <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish>]
 
     `<protocol>` is one of `git`, `git+ssh`, `git+http`, or
     `git+https`.  If no `<commit-ish>` is specified, then `master` is
@@ -271,26 +274,39 @@ effect on installation, since that's most of what npm does.
 
 To install a package, npm uses the following algorithm:
 
-    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)
+    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
+    +-- 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.
+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 leve, C now has to install D@2
+privately for itself.
 
 See npm-folders(5) for a more detailed description of the specific
 folder structures that npm creates.
diff --git a/doc/cli/npm-ls.md b/doc/cli/npm-ls.md
index 318cdd8fd..fa93e836e 100644
--- a/doc/cli/npm-ls.md
+++ b/doc/cli/npm-ls.md
@@ -28,6 +28,9 @@ If a project specifies git urls for dependencies these are shown
 in parentheses after the name@version to make it easier for users to
 recognize potential forks of a project.
 
+The tree shown is the logical dependency tree, based on package
+dependencies, not the physical layout of your node_modules folder.
+
 When run as `ll` or `la`, it shows extended information by default.
 
 ## CONFIGURATION
diff --git a/doc/cli/npm-rm.md b/doc/cli/npm-rm.md
deleted file mode 100644
index 6691265ff..000000000
--- a/doc/cli/npm-rm.md
+++ /dev/null
@@ -1,23 +0,0 @@
-npm-rm(1) -- Remove a package
-=============================
-
-## SYNOPSIS
-
-    npm rm <name>
-    npm r <name>
-    npm uninstall <name>
-    npm un <name>
-
-## DESCRIPTION
-
-This uninstalls a package, completely removing everything npm installed
-on its behalf.
-
-## SEE ALSO
-
-* npm-prune(1)
-* npm-install(1)
-* npm-folders(5)
-* npm-config(1)
-* npm-config(7)
-* npmrc(5)
diff --git a/doc/cli/npm-shrinkwrap.md b/doc/cli/npm-shrinkwrap.md
index ca9cb257b..b4548ca7c 100644
--- a/doc/cli/npm-shrinkwrap.md
+++ b/doc/cli/npm-shrinkwrap.md
@@ -82,29 +82,32 @@ This generates `npm-shrinkwrap.json`, which will look something like this:
 
     {
       "name": "A",
-      "version": "0.1.0",
+      "version": "1.1.0",
       "dependencies": {
         "B": {
-          "version": "0.0.1",
+          "version": "1.0.1",
+          "from": "B@^1.0.0",
+          "resolved": "https://registry.npmjs.org/B/-/B-1.0.1.tgz",
           "dependencies": {
             "C": {
-              "version": "0.0.1"
+              "version": "1.0.1",
+              "from": "org/C#v1.0.1",
+              "resolved": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
             }
           }
         }
       }
     }
 
-The shrinkwrap command has locked down the dependencies based on
-what's currently installed in node_modules.  When `npm install`
-installs a package with an `npm-shrinkwrap.json` in the package
-root, the shrinkwrap file (rather than `package.json` files) completely
-drives the installation of that package and all of its dependencies
-(recursively).  So now the author publishes A@0.1.0, and subsequent
-installs of this package will use B@0.0.1 and C@0.0.1, regardless the
-dependencies and versions listed in A's, B's, and C's `package.json`
-files.
+The shrinkwrap command has locked down the dependencies based on what's
+currently installed in `node_modules`.  The installation behavior is changed to:
+
+1. The module tree described by the shrinkwrap is reproduced. This means
+reproducing the structure described in the file, using the specific files
+referenced in "resolved" if available, falling back to normal package
+resolution using "version" if one isn't.
 
+2. The tree is walked and any missing dependencies are installed in the usual fasion.
 
 ### Using shrinkwrapped packages
 
@@ -126,15 +129,14 @@ To add or update a dependency in a shrinkwrapped package:
 
 1. Run `npm install` in the package root to install the current
    versions of all dependencies.
-2. Add or update dependencies. `npm install` each new or updated
-   package individually and then update `package.json`.  Note that they
-   must be explicitly named in order to be installed: running `npm
-   install` with no arguments will merely reproduce the existing
+2. Add or update dependencies. `npm install --save` each new or updated
+   package individually to update the `package.json` and the shrinkwrap.
+   Note that they must be explicitly named in order to be installed: running
+   `npm install` with no arguments will merely reproduce the existing
    shrinkwrap.
 3. Validate that the package works as expected with the new
    dependencies.
-4. Run `npm shrinkwrap`, commit the new `npm-shrinkwrap.json`, and
-   publish your package.
+4. Commit the new `npm-shrinkwrap.json`, and publish your package.
 
 You can use npm-outdated(1) to view dependencies with newer versions
 available.
diff --git a/doc/cli/npm-uninstall.md b/doc/cli/npm-uninstall.md
index bfa667c3e..72e3b7d45 100644
--- a/doc/cli/npm-uninstall.md
+++ b/doc/cli/npm-uninstall.md
@@ -27,6 +27,9 @@ the package version in your main package.json:
 
 * `--save-optional`: Package will be removed from your `optionalDependencies`.
 
+Further, if you have an `npm-shrinkwrap.json` then it will be updated as
+well.
+
 Scope is optional and follows the usual rules for `npm-scope(7)`.
 
 Examples:
diff --git a/doc/files/package.json.md b/doc/files/package.json.md
index f402e2ebc..b8f543c5f 100644
--- a/doc/files/package.json.md
+++ b/doc/files/package.json.md
@@ -603,17 +603,10 @@ field is advisory only.
 
 ## engineStrict
 
-**NOTE: This feature is deprecated and will be removed in npm 3.0.0.**
+**This feature was deprecated with npm 3.0.0**
 
-If you are sure that your module will *definitely not* run properly on
-versions of Node/npm other than those specified in the `engines` object,
-then you can set `"engineStrict": true` in your package.json file.
-This will override the user's `engine-strict` config setting.
-
-Please do not do this unless you are really very very sure.  If your
-engines object is something overly restrictive, you can quite easily and
-inadvertently lock yourself into obscurity and prevent your users from
-updating to new versions of Node.  Consider this choice carefully.
+Prior to npm 3.0.0, this feature was used to treat this package as if the
+user had set `engine-strict`.
 
 ## os
 
diff --git a/doc/misc/npm-config.md b/doc/misc/npm-config.md
index c5cfbe943..454130d43 100644
--- a/doc/misc/npm-config.md
+++ b/doc/misc/npm-config.md
@@ -816,7 +816,7 @@ on success, but left behind on failure for forensic purposes.
 
 ### unicode
 
-* Default: true
+* Default: true on windows and mac/unix systems with a unicode locale
 * Type: Boolean
 
 When set to true, npm uses unicode characters in the tree output.  When