CLI documentation update from CI

CI User · CI User · commit 9e13d063da19 · 2022-03-25T02:38:17.000Z
diff --git a/cli/v8 b/cli/v8
@@ -1 +1 @@
-Subproject commit 362831c4eba2554b44feec60fdff197d92eac0c1
+Subproject commit 716a07fde7905bb69e4c6f1991bb7289589a6669
diff --git a/content/cli/v8/commands/npm-version.md b/content/cli/v8/commands/npm-version.md
@@ -154,6 +154,17 @@ This value is not exported to the environment for child processes.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### `workspaces-update`
+
+* Default: true
+* Type: Boolean
+
+If set to true, the npm cli will run an update after operations that may
+possibly change the workspaces installed to the `node_modules` folder.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### `include-workspace-root`
 
 * Default: false
diff --git a/content/cli/v8/using-npm/config.md b/content/cli/v8/using-npm/config.md
@@ -1035,13 +1035,26 @@ See also the `foreground-scripts` config.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### `logs-dir`
+
+* Default: A directory named `_logs` inside the cache
+* Type: null or Path
+
+The location of npm's log directory. See [`npm logging`](/cli/v8/using-npm/logging)
+for more information.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### `logs-max`
 
 * Default: 10
 * Type: Number
 
 The maximum number of log files to store.
 
+If set to 0, no log files will be written for the current run.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
@@ -1636,9 +1649,9 @@ particular, use care when overriding this setting for public packages.
 * Default: false
 * Type: Boolean
 
-If true, writes an `npm-debug` log to `_logs` and timing information to
-`_timing.json`, both in your cache, even if the command completes
-successfully. `_timing.json` is a newline delimited list of JSON objects.
+If true, writes a debug log to `logs-dir` and timing information to
+`_timing.json` in the cache, even if the command completes successfully.
+`_timing.json` is a newline delimited list of JSON objects.
 
 You can quickly view it with this [json](https://npm.im/json) command line:
 `npm exec -- json -g < ~/.npm/_timing.json`.
@@ -1831,6 +1844,17 @@ This value is not exported to the environment for child processes.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### `workspaces-update`
+
+* Default: true
+* Type: Boolean
+
+If set to true, the npm cli will run an update after operations that may
+possibly change the workspaces installed to the `node_modules` folder.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### `yes`
 
 * Default: null
diff --git a/content/cli/v8/using-npm/logging.md b/content/cli/v8/using-npm/logging.md
@@ -1,7 +1,7 @@
 ---
 title: Logging
 section: 7
-description: Why, What & How we Log
+description: Why, What & How We Log
 redirect_from:
   - /using-npm/logging
   - /using-npm/logging.html
@@ -16,6 +16,17 @@ github_path: docs/content/using-npm/logging.md
 
 The `npm` CLI has various mechanisms for showing different levels of information back to end-users for certain commands, configurations & environments.
 
+### Setting Log File Location
+
+All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
+
+The default location of the logs directory is a directory named `_logs` inside the npm cache. This can be changed
+with the `logs-dir` config option.
+
+Log files will be removed from the `logs-dir` when the number of log files exceeds `logs-max`, with the oldest logs being deleted first.
+
+To turn off logs completely set `--logs-max=0`.
+
 ### Setting Log Levels
 
 #### `loglevel`
@@ -36,8 +47,6 @@ The default value of `loglevel` is `"notice"` but there are several levels/types
 
 All logs pertaining to a level proceeding the current setting will be shown.
 
-All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
-
 ##### Aliases
 
 The log levels listed above have various corresponding aliases, including:
@@ -55,6 +64,15 @@ The log levels listed above have various corresponding aliases, including:
 
 The `npm` CLI began hiding the output of lifecycle scripts for `npm install` as of `v7`. Notably, this means you will not see logs/output from packages that may be using "install scripts" to display information back to you or from your own project's scripts defined in `package.json`. If you'd like to change this behavior & log this output you can set `foreground-scripts` to `true`.
 
+### Timing Information
+
+The `--timing` config can be set which does two things:
+
+1. Always shows the full path to the debug log regardless of command exit status
+1. Write timing information to a timing file in the cache or `logs-dir`
+
+This file is a newline delimited list of JSON  objects that can be inspected to see timing data for each task in a `npm` CLI run.
+
 ### Registry Response Headers
 
 #### `npm-notice`
@@ -63,6 +81,15 @@ The `npm` CLI reads from & logs any `npm-notice` headers that are returned from
 
 This header is not cached, and will not be logged if the request is served from the cache.
 
+### Logs and Sensitive Information
+
+The `npm` CLI makes a best effort to redact the following from terminal output and log files:
+
+- Passwords inside basic auth URLs
+- npm tokens
+
+However, this behavior should not be relied on to keep all possible sensitive information redacted. If you are concerned about secrets in your log file or terminal output, you can use `--loglevel=silent` and `--logs-max=0` to ensure no logs are written to your terminal or filesystem.
+
 ### See also
 
 * [config](/cli/v8/using-npm/config)
