install: Only autoprune on install with lock file

3 files changed, 20 insertions, 3 deletions

diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md
index 0489ddf94..8bee6cf2d 100644
--- a/doc/cli/npm-install.md
+++ b/doc/cli/npm-install.md
@@ -347,7 +347,8 @@ The `--no-shrinkwrap` argument, which will ignore an available
 package lock or shrinkwrap file and use the package.json instead.
 
 The `--no-package-lock` argument will prevent npm from creating a
-`package-lock.json` file.
+`package-lock.json` file.  When running with package-lock's disabled npm
+will not automatically prune your node modules when installing.
 
 The `--nodedir=/path/to/node/source` argument will allow npm to find the
 node source code so that npm can compile native modules.
diff --git a/doc/cli/npm-prune.md b/doc/cli/npm-prune.md
index c7f340ca7..0dde24425 100644
--- a/doc/cli/npm-prune.md
+++ b/doc/cli/npm-prune.md
@@ -3,7 +3,7 @@ npm-prune(1) -- Remove extraneous packages
 
 ## SYNOPSIS
 
-    npm prune [[<@scope>/]<pkg>...] [--production]
+    npm prune [[<@scope>/]<pkg>...] [--production] [--dry-run] [--json]
 
 ## DESCRIPTION
 
@@ -16,9 +16,21 @@ package's dependencies list.
 
 If the `--production` flag is specified or the `NODE_ENV` environment
 variable is set to `production`, this command will remove the packages
-specified in your `devDependencies`. Setting `--production=false` will
+specified in your `devDependencies`. Setting `--no-production` will
 negate `NODE_ENV` being set to `production`.
 
+If the `--dry-run` flag is used then no changes will actually be made.
+
+If the `--json` flag is used then the changes `npm prune` made (or would
+have made with `--dry-run`) are printed as a JSON object.
+
+In normal operation with package-locks enabled, extraneous modules are
+pruned automatically when modules are installed and you'll only need
+this command with the `--production` flag.
+
+If you've disabled package-locks then extraneous modules will not be removed
+and it's up to you to run `npm prune` from time-to-time to remove them.
+
 ## SEE ALSO
 
 * npm-uninstall(1)
diff --git a/doc/misc/npm-config.md b/doc/misc/npm-config.md
index 0ab041891..70c2ec6e9 100644
--- a/doc/misc/npm-config.md
+++ b/doc/misc/npm-config.md
@@ -731,6 +731,10 @@ when publishing or changing package permissions with `npm access`.
 If set to false, then ignore `package-lock.json` files when installing. This
 will also prevent _writing_ `package-lock.json` if `save` is true.
 
+When package package-locks are disabled, automatic pruning of extraneous
+modules will also be disabled.  To remove extraneous modules with
+package-locks disabled use `npm prune`.
+
 This option is an alias for `--shrinkwrap`.
 
 ### package-lock-only