From de40c31d1fe7521ffbc4e22fd233b18eca149afe Mon Sep 17 00:00:00 2001 From: Gar Date: Wed, 27 Jul 2022 14:05:34 -0700 Subject: [PATCH] docs: sync ci params with install (#5207) --- docs/content/commands/npm-ci.md | 253 +++++++++++++++++- docs/content/commands/npm-install-ci-test.md | 253 +++++++++++++++++- lib/commands/ci.js | 9 +- .../tap-snapshots/test/index.js.test.cjs | 9 +- .../test/lib/load-all-commands.js.test.cjs | 18 +- tap-snapshots/test/lib/npm.js.test.cjs | 18 +- 6 files changed, 524 insertions(+), 36 deletions(-) diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md index 9b8238d05a3b9..30a03365ade81 100644 --- a/docs/content/commands/npm-ci.md +++ b/docs/content/commands/npm-ci.md @@ -84,15 +84,129 @@ cache: -#### `audit` +#### `save` + +* Default: `true` unless when using `npm update` where it defaults to `false` +* Type: Boolean + +Save installed packages to a `package.json` file as dependencies. + +When used with the `npm rm` command, removes the dependency from +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. + + + + +#### `save-exact` + +* Default: false +* Type: Boolean + +Dependencies saved to package.json will be configured with an exact version +rather than using npm's default semver range operator. + + + + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + + + + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + + + + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + + + + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + + + + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + + + + +#### `package-lock` * Default: true * Type: Boolean -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +This configuration does not affect `npm ci`. @@ -127,13 +241,132 @@ will *not* run any pre- or post-scripts. -#### `script-shell` +#### `audit` -* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows -* Type: null or String +* Default: true +* Type: Boolean + +When "true" submit audit reports alongside the current npm command to the +default registry and all registries configured for scopes. See the +documentation for [`npm audit`](/commands/npm-audit) for details on what is +submitted. + + + + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + + + + +#### `fund` + +* Default: true +* Type: Boolean + +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. + + + + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + + + + +#### `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 in selecting all + workspaces within that folder) + +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: null +* Type: null or Boolean + +Set to true to run the command in the context of **all** configured +workspaces. + +Explicitly setting this to false will cause commands like `install` to +ignore workspaces altogether. When not set explicitly: + +- Commands that operate on the `node_modules` tree (install, update, etc.) +will link workspaces into the `node_modules` folder. - Commands that do +other things (test, exec, publish, etc.) will operate on the root project, +_unless_ one or more workspaces are specified in the `workspace` config. + +This value is not exported to the environment for child processes. + + + + +#### `include-workspace-root` + +* Default: false +* Type: Boolean + +Include the workspace root when workspaces are enabled for a command. + +When false, specifying individual workspaces via the `workspace` config, or +all workspaces via the `workspaces` flag, will cause npm to operate only on +the specified workspaces, and not on the root project. + +This value is not exported to the environment for child processes. + + + + +#### `install-links` + +* Default: false +* Type: Boolean -The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init ` commands. +When set file: protocol dependencies that exist outside of the project root +will be packed and installed as regular dependencies instead of creating a +symlink. This option has no effect on workspaces. diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md index 74ed4667e81bf..b886f8ab9599a 100644 --- a/docs/content/commands/npm-install-ci-test.md +++ b/docs/content/commands/npm-install-ci-test.md @@ -30,15 +30,129 @@ This command runs `npm ci` followed immediately by `npm test`. -#### `audit` +#### `save` + +* Default: `true` unless when using `npm update` where it defaults to `false` +* Type: Boolean + +Save installed packages to a `package.json` file as dependencies. + +When used with the `npm rm` command, removes the dependency from +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. + + + + +#### `save-exact` + +* Default: false +* Type: Boolean + +Dependencies saved to package.json will be configured with an exact version +rather than using npm's default semver range operator. + + + + +#### `global` + +* Default: false +* Type: Boolean + +Operates in "global" mode, so that packages are installed into the `prefix` +folder instead of the current working directory. See +[folders](/configuring-npm/folders) for more on the differences in behavior. + +* packages are installed into the `{prefix}/lib/node_modules` folder, instead + of the current working directory. +* bin files are linked to `{prefix}/bin` +* man pages are linked to `{prefix}/share/man` + + + + +#### `global-style` + +* Default: false +* Type: Boolean + +Causes npm to install the package into your local `node_modules` folder with +the same layout it uses with the global `node_modules` folder. Only your +direct dependencies will show in `node_modules` and everything they depend +on will be flattened in their `node_modules` folders. This obviously will +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` +will be preferred. + + + + +#### `legacy-bundling` + +* Default: false +* Type: Boolean + +Causes npm to install the package such that versions of npm prior to 1.4, +such as the one included with node 0.8, can install the package. This +eliminates all automatic deduping. If used with `global-style` this option +will be preferred. + + + + +#### `omit` + +* Default: 'dev' if the `NODE_ENV` environment variable is set to + 'production', otherwise empty. +* Type: "dev", "optional", or "peer" (can be set multiple times) + +Dependency types to omit from the installation tree on disk. + +Note that these dependencies _are_ still resolved and added to the +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not +physically installed on disk. + +If a package type appears in both the `--include` and `--omit` lists, then +it will be included. + +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment +variable will be set to `'production'` for all lifecycle scripts. + + + + +#### `strict-peer-deps` + +* Default: false +* Type: Boolean + +If set to `true`, and `--legacy-peer-deps` is not set, then _any_ +conflicting `peerDependencies` will be treated as an install failure, even +if npm could reasonably guess the appropriate resolution based on non-peer +dependency relationships. + +By default, conflicting `peerDependencies` deep in the dependency graph will +be resolved using the nearest non-peer dependency specification, even if +doing so will result in some packages receiving a peer dependency outside +the range set in their package's `peerDependencies` object. + +When such and override is performed, a warning is printed, explaining the +conflict and the packages involved. If `--strict-peer-deps` is set, then +this warning is treated as a failure. + + + + +#### `package-lock` * Default: true * Type: Boolean -When "true" submit audit reports alongside the current npm command to the -default registry and all registries configured for scopes. See the -documentation for [`npm audit`](/commands/npm-audit) for details on what is -submitted. +If set to false, then ignore `package-lock.json` files when installing. This +will also prevent _writing_ `package-lock.json` if `save` is true. + +This configuration does not affect `npm ci`. @@ -73,13 +187,132 @@ will *not* run any pre- or post-scripts. -#### `script-shell` +#### `audit` -* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows -* Type: null or String +* Default: true +* Type: Boolean + +When "true" submit audit reports alongside the current npm command to the +default registry and all registries configured for scopes. See the +documentation for [`npm audit`](/commands/npm-audit) for details on what is +submitted. + + + + +#### `bin-links` + +* Default: true +* Type: Boolean + +Tells npm to create symlinks (or `.cmd` shims on Windows) for package +executables. + +Set to false to have it not do this. This can be used to work around the +fact that some file systems don't support symlinks, even on ostensibly Unix +systems. + + + + +#### `fund` + +* Default: true +* Type: Boolean + +When "true" displays the message at the end of each `npm install` +acknowledging the number of dependencies looking for funding. See [`npm +fund`](/commands/npm-fund) for details. + + + + +#### `dry-run` + +* Default: false +* Type: Boolean + +Indicates that you don't want npm to make any changes and that it should +only report what it would have done. This can be passed into any of the +commands that modify your local installation, eg, `install`, `update`, +`dedupe`, `uninstall`, as well as `pack` and `publish`. + +Note: This is NOT honored by other network related commands, eg `dist-tags`, +`owner`, etc. + + + + +#### `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 in selecting all + workspaces within that folder) + +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: null +* Type: null or Boolean + +Set to true to run the command in the context of **all** configured +workspaces. + +Explicitly setting this to false will cause commands like `install` to +ignore workspaces altogether. When not set explicitly: + +- Commands that operate on the `node_modules` tree (install, update, etc.) +will link workspaces into the `node_modules` folder. - Commands that do +other things (test, exec, publish, etc.) will operate on the root project, +_unless_ one or more workspaces are specified in the `workspace` config. + +This value is not exported to the environment for child processes. + + + + +#### `include-workspace-root` + +* Default: false +* Type: Boolean + +Include the workspace root when workspaces are enabled for a command. + +When false, specifying individual workspaces via the `workspace` config, or +all workspaces via the `workspaces` flag, will cause npm to operate only on +the specified workspaces, and not on the root project. + +This value is not exported to the environment for child processes. + + + + +#### `install-links` + +* Default: false +* Type: Boolean -The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init ` commands. +When set file: protocol dependencies that exist outside of the project root +will be packed and installed as regular dependencies instead of creating a +symlink. This option has no effect on workspaces. diff --git a/lib/commands/ci.js b/lib/commands/ci.js index 2a6125d564e91..0adf203a9856e 100644 --- a/lib/commands/ci.js +++ b/lib/commands/ci.js @@ -9,16 +9,13 @@ const log = require('../utils/log-shim.js') const validateLockfile = require('../utils/validate-lockfile.js') const ArboristWorkspaceCmd = require('../arborist-cmd.js') +const Install = require('./install.js') class CI extends ArboristWorkspaceCmd { static description = 'Clean install a project' static name = 'ci' - static params = [ - 'audit', - 'foreground-scripts', - 'ignore-scripts', - 'script-shell', - ] + + static params = Install.params async exec () { if (this.npm.global) { diff --git a/smoke-tests/tap-snapshots/test/index.js.test.cjs b/smoke-tests/tap-snapshots/test/index.js.test.cjs index 6a803160a4076..cca28b348ea40 100644 --- a/smoke-tests/tap-snapshots/test/index.js.test.cjs +++ b/smoke-tests/tap-snapshots/test/index.js.test.cjs @@ -55,8 +55,13 @@ npm ERR! Usage: npm ERR! npm ci npm ERR! npm ERR! Options: -npm ERR! [--no-audit] [--foreground-scripts] [--ignore-scripts] -npm ERR! [--script-shell ] +npm ERR! [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] +npm ERR! [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] +npm ERR! [--omit [--omit ...]] +npm ERR! [--strict-peer-deps] [--no-package-lock] [--foreground-scripts] +npm ERR! [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] +npm ERR! [-w|--workspace [-w|--workspace ...]] +npm ERR! [-ws|--workspaces] [--include-workspace-root] [--install-links] npm ERR! npm ERR! aliases: clean-install, ic, install-clean, isntall-clean npm ERR! diff --git a/tap-snapshots/test/lib/load-all-commands.js.test.cjs b/tap-snapshots/test/lib/load-all-commands.js.test.cjs index b697dfbb796c6..88b1d49556fd8 100644 --- a/tap-snapshots/test/lib/load-all-commands.js.test.cjs +++ b/tap-snapshots/test/lib/load-all-commands.js.test.cjs @@ -116,8 +116,13 @@ Usage: npm ci Options: -[--no-audit] [--foreground-scripts] [--ignore-scripts] -[--script-shell ] +[-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] +[-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] +[--omit [--omit ...]] +[--strict-peer-deps] [--no-package-lock] [--foreground-scripts] +[--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] +[-w|--workspace [-w|--workspace ...]] +[-ws|--workspaces] [--include-workspace-root] [--install-links] aliases: clean-install, ic, install-clean, isntall-clean @@ -425,8 +430,13 @@ Usage: npm install-ci-test Options: -[--no-audit] [--foreground-scripts] [--ignore-scripts] -[--script-shell ] +[-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] +[-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] +[--omit [--omit ...]] +[--strict-peer-deps] [--no-package-lock] [--foreground-scripts] +[--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] +[-w|--workspace [-w|--workspace ...]] +[-ws|--workspaces] [--include-workspace-root] [--install-links] alias: cit diff --git a/tap-snapshots/test/lib/npm.js.test.cjs b/tap-snapshots/test/lib/npm.js.test.cjs index 3cdf37684de27..ea7d2a7e1cdc0 100644 --- a/tap-snapshots/test/lib/npm.js.test.cjs +++ b/tap-snapshots/test/lib/npm.js.test.cjs @@ -254,8 +254,13 @@ All commands: npm ci Options: - [--no-audit] [--foreground-scripts] [--ignore-scripts] - [--script-shell ] + [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] + [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] + [--omit [--omit ...]] + [--strict-peer-deps] [--no-package-lock] [--foreground-scripts] + [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] + [-w|--workspace [-w|--workspace ...]] + [-ws|--workspaces] [--include-workspace-root] [--install-links] aliases: clean-install, ic, install-clean, isntall-clean @@ -511,8 +516,13 @@ All commands: npm install-ci-test Options: - [--no-audit] [--foreground-scripts] [--ignore-scripts] - [--script-shell ] + [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] + [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] + [--omit [--omit ...]] + [--strict-peer-deps] [--no-package-lock] [--foreground-scripts] + [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run] + [-w|--workspace [-w|--workspace ...]] + [-ws|--workspaces] [--include-workspace-root] [--install-links] alias: cit