docs: explain through run-script

PR-URL: #2330
Credit: @isaacs
Close: #2330

docs/content/commands/npm-explain.md

@@ -8,6 +8,8 @@ description: Explain installed packages
 
 ```bash
 npm explain <folder | specifier>
+
+alias: why
 ```
 
 ### Description

docs/content/commands/npm-link.md

@@ -15,41 +15,44 @@ alias: npm ln
 
 ### Description
 
+This is handy for installing your own stuff, so that you can work on it and
+test iteratively without having to continually rebuild.
+
 Package linking is a two-step process.
 
-First, `npm link` in a package folder will create a symlink in the global folder
-`{prefix}/lib/node_modules/<package>` that links to the package where the `npm
-link` command was executed. It will also link any bins in the package to `{prefix}/bin/{name}`.
-Note that `npm link` uses the global prefix (see `npm prefix -g` for its value).
+First, `npm link` in a package folder will create a symlink in the global
+folder `{prefix}/lib/node_modules/<package>` that links to the package
+where the `npm link` command was executed. It will also link any bins in
+the package to `{prefix}/bin/{name}`.  Note that `npm link` uses the global
+prefix (see `npm prefix -g` for its value).
 
 Next, in some other location, `npm link package-name` will create a
-symbolic link from globally-installed `package-name` to `node_modules/`
-of the current folder.
+symbolic link from globally-installed `package-name` to `node_modules/` of
+the current folder.
 
-Note that `package-name` is taken from `package.json`,
-not from directory name.
+Note that `package-name` is taken from `package.json`, _not_ from the
+directory name.
 
-The package name can be optionally prefixed with a scope. See [`scope`](/using-npm/scope).
-The scope must be preceded by an @-symbol and followed by a slash.
+The package name can be optionally prefixed with a scope. See
+[`scope`](/using-npm/scope).  The scope must be preceded by an @-symbol and
+followed by a slash.
 
 When creating tarballs for `npm publish`, the linked packages are
-"snapshotted" to their current state by resolving the symbolic links.
-
-This is handy for installing your own stuff, so that you can work on it and
-test it iteratively without having to continually rebuild.
+"snapshotted" to their current state by resolving the symbolic links, if
+they are included in `bundleDependencies`.
 
 For example:
 
 ```bash
-    cd ~/projects/node-redis    # go into the package directory
-    npm link                    # creates global link
-    cd ~/projects/node-bloggy   # go into some other package directory.
-    npm link redis              # link-install the package
+cd ~/projects/node-redis    # go into the package directory
+npm link                    # creates global link
+cd ~/projects/node-bloggy   # go into some other package directory.
+npm link redis              # link-install the package
 ```
 
-Now, any changes to ~/projects/node-redis will be reflected in
-~/projects/node-bloggy/node_modules/node-redis/. Note that the link should
-be to the package name, not the directory name for that package.
+Now, any changes to `~/projects/node-redis` will be reflected in
+`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link
+should be to the package name, not the directory name for that package.
 
 You may also shortcut the two steps in one.  For example, to do the
 above use-case in a shorter way:
@@ -69,15 +72,33 @@ npm link redis
 That is, it first creates a global link, and then links the global
 installation target into your project's `node_modules` folder.
 
-Note that in this case, you are referring to the directory name, `node-redis`,
-rather than the package name `redis`.
+Note that in this case, you are referring to the directory name,
+`node-redis`, rather than the package name `redis`.
 
-If your linked package is scoped (see [`scope`](/using-npm/scope)) your link command must include that scope, e.g.
+If your linked package is scoped (see [`scope`](/using-npm/scope)) your
+link command must include that scope, e.g.
 
 ```bash
 npm link @myorg/privatepackage
 ```
 
+### Caveat
+
+Note that package dependencies linked in this way are _not_ saved to
+`package.json` by default, on the assumption that the intention is to have
+a link stand in for a regular non-link dependency.  Otherwise, for example,
+if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace
+the `^3.0.1` dependency with `file:../path/to/node-redis`, which you
+probably don't want!  Additionally, other users or developers on your
+project would run into issues if they do not have their folders set up
+exactly the same as yours.
+
+If you are adding a _new_ dependency as a link, you should add it to the
+relevant metadata by running `npm install <dep> --package-lock-only`.
+
+If you _want_ to save the `file:` reference in your `package.json` and
+`package-lock.json` files, you can use `npm link <dep> --save` to do so.
+
 ### See Also
 
 * [npm developers](/using-npm/developers)

docs/content/commands/npm-logout.md

@@ -12,13 +12,13 @@ npm logout [--registry=<url>] [--scope=<@scope>]
 
 ### Description
 
-When logged into a registry that supports token-based authentication, tell the
-server to end this token's session. This will invalidate the token everywhere
-you're using it, not just for the current environment.
+When logged into a registry that supports token-based authentication, tell
+the server to end this token's session. This will invalidate the token
+everywhere you're using it, not just for the current environment.
 
-When logged into a legacy registry that uses username and password authentication, this will
-clear the credentials in your user configuration. In this case, it will _only_ affect
-the current environment.
+When logged into a legacy registry that uses username and password
+authentication, this will clear the credentials in your user configuration.
+In this case, it will _only_ affect the current environment.
 
 If `--scope` is provided, this will find the credentials for the registry
 connected to that scope, if set.

docs/content/commands/npm-ls.md

@@ -15,17 +15,21 @@ aliases: list, la, ll
 ### Description
 
 This command will print to stdout all the versions of packages that are
-installed, as well as their dependencies, in a tree-structure.
+installed, as well as their dependencies when `--all` is specified, in a
+tree structure.
 
-Positional arguments are `name@version-range` identifiers, which will
-limit the results to only the paths to the packages named.  Note that
-nested packages will *also* show the paths to the specified packages.
-For example, running `npm ls promzard` in npm's source tree will show:
+Note: to get a "bottoms up" view of why a given package is included in the
+tree at all, use [`npm explain`](/commands/npm-explain).
+
+Positional arguments are `name@version-range` identifiers, which will limit
+the results to only the paths to the packages named.  Note that nested
+packages will *also* show the paths to the specified packages.  For
+example, running `npm ls promzard` in npm's source tree will show:
 
 ```bash
-    npm@@VERSION@ /path/to/npm
-    └─┬ [email protected]
-      └── [email protected]
+npm@@VERSION@ /path/to/npm
+└─┬ [email protected]
+  └── [email protected]
 ```
 
 It will print out extraneous, missing, and invalid packages.
@@ -35,12 +39,49 @@ 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.
+dependencies, not the physical layout of your `node_modules` folder.
 
 When run as `ll` or `la`, it shows extended information by default.
 
+### Note: Design Changes Pending
+
+The `npm ls` command's output and behavior made a _ton_ of sense when npm
+created a `node_modules` folder that naively nested every dependency.  In
+such a case, the logical dependency graph and physical tree of packages on
+disk would be roughly identical.
+
+With the advent of automatic install-time deduplication of dependencies in
+npm v3, the `ls` output was modified to display the logical dependency
+graph as a tree structure, since this was more useful to most users.
+However, without using `npm ls -l`, it became impossible show _where_ a
+package was actually installed much of the time!
+
+With the advent of automatic installation of `peerDependencies` in npm v7,
+this gets even more curious, as `peerDependencies` are logically
+"underneath" their dependents in the dependency graph, but are always
+physically at or above their location on disk.
+
+Also, in the years since npm got an `ls` command (in version 0.0.2!),
+dependency graphs have gotten much larger as a general rule.  Therefor, in
+order to avoid dumping an excessive amount of content to the terminal, `npm
+ls` now only shows the _top_ level dependencies, unless `--all` is
+provided.
+
+A thorough re-examination of the use cases, intention, behavior, and output
+of this command, is currently underway.  Expect significant changes to at
+least the default human-readable `npm ls` output in npm v8.
+
 ### Configuration
 
+#### all
+
+* Default: `false`
+* Type: Boolean
+
+When running `npm outdated` and `npm ls`, setting `--all` will show all
+outdated or installed packages, rather than only those directly depended
+upon by the current project.
+
 #### json
 
 * Default: false
@@ -115,6 +156,7 @@ Set it to false in order to use all-ansi output.
 
 ### See Also
 
+* [npm explain](/commands/npm-explain)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
 * [npm folders](/configuring-npm/folders)

docs/content/commands/npm-org.md

@@ -52,10 +52,11 @@ $ npm org ls my-org @mx-santos
 
 ### Description
 
-You can use the `npm org` commands to manage and view users of an organization.
-It supports adding and removing users, changing their roles, listing them, and
-finding specific ones and their roles.
+You can use the `npm org` commands to manage and view users of an
+organization.  It supports adding and removing users, changing their roles,
+listing them, and finding specific ones and their roles.
 
 ### See Also
 
+* [using orgs](/using-npm/orgs)
 * [Documentation on npm Orgs](https://docs.npmjs.com/orgs/)

docs/content/commands/npm-outdated.md

@@ -15,25 +15,34 @@ npm outdated [[<@scope>/]<pkg> ...]
 This command will check the registry to see if any (or, specific) installed
 packages are currently outdated.
 
+By default, only the direct dependencies of the root project are shown.
+Use `--all` to find all outdated meta-dependencies as well.
+
 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.
+  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](npm-dist-tag).
+  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](/commands/npm-dist-tag).
 * `location` is where in the physical tree the package is located.
 * `depended by` shows which package depends on the displayed dependency
-* `package type` (when using `--long` / `-l`) tells you whether this package is
-  a `dependency` or a dev/peer/optional dependency. Packages not included in `package.json`
-  are always marked `dependencies`.
-* `homepage` (when using `--long` / `-l`) is the `homepage` value contained in the package's packument
-* Red means there's a newer version matching your semver requirements, so you should update now.
-* Yellow indicates that there's a newer version above your semver requirements (usually new major, or new 0.x minor) so proceed with caution.
+* `package type` (when using `--long` / `-l`) tells you whether this
+  package is a `dependency` or a dev/peer/optional dependency. Packages not
+  included in `package.json` are always marked `dependencies`.
+* `homepage` (when using `--long` / `-l`) is the `homepage` value contained
+  in the package's packument
+* Red means there's a newer version matching your semver requirements, so
+  you should update now.
+* Yellow indicates that there's a newer version _above_ your semver
+  requirements (usually new major, or new 0.x minor) so proceed with
+  caution.
 
 ### An example
 
@@ -59,19 +68,20 @@ With these `dependencies`:
 
 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.
-* `[email protected]` is marked as "wanted", but "latest" is `[email protected]` 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.
+* `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.
+* `[email protected]` is marked as "wanted", but "latest" is `[email protected]` 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
 

docs/content/commands/npm-owner.md

@@ -18,26 +18,24 @@ aliases: author
 
 Manage ownership of published packages.
 
-* ls:
-  List all the users who have access to modify a package and push new versions.
-  Handy when you need to know who to bug for help.
-* add:
-  Add a new user as a maintainer of a package.  This user is enabled to modify
-  metadata, publish new versions, and add other owners.
-* rm:
-  Remove a user from the package owner list.  This immediately revokes their
-  privileges.
+* ls: List all the users who have access to modify a package and push new
+  versions.  Handy when you need to know who to bug for help.
+* add: Add a new user as a maintainer of a package.  This user is enabled
+  to modify metadata, publish new versions, and add other owners.
+* rm: Remove a user from the package owner list.  This immediately revokes
+  their privileges.
 
 Note that there is only one level of access.  Either you can modify a package,
 or you can't.  Future versions may contain more fine-grained access levels, but
 that is not implemented at this time.
 
-If you have two-factor authentication enabled with `auth-and-writes` then
-you'll need to include an otp on the command line when changing ownership
-with `--otp`.
+If you have two-factor authentication enabled with `auth-and-writes` (see
+[`npm-profile`](/commands/npm-profile)) then you'll need to include an otp
+on the command line when changing ownership with `--otp`.
 
 ### See Also
 
+* [npm profile](/commands/npm-profile)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)
 * [npm adduser](/commands/npm-adduser)

docs/content/commands/npm-pack.md

@@ -13,21 +13,23 @@ npm pack [[<@scope>/]<pkg>...] [--dry-run]
 ### Description
 
 For anything that's installable (that is, a package folder, tarball,
-tarball url, name@tag, name@version, name, or scoped name), this
-command will fetch it to the cache, and then copy the tarball to the
-current working directory as `<name>-<version>.tgz`, and then write
-the filenames out to stdout.
+tarball url, git url, name@tag, name@version, name, or scoped name), this
+command will fetch it to the cache, copy the tarball to the current working
+directory as `<name>-<version>.tgz`, and then write the filenames out to
+stdout.
 
 If the same package is specified multiple times, then the file will be
 overwritten the second time.
 
 If no arguments are supplied, then npm packs the current package folder.
 
 The `--dry-run` argument will do everything that pack usually does without
-actually packing anything. Reports on what would have gone into the tarball.
+actually packing anything.  That is, it reports on what would have gone
+into the tarball, but nothing else.
 
 ### See Also
 
+* [npm-packlist package](http://npm.im/npm-packlist)
 * [npm cache](/commands/npm-cache)
 * [npm publish](/commands/npm-publish)
 * [npm config](/commands/npm-config)

docs/content/commands/npm-ping.md

@@ -25,5 +25,6 @@ Ping error: {*Detail about error}
 
 ### See Also
 
+* [npm doctor](/commands/npm-doctor)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)