docs: npm-dedupe through npm-install

docs/content/cli-commands/npm-dedupe.md

@@ -1,5 +1,5 @@
 ---
-section: cli-commands 
+section: cli-commands
 title: npm-dedupe
 description: Reduce duplication
 ---
@@ -25,7 +25,7 @@ be more effectively shared by multiple dependent packages.
 
 For example, consider this dependency graph:
 
-```bash
+```
 a
 +-- b <-- depends on c@1.0.x
 |   `-- c@1.0.3
@@ -46,20 +46,35 @@ 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.
+In some cases, you may have a dependency graph like this:
+
+```
+a
++-- b <-- depends on c@1.0.x
++-- c@1.0.3
+`-- d <-- depends on c@1.x
+    `-- c@1.9.9
+```
+
+During the installation process, the `c@1.0.3` dependency for `b` was
+placed in the root of the tree.  Though `d`'s dependency on `c@1.x` could
+have been satisfied by `c@1.0.3`, the newer `c@1.9.0` dependency was used,
+because npm favors updates by default, even when doing so causes
+duplication.
+
+Running `npm dedupe` will cause npm to note the duplication and
+re-evaluate, deleting the nested `c` module, because the one in the root is
+sufficient.
 
-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.
+To prefer deduplication over novelty during the installation process, run
+`npm install --prefer-dedupe` or `npm config set prefer-dedupe true`.
 
 Arguments are ignored. Dedupe always acts on the entire tree.
 
 Note that this operation transforms the dependency tree, but will never
 result in new modules being installed.
 
-Using `npm find-dupes` will run the command in dryRun mode.
+Using `npm find-dupes` will run the command in `--dry-run` mode.
 
 ### See Also
 

docs/content/cli-commands/npm-deprecate.md

@@ -3,22 +3,25 @@ section: cli-commands
 title: npm-deprecate
 description: Deprecate a version of a package
 ---
+
 # npm-deprecate(1)
 
 ## Deprecate a version of a package
 
 ### Synopsis
+
 ```bash
 npm deprecate <pkg>[@<version>] <message>
 ```
 
 ### Description
 
-This command will update the npm registry entry for a package, providing
-a deprecation warning to all who attempt to install it.
+This command will update the npm registry entry for a package, providing a
+deprecation warning to all who attempt to install it.
 
-It works on [version ranges](https://semver.npmjs.com/) as well as specific 
+It works on [version ranges](https://semver.npmjs.com/) as well as specific
 versions, so you can do something like this:
+
 ```bash
 npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"
 ```
@@ -34,3 +37,5 @@ format an empty string.
 
 * [npm publish](/cli-commands/publish)
 * [npm registry](/using-npm/registry)
+* [npm owner](/cli-commands/owner)
+* [npm owner](/cli-commands/adduser)

docs/content/cli-commands/npm-dist-tag.md

@@ -1,5 +1,5 @@
- ---
-section: cli-commands 
+---
+section: cli-commands
 title: npm-dist-tag
 description: Modify package distribution tags
 ---
@@ -8,8 +8,8 @@ description: Modify package distribution tags
 
 ## Modify package distribution tags
 
-
 ### Synopsis
+
 ```bash
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
@@ -22,17 +22,18 @@ aliases: dist-tags
 
 Add, remove, and enumerate distribution tags on a package:
 
-* add:
-  Tags the specified version of the package with the specified tag, or the
-  `--tag` config if not specified. If you have two-factor authentication on
-  auth-and-writes then you’ll need to include a one-time password on the
-  command line with `--otp <one-time password>`.
+* add: Tags the specified version of the package with the specified tag, or
+  the `--tag` config if not specified. If you have two-factor
+  authentication on auth-and-writes then you’ll need to include a one-time
+  password on the command line with `--otp <one-time password>`, or at the
+  OTP prompt.
 
-* rm:
-  Clear a tag that is no longer in use from the package.
+* rm: Clear a tag that is no longer in use from the package. If you have
+  two-factor authentication on auth-and-writes then you’ll need to include
+  a one-time password on the command line with `--otp <one-time password>`,
+  or at the OTP prompt.
 
-* ls:
-  Show all of the dist-tags for a package, defaulting to the package in
+* ls: Show all of the dist-tags for a package, defaulting to the package in
   the current prefix. This is the default action if none is specified.
 
 A tag can be used when installing packages as a reference to a version instead
@@ -48,7 +49,8 @@ When installing dependencies, a preferred tagged version may be specified:
 npm install --tag <tag>
 ```
 
-This also applies to `npm dedupe`.
+(This also applies to any other commands that resolve and install
+dependencies, such as `npm dedupe`, `npm update`, and `npm audit fix`.)
 
 Publishing a package sets the `latest` tag to the published version unless the
 `--tag` option is used. For example, `npm publish --tag=beta`.
@@ -61,34 +63,34 @@ specifier) installs the `latest` tag.
 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`.
+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.
+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.
 
-By default, other than `latest`, no tag has any special significance to npm
-itself.
+Other than `latest`, no tag has any special significance to npm itself.
 
 ### Caveats
 
-This command used to be known as `npm tag`, which only created new tags, and so
-had a different syntax.
+This command used to be known as `npm tag`, which only created new tags,
+and so had a different syntax.
 
-Tags must share a namespace with version numbers, because they are specified in
-the same slot: `npm install <pkg>@<version>` vs `npm install <pkg>@<tag>`.
+Tags must share a namespace with version numbers, because they are
+specified in the same slot: `npm install <pkg>@<version>` vs `npm install
+<pkg>@<tag>`.
 
 Tags that can be interpreted as valid semver ranges will be rejected. For
-example, `v1.4` cannot be used as a tag, because it is interpreted by semver as
-`>=1.4.0 <1.5.0`.  See <https://github.com/npm/npm/issues/6082>.
+example, `v1.4` cannot be used as a tag, because it is interpreted by
+semver as `>=1.4.0 <1.5.0`.  See <https://github.com/npm/npm/issues/6082>.
 
-The simplest way to avoid semver problems with tags is to use tags that do not
-begin with a number or the letter `v`.
+The simplest way to avoid semver problems with tags is to use tags that do
+not begin with a number or the letter `v`.
 
 ### See Also
 

docs/content/cli-commands/npm-docs.md

@@ -1,12 +1,12 @@
 ---
-section: cli-commands 
+section: cli-commands
 title: npm-docs
 description: Docs for a package in a web browser maybe
 ---
 
-# npm-docs(1) 
+# npm-docs(1)
 
-## Docs for a package in a web browser maybe
+## Open documentation for a package in a web browser
 
 ### Synopsis
 
@@ -19,10 +19,10 @@ aliases: home
 ### Description
 
 This command tries to guess at the likely location of a package's
-documentation URL, and then tries to open it using the `--browser`
-config param. You can pass multiple package names at once. If no
-package name is provided, it will search for a `package.json` in
-the current folder and use the `name` property.
+documentation URL, and then tries to open it using the `--browser` config
+param. You can pass multiple package names at once. If no package name is
+provided, it will search for a `package.json` in the current folder and use
+the `name` property.
 
 ### Configuration
 
@@ -45,7 +45,6 @@ Set to `true` to use default system URL opener.
 
 The base URL of the npm package registry.
 
-
 ### See Also
 
 * [npm view](/cli-commands/view)

docs/content/cli-commands/npm-doctor.md

@@ -6,7 +6,7 @@ description: Check your environments
 
 # npm-doctor(1)
 
-## Check your environments
+## Check your npm environment
 
 ### Synopsis
 
@@ -17,92 +17,92 @@ npm doctor
 ### Description
 
 `npm doctor` runs a set of checks to ensure that your npm installation has
-what it needs to manage your JavaScript packages. npm is mostly a standalone tool, but it does
-have some basic requirements that must be met:
+what it needs to manage your JavaScript packages. npm is mostly a
+standalone tool, but it does have some basic requirements that must be met:
 
 + Node.js and git must be executable by npm.
-+ The primary npm registry, `registry.npmjs.com`, or another service that uses
-  the registry API, is available.
-+ The directories that npm uses, `node_modules` (both locally and globally),
-  exist and can be written by the current user.
++ The primary npm registry, `registry.npmjs.com`, or another service that
+  uses the registry API, is available.
++ The directories that npm uses, `node_modules` (both locally and
+  globally), exist and can be written by the current user.
 + The npm cache exists, and the package tarballs within it aren't corrupt.
 
-Without all of these working properly, npm may not work properly.  Many issues
-are often attributable to things that are outside npm's code base, so `npm
-doctor` confirms that the npm installation is in a good state.
+Without all of these working properly, npm may not work properly.  Many
+issues are often attributable to things that are outside npm's code base,
+so `npm doctor` confirms that the npm installation is in a good state.
 
-Also, in addition to this, there are also very many issue reports due to using
-old versions of npm. Since npm is constantly improving, running `npm@latest` is
-better than an old version.
+Also, in addition to this, there are also very many issue reports due to
+using old versions of npm. Since npm is constantly improving, running
+`npm@latest` is better than an old version.
 
-`npm doctor` verifies the following items in your environment, and if there are
-any recommended changes, it will display them.
+`npm doctor` verifies the following items in your environment, and if there
+are any recommended changes, it will display them.
 
 #### `npm ping`
 
-By default, npm installs from the primary npm registry, `registry.npmjs.org`.
-`npm doctor` hits a special ping endpoint within the registry. This can also be
-checked with `npm ping`. If this check fails, you may be using a proxy that
-needs to be configured, or may need to talk to your IT staff to get access over
-HTTPS to `registry.npmjs.org`.
+By default, npm installs from the primary npm registry,
+`registry.npmjs.org`.  `npm doctor` hits a special ping endpoint within the
+registry. This can also be checked with `npm ping`. If this check fails,
+you may be using a proxy that needs to be configured, or may need to talk
+to your IT staff to get access over HTTPS to `registry.npmjs.org`.
 
-This check is done against whichever registry you've configured (you can see
-what that is by running `npm config get registry`), and if you're using a
-private registry that doesn't support the `/whoami` endpoint supported by the
-primary registry, this check may fail.
+This check is done against whichever registry you've configured (you can
+see what that is by running `npm config get registry`), and if you're using
+a private registry that doesn't support the `/whoami` endpoint supported by
+the primary registry, this check may fail.
 
 #### `npm -v`
 
 While Node.js may come bundled with a particular version of npm, it's the
 policy of the CLI team that we recommend all users run `npm@latest` if they
-can. As the CLI is maintained by a small team of contributors, there are only
-resources for a single line of development, so npm's own long-term support
-releases typically only receive critical security and regression fixes. The
-team believes that the latest tested version of npm is almost always likely to
-be the most functional and defect-free version of npm.
+can. As the CLI is maintained by a small team of contributors, there are
+only resources for a single line of development, so npm's own long-term
+support releases typically only receive critical security and regression
+fixes. The team believes that the latest tested version of npm is almost
+always likely to be the most functional and defect-free version of npm.
 
 #### `node -v`
 
 For most users, in most circumstances, the best version of Node will be the
 latest long-term support (LTS) release. Those of you who want access to new
-ECMAscript features or bleeding-edge changes to Node's standard library may be
-running a newer version, and some of you may be required to run an older
-version of Node because of enterprise change control policies. That's OK! But
-in general, the npm team recommends that most users run Node.js LTS.
+ECMAscript features or bleeding-edge changes to Node's standard library may
+be running a newer version, and some may be required to run an older
+version of Node because of enterprise change control policies. That's OK!
+But in general, the npm team recommends that most users run Node.js LTS.
 
 #### `npm config get registry`
 
-Some of you may be installing from private package registries for your project
-or company. That's great! Others of you may be following tutorials or
-StackOverflow questions in an effort to troubleshoot problems you may be
-having. Sometimes, this may entail changing the registry you're pointing at.
-This part of `npm doctor` just lets you, and maybe whoever's helping you with
+You may be installing from private package registries for your project or
+company. That's great! Others may be following tutorials or StackOverflow
+questions in an effort to troubleshoot problems you may be having.
+Sometimes, this may entail changing the registry you're pointing at.  This
+part of `npm doctor` just lets you, and maybe whoever's helping you with
 support, know that you're not using the default registry.
 
 #### `which git`
 
-While it's documented in the README, it may not be obvious that npm needs Git
-installed to do many of the things that it does. Also, in some cases
-– especially on Windows – you may have Git set up in such a way that it's not
-accessible via your `PATH` so that npm can find it. This check ensures that Git
-is available.
+While it's documented in the README, it may not be obvious that npm needs
+Git installed to do many of the things that it does. Also, in some cases
+– especially on Windows – you may have Git set up in such a way that it's
+not accessible via your `PATH` so that npm can find it. This check ensures
+that Git is available.
 
 #### Permissions checks
 
 * Your cache must be readable and writable by the user running npm.
 * Global package binaries must be writable by the user running npm.
-* Your local `node_modules` path, if you're running `npm doctor` with a project
-  directory, must be readable and writable by the user running npm.
+* Your local `node_modules` path, if you're running `npm doctor` with a
+  project directory, must be readable and writable by the user running npm.
 
 #### Validate the checksums of cached packages
 
-When an npm package is published, the publishing process generates a checksum
-that npm uses at install time to verify that the package didn't get corrupted
-in transit. `npm doctor` uses these checksums to validate the package tarballs
-in your local cache (you can see where that cache is located with `npm config
-get cache`, and see what's in that cache with `npm cache ls` – probably more
-than you were expecting!). In the event that there are corrupt packages in your
-cache, you should probably run `npm cache clean` and reset the cache.
+When an npm package is published, the publishing process generates a
+checksum that npm uses at install time to verify that the package didn't
+get corrupted in transit. `npm doctor` uses these checksums to validate the
+package tarballs in your local cache (you can see where that cache is
+located with `npm config get cache`). In the event that there are corrupt
+packages in your cache, you should probably run `npm cache clean -f` and
+reset the cache.
 
 ### See Also