@cryptotaxi247 / documentation / commits / d8fae16

CLI documentation update from CI

npm CLI robot committed Jul 28, 2022 at 03:00 UTC d8fae16368ee6deee7d45e6e82a129c6e017a69c
6 files changed +500 -24
cli/v8
+1 -1
@@ -1 +1 @@
1 -Subproject commit f9abee79abe541226a249f50bdeec41317dd5712
1 +Subproject commit 58cc362ceec82ddeb16311d3fb574908294ac789
content/cli/v8/commands/npm-ci.md
+243 -10
@@ -94,15 +94,129 @@ cache:
94 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
95 <!-- automatically generated, do not edit manually -->
96 <!-- see lib/utils/config/definitions.js -->
97 -#### `audit`
97 +#### `save`
98 +
99 +* Default: `true` unless when using `npm update` where it defaults to `false`
100 +* Type: Boolean
101 +
102 +Save installed packages to a `package.json` file as dependencies.
103 +
104 +When used with the `npm rm` command, removes the dependency from
105 +`package.json`.
106 +
107 +Will also prevent writing to `package-lock.json` if set to `false`.
108 +
109 +<!-- automatically generated, do not edit manually -->
110 +<!-- see lib/utils/config/definitions.js -->
111 +
112 +#### `save-exact`
113 +
114 +* Default: false
115 +* Type: Boolean
116 +
117 +Dependencies saved to package.json will be configured with an exact version
118 +rather than using npm's default semver range operator.
119 +
120 +<!-- automatically generated, do not edit manually -->
121 +<!-- see lib/utils/config/definitions.js -->
122 +
123 +#### `global`
124 +
125 +* Default: false
126 +* Type: Boolean
127 +
128 +Operates in "global" mode, so that packages are installed into the `prefix`
129 +folder instead of the current working directory. See
130 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.
131 +
132 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead
133 + of the current working directory.
134 +* bin files are linked to `{prefix}/bin`
135 +* man pages are linked to `{prefix}/share/man`
136 +
137 +<!-- automatically generated, do not edit manually -->
138 +<!-- see lib/utils/config/definitions.js -->
139 +
140 +#### `global-style`
141 +
142 +* Default: false
143 +* Type: Boolean
144 +
145 +Causes npm to install the package into your local `node_modules` folder with
146 +the same layout it uses with the global `node_modules` folder. Only your
147 +direct dependencies will show in `node_modules` and everything they depend
148 +on will be flattened in their `node_modules` folders. This obviously will
149 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`
150 +will be preferred.
151 +
152 +<!-- automatically generated, do not edit manually -->
153 +<!-- see lib/utils/config/definitions.js -->
154 +
155 +#### `legacy-bundling`
156 +
157 +* Default: false
158 +* Type: Boolean
159 +
160 +Causes npm to install the package such that versions of npm prior to 1.4,
161 +such as the one included with node 0.8, can install the package. This
162 +eliminates all automatic deduping. If used with `global-style` this option
163 +will be preferred.
164 +
165 +<!-- automatically generated, do not edit manually -->
166 +<!-- see lib/utils/config/definitions.js -->
167 +
168 +#### `omit`
169 +
170 +* Default: 'dev' if the `NODE_ENV` environment variable is set to
171 + 'production', otherwise empty.
172 +* Type: "dev", "optional", or "peer" (can be set multiple times)
173 +
174 +Dependency types to omit from the installation tree on disk.
175 +
176 +Note that these dependencies _are_ still resolved and added to the
177 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
178 +physically installed on disk.
179 +
180 +If a package type appears in both the `--include` and `--omit` lists, then
181 +it will be included.
182 +
183 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
184 +variable will be set to `'production'` for all lifecycle scripts.
185 +
186 +<!-- automatically generated, do not edit manually -->
187 +<!-- see lib/utils/config/definitions.js -->
188 +
189 +#### `strict-peer-deps`
190 +
191 +* Default: false
192 +* Type: Boolean
193 +
194 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_
195 +conflicting `peerDependencies` will be treated as an install failure, even
196 +if npm could reasonably guess the appropriate resolution based on non-peer
197 +dependency relationships.
198 +
199 +By default, conflicting `peerDependencies` deep in the dependency graph will
200 +be resolved using the nearest non-peer dependency specification, even if
201 +doing so will result in some packages receiving a peer dependency outside
202 +the range set in their package's `peerDependencies` object.
203 +
204 +When such and override is performed, a warning is printed, explaining the
205 +conflict and the packages involved. If `--strict-peer-deps` is set, then
206 +this warning is treated as a failure.
207 +
208 +<!-- automatically generated, do not edit manually -->
209 +<!-- see lib/utils/config/definitions.js -->
210 +
211 +#### `package-lock`
212
213 * Default: true
214 * Type: Boolean
215
102 -When "true" submit audit reports alongside the current npm command to the
103 -default registry and all registries configured for scopes. See the
104 -documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is
105 -submitted.
216 +If set to false, then ignore `package-lock.json` files when installing. This
217 +will also prevent _writing_ `package-lock.json` if `save` is true.
218 +
219 +This configuration does not affect `npm ci`.
220
221 <!-- automatically generated, do not edit manually -->
222 <!-- see lib/utils/config/definitions.js -->
@@ -137,13 +251,132 @@ will *not* run any pre- or post-scripts.
251 <!-- automatically generated, do not edit manually -->
252 <!-- see lib/utils/config/definitions.js -->
253
140 -#### `script-shell`
254 +#### `audit`
255
142 -* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
143 -* Type: null or String
256 +* Default: true
257 +* Type: Boolean
258 +
259 +When "true" submit audit reports alongside the current npm command to the
260 +default registry and all registries configured for scopes. See the
261 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is
262 +submitted.
263 +
264 +<!-- automatically generated, do not edit manually -->
265 +<!-- see lib/utils/config/definitions.js -->
266 +
267 +#### `bin-links`
268 +
269 +* Default: true
270 +* Type: Boolean
271 +
272 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package
273 +executables.
274 +
275 +Set to false to have it not do this. This can be used to work around the
276 +fact that some file systems don't support symlinks, even on ostensibly Unix
277 +systems.
278 +
279 +<!-- automatically generated, do not edit manually -->
280 +<!-- see lib/utils/config/definitions.js -->
281 +
282 +#### `fund`
283 +
284 +* Default: true
285 +* Type: Boolean
286 +
287 +When "true" displays the message at the end of each `npm install`
288 +acknowledging the number of dependencies looking for funding. See [`npm
289 +fund`](/cli/v8/commands/npm-fund) for details.
290 +
291 +<!-- automatically generated, do not edit manually -->
292 +<!-- see lib/utils/config/definitions.js -->
293 +
294 +#### `dry-run`
295 +
296 +* Default: false
297 +* Type: Boolean
298 +
299 +Indicates that you don't want npm to make any changes and that it should
300 +only report what it would have done. This can be passed into any of the
301 +commands that modify your local installation, eg, `install`, `update`,
302 +`dedupe`, `uninstall`, as well as `pack` and `publish`.
303 +
304 +Note: This is NOT honored by other network related commands, eg `dist-tags`,
305 +`owner`, etc.
306 +
307 +<!-- automatically generated, do not edit manually -->
308 +<!-- see lib/utils/config/definitions.js -->
309 +
310 +#### `workspace`
311 +
312 +* Default:
313 +* Type: String (can be set multiple times)
314 +
315 +Enable running a command in the context of the configured workspaces of the
316 +current project while filtering by running only the workspaces defined by
317 +this configuration option.
318 +
319 +Valid values for the `workspace` config are either:
320 +
321 +* Workspace names
322 +* Path to a workspace directory
323 +* Path to a parent workspace directory (will result in selecting all
324 + workspaces within that folder)
325 +
326 +When set for the `npm init` command, this may be set to the folder of a
327 +workspace which does not yet exist, to create the folder and set it up as a
328 +brand new workspace within the project.
329 +
330 +This value is not exported to the environment for child processes.
331 +
332 +<!-- automatically generated, do not edit manually -->
333 +<!-- see lib/utils/config/definitions.js -->
334 +
335 +#### `workspaces`
336 +
337 +* Default: null
338 +* Type: null or Boolean
339 +
340 +Set to true to run the command in the context of **all** configured
341 +workspaces.
342 +
343 +Explicitly setting this to false will cause commands like `install` to
344 +ignore workspaces altogether. When not set explicitly:
345 +
346 +- Commands that operate on the `node_modules` tree (install, update, etc.)
347 +will link workspaces into the `node_modules` folder. - Commands that do
348 +other things (test, exec, publish, etc.) will operate on the root project,
349 +_unless_ one or more workspaces are specified in the `workspace` config.
350 +
351 +This value is not exported to the environment for child processes.
352 +
353 +<!-- automatically generated, do not edit manually -->
354 +<!-- see lib/utils/config/definitions.js -->
355 +
356 +#### `include-workspace-root`
357 +
358 +* Default: false
359 +* Type: Boolean
360 +
361 +Include the workspace root when workspaces are enabled for a command.
362 +
363 +When false, specifying individual workspaces via the `workspace` config, or
364 +all workspaces via the `workspaces` flag, will cause npm to operate only on
365 +the specified workspaces, and not on the root project.
366 +
367 +This value is not exported to the environment for child processes.
368 +
369 +<!-- automatically generated, do not edit manually -->
370 +<!-- see lib/utils/config/definitions.js -->
371 +
372 +#### `install-links`
373 +
374 +* Default: false
375 +* Type: Boolean
376
145 -The shell to use for scripts run with the `npm exec`, `npm run` and `npm
146 -init <package-spec>` commands.
377 +When set file: protocol dependencies that exist outside of the project root
378 +will be packed and installed as regular dependencies instead of creating a
379 +symlink. This option has no effect on workspaces.
380
381 <!-- automatically generated, do not edit manually -->
382 <!-- see lib/utils/config/definitions.js -->
content/cli/v8/commands/npm-init.md
+2
@@ -48,6 +48,8 @@ follows:
48 * `npm init foo` -> `npm exec create-foo`
49 * `npm init @usr/foo` -> `npm exec @usr/create-foo`
50 * `npm init @usr` -> `npm exec @usr/create`
51 +* `npm init @usr@2.0.0` -> `npm exec @usr/create@2.0.0`
52 +* `npm init @usr/foo@2.0.0` -> `npm exec @usr/create-foo@2.0.0`
53
54 If the initializer is omitted (by just calling `npm init`), init will fall
55 back to legacy init behavior. It will ask you a bunch of questions, and
content/cli/v8/commands/npm-install-ci-test.md
+243 -10
@@ -40,15 +40,129 @@ This command runs `npm ci` followed immediately by `npm test`.
40 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
41 <!-- automatically generated, do not edit manually -->
42 <!-- see lib/utils/config/definitions.js -->
43 -#### `audit`
43 +#### `save`
44 +
45 +* Default: `true` unless when using `npm update` where it defaults to `false`
46 +* Type: Boolean
47 +
48 +Save installed packages to a `package.json` file as dependencies.
49 +
50 +When used with the `npm rm` command, removes the dependency from
51 +`package.json`.
52 +
53 +Will also prevent writing to `package-lock.json` if set to `false`.
54 +
55 +<!-- automatically generated, do not edit manually -->
56 +<!-- see lib/utils/config/definitions.js -->
57 +
58 +#### `save-exact`
59 +
60 +* Default: false
61 +* Type: Boolean
62 +
63 +Dependencies saved to package.json will be configured with an exact version
64 +rather than using npm's default semver range operator.
65 +
66 +<!-- automatically generated, do not edit manually -->
67 +<!-- see lib/utils/config/definitions.js -->
68 +
69 +#### `global`
70 +
71 +* Default: false
72 +* Type: Boolean
73 +
74 +Operates in "global" mode, so that packages are installed into the `prefix`
75 +folder instead of the current working directory. See
76 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.
77 +
78 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead
79 + of the current working directory.
80 +* bin files are linked to `{prefix}/bin`
81 +* man pages are linked to `{prefix}/share/man`
82 +
83 +<!-- automatically generated, do not edit manually -->
84 +<!-- see lib/utils/config/definitions.js -->
85 +
86 +#### `global-style`
87 +
88 +* Default: false
89 +* Type: Boolean
90 +
91 +Causes npm to install the package into your local `node_modules` folder with
92 +the same layout it uses with the global `node_modules` folder. Only your
93 +direct dependencies will show in `node_modules` and everything they depend
94 +on will be flattened in their `node_modules` folders. This obviously will
95 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`
96 +will be preferred.
97 +
98 +<!-- automatically generated, do not edit manually -->
99 +<!-- see lib/utils/config/definitions.js -->
100 +
101 +#### `legacy-bundling`
102 +
103 +* Default: false
104 +* Type: Boolean
105 +
106 +Causes npm to install the package such that versions of npm prior to 1.4,
107 +such as the one included with node 0.8, can install the package. This
108 +eliminates all automatic deduping. If used with `global-style` this option
109 +will be preferred.
110 +
111 +<!-- automatically generated, do not edit manually -->
112 +<!-- see lib/utils/config/definitions.js -->
113 +
114 +#### `omit`
115 +
116 +* Default: 'dev' if the `NODE_ENV` environment variable is set to
117 + 'production', otherwise empty.
118 +* Type: "dev", "optional", or "peer" (can be set multiple times)
119 +
120 +Dependency types to omit from the installation tree on disk.
121 +
122 +Note that these dependencies _are_ still resolved and added to the
123 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
124 +physically installed on disk.
125 +
126 +If a package type appears in both the `--include` and `--omit` lists, then
127 +it will be included.
128 +
129 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
130 +variable will be set to `'production'` for all lifecycle scripts.
131 +
132 +<!-- automatically generated, do not edit manually -->
133 +<!-- see lib/utils/config/definitions.js -->
134 +
135 +#### `strict-peer-deps`
136 +
137 +* Default: false
138 +* Type: Boolean
139 +
140 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_
141 +conflicting `peerDependencies` will be treated as an install failure, even
142 +if npm could reasonably guess the appropriate resolution based on non-peer
143 +dependency relationships.
144 +
145 +By default, conflicting `peerDependencies` deep in the dependency graph will
146 +be resolved using the nearest non-peer dependency specification, even if
147 +doing so will result in some packages receiving a peer dependency outside
148 +the range set in their package's `peerDependencies` object.
149 +
150 +When such and override is performed, a warning is printed, explaining the
151 +conflict and the packages involved. If `--strict-peer-deps` is set, then
152 +this warning is treated as a failure.
153 +
154 +<!-- automatically generated, do not edit manually -->
155 +<!-- see lib/utils/config/definitions.js -->
156 +
157 +#### `package-lock`
158
159 * Default: true
160 * Type: Boolean
161
48 -When "true" submit audit reports alongside the current npm command to the
49 -default registry and all registries configured for scopes. See the
50 -documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is
51 -submitted.
162 +If set to false, then ignore `package-lock.json` files when installing. This
163 +will also prevent _writing_ `package-lock.json` if `save` is true.
164 +
165 +This configuration does not affect `npm ci`.
166
167 <!-- automatically generated, do not edit manually -->
168 <!-- see lib/utils/config/definitions.js -->
@@ -83,13 +197,132 @@ will *not* run any pre- or post-scripts.
197 <!-- automatically generated, do not edit manually -->
198 <!-- see lib/utils/config/definitions.js -->
199
86 -#### `script-shell`
200 +#### `audit`
201
88 -* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
89 -* Type: null or String
202 +* Default: true
203 +* Type: Boolean
204 +
205 +When "true" submit audit reports alongside the current npm command to the
206 +default registry and all registries configured for scopes. See the
207 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is
208 +submitted.
209 +
210 +<!-- automatically generated, do not edit manually -->
211 +<!-- see lib/utils/config/definitions.js -->
212 +
213 +#### `bin-links`
214 +
215 +* Default: true
216 +* Type: Boolean
217 +
218 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package
219 +executables.
220 +
221 +Set to false to have it not do this. This can be used to work around the
222 +fact that some file systems don't support symlinks, even on ostensibly Unix
223 +systems.
224 +
225 +<!-- automatically generated, do not edit manually -->
226 +<!-- see lib/utils/config/definitions.js -->
227 +
228 +#### `fund`
229 +
230 +* Default: true
231 +* Type: Boolean
232 +
233 +When "true" displays the message at the end of each `npm install`
234 +acknowledging the number of dependencies looking for funding. See [`npm
235 +fund`](/cli/v8/commands/npm-fund) for details.
236 +
237 +<!-- automatically generated, do not edit manually -->
238 +<!-- see lib/utils/config/definitions.js -->
239 +
240 +#### `dry-run`
241 +
242 +* Default: false
243 +* Type: Boolean
244 +
245 +Indicates that you don't want npm to make any changes and that it should
246 +only report what it would have done. This can be passed into any of the
247 +commands that modify your local installation, eg, `install`, `update`,
248 +`dedupe`, `uninstall`, as well as `pack` and `publish`.
249 +
250 +Note: This is NOT honored by other network related commands, eg `dist-tags`,
251 +`owner`, etc.
252 +
253 +<!-- automatically generated, do not edit manually -->
254 +<!-- see lib/utils/config/definitions.js -->
255 +
256 +#### `workspace`
257 +
258 +* Default:
259 +* Type: String (can be set multiple times)
260 +
261 +Enable running a command in the context of the configured workspaces of the
262 +current project while filtering by running only the workspaces defined by
263 +this configuration option.
264 +
265 +Valid values for the `workspace` config are either:
266 +
267 +* Workspace names
268 +* Path to a workspace directory
269 +* Path to a parent workspace directory (will result in selecting all
270 + workspaces within that folder)
271 +
272 +When set for the `npm init` command, this may be set to the folder of a
273 +workspace which does not yet exist, to create the folder and set it up as a
274 +brand new workspace within the project.
275 +
276 +This value is not exported to the environment for child processes.
277 +
278 +<!-- automatically generated, do not edit manually -->
279 +<!-- see lib/utils/config/definitions.js -->
280 +
281 +#### `workspaces`
282 +
283 +* Default: null
284 +* Type: null or Boolean
285 +
286 +Set to true to run the command in the context of **all** configured
287 +workspaces.
288 +
289 +Explicitly setting this to false will cause commands like `install` to
290 +ignore workspaces altogether. When not set explicitly:
291 +
292 +- Commands that operate on the `node_modules` tree (install, update, etc.)
293 +will link workspaces into the `node_modules` folder. - Commands that do
294 +other things (test, exec, publish, etc.) will operate on the root project,
295 +_unless_ one or more workspaces are specified in the `workspace` config.
296 +
297 +This value is not exported to the environment for child processes.
298 +
299 +<!-- automatically generated, do not edit manually -->
300 +<!-- see lib/utils/config/definitions.js -->
301 +
302 +#### `include-workspace-root`
303 +
304 +* Default: false
305 +* Type: Boolean
306 +
307 +Include the workspace root when workspaces are enabled for a command.
308 +
309 +When false, specifying individual workspaces via the `workspace` config, or
310 +all workspaces via the `workspaces` flag, will cause npm to operate only on
311 +the specified workspaces, and not on the root project.
312 +
313 +This value is not exported to the environment for child processes.
314 +
315 +<!-- automatically generated, do not edit manually -->
316 +<!-- see lib/utils/config/definitions.js -->
317 +
318 +#### `install-links`
319 +
320 +* Default: false
321 +* Type: Boolean
322
91 -The shell to use for scripts run with the `npm exec`, `npm run` and `npm
92 -init <package-spec>` commands.
323 +When set file: protocol dependencies that exist outside of the project root
324 +will be packed and installed as regular dependencies instead of creating a
325 +symlink. This option has no effect on workspaces.
326
327 <!-- automatically generated, do not edit manually -->
328 <!-- see lib/utils/config/definitions.js -->
content/cli/v8/commands/npm-ls.md
+2 -2
@@ -54,7 +54,7 @@ npm@8.0.0 /path/to/npm
54 It will print out extraneous, missing, and invalid packages.
55
56 If a project specifies git urls for dependencies these are shown
57 -in parentheses after the name@version to make it easier for users to
57 +in parentheses after the `name@version` to make it easier for users to
58 recognize potential forks of a project.
59
60 The tree shown is the logical dependency tree, based on package
@@ -72,7 +72,7 @@ disk would be roughly identical.
72 With the advent of automatic install-time deduplication of dependencies in
73 npm v3, the `ls` output was modified to display the logical dependency
74 graph as a tree structure, since this was more useful to most users.
75 -However, without using `npm ls -l`, it became impossible show _where_ a
75 +However, without using `npm ls -l`, it became impossible to show _where_ a
76 package was actually installed much of the time!
77
78 With the advent of automatic installation of `peerDependencies` in npm v7,
content/cli/v8/using-npm/workspaces.md
+9 -1
@@ -145,6 +145,8 @@ nested workspaces to be consumed elsewhere.
145
146 You can use the `workspace` configuration option to run commands in the context
147 of a configured workspace.
148 +Additionally, if your current directory is in a workspace, the `workspace`
149 +configuration is implicitly set, and `prefix` is set to the root workspace.
150
151 Following is a quick example on how to use the `npm run` command in the context
152 of nested workspaces. For a project containing multiple workspaces, e.g:
@@ -166,7 +168,13 @@ given command in the context of that specific workspace. e.g:
168 npm run test --workspace=a
169 ```
170
169 -This will run the `test` script defined within the
171 +You could also run the command within the workspace.
172 +
173 +```
174 +cd packages/a && npm run test
175 +```
176 +
177 +Either will run the `test` script defined within the
178 `./packages/a/package.json` file.
179
180 Please note that you can also specify this argument multiple times in the