feat: add ls workspaces

- Add listing workspaces deps by default in `npm ls`
- Add ability to filter the result tree by workspace using the -w config
- Added tests and docs

Fixes: https://github.com/npm/statusboard/issues/302

PR-URL: https://github.com/npm/cli/pull/3250
Credit: @ruyadorno
Close: #3250
Reviewed-by: @isaacs

1 files changed, 32 insertions, 0 deletions

diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md
index 505dfd9c4..3c6621763 100644
--- a/docs/content/commands/npm-ls.md
+++ b/docs/content/commands/npm-ls.md
@@ -177,6 +177,38 @@ When used with `npm ls`, only show packages that are linked.
 When set to true, npm uses unicode characters in the tree output. When
 false, it uses ascii characters instead of unicode glyphs.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also