diff options
author | Wassim Chegham <1699357+manekinekko@users.noreply.github.com> | 2022-02-24 20:46:37 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-02-24 20:46:37 +0300 |
commit | 6b68c1aaa282205eb4d47dbc81909c11851f7e06 (patch) | |
tree | a5a2ddafe61e5e475913a316a3ca59893629f986 | |
parent | d438d61d4f689966de8f964afe212d1319b8d460 (diff) |
docs: auto-generate npm usage for each command (#4450)
Closes #4189
* docs: auto-generate synopsis sections
* feat: improve usage auto-generation'
* chore: auto-generate npm usage for each command
* docs: print default usage when usage is missing
* docs: add special case for npx
* fix: remove optional chaining
65 files changed, 821 insertions, 164 deletions
diff --git a/docs/content/commands/npm-access.md b/docs/content/commands/npm-access.md index 1f661c911..162e94f1f 100644 --- a/docs/content/commands/npm-access.md +++ b/docs/content/commands/npm-access.md @@ -6,21 +6,27 @@ description: Set access level on published packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/access.js --> + ```bash npm access public [<package>] npm access restricted [<package>] - npm access grant <read-only|read-write> <scope:team> [<package>] npm access revoke <scope:team> [<package>] - npm access 2fa-required [<package>] npm access 2fa-not-required [<package>] - npm access ls-packages [<user>|<scope>|<scope:team>] npm access ls-collaborators [<package> [<user>]] npm access edit [<package>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/access.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Used to set access controls on private packages. diff --git a/docs/content/commands/npm-adduser.md b/docs/content/commands/npm-adduser.md index 21a31ca94..06eeb379c 100644 --- a/docs/content/commands/npm-adduser.md +++ b/docs/content/commands/npm-adduser.md @@ -6,12 +6,21 @@ description: Add a registry user account ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/adduser.js --> + ```bash -npm adduser [--registry=url] [--scope=@orgname] [--auth-type=legacy] +npm adduser aliases: login, add-user ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/adduser.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-audit.md b/docs/content/commands/npm-audit.md index 58c614d79..323d38f64 100644 --- a/docs/content/commands/npm-audit.md +++ b/docs/content/commands/npm-audit.md @@ -6,13 +6,19 @@ description: Run a security audit ### Synopsis -```bash -npm audit [--json] [--production] [--audit-level=(low|moderate|high|critical)] -npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)] +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/audit.js --> -common options: [--production] [--only=(dev|prod)] +```bash +npm audit [fix] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/audit.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description The audit command submits a description of the dependencies configured in diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md index 2d7c1d5b8..94b72cfd5 100644 --- a/docs/content/commands/npm-bin.md +++ b/docs/content/commands/npm-bin.md @@ -6,10 +6,19 @@ description: Display npm bin folder ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/bin.js --> + ```bash -npm bin [-g|--global] +npm bin ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/bin.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-bugs.md b/docs/content/commands/npm-bugs.md index f92241a14..aeddeb848 100644 --- a/docs/content/commands/npm-bugs.md +++ b/docs/content/commands/npm-bugs.md @@ -6,12 +6,21 @@ description: Report bugs for a package in a web browser ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/bugs.js --> + ```bash -npm bugs [<pkgname> [<pkgname> ...]] +npm bugs [<pkgname>] -aliases: issues +alias: issues ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/bugs.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command tries to guess at the likely location of a package's bug diff --git a/docs/content/commands/npm-cache.md b/docs/content/commands/npm-cache.md index 6497a3988..091e26e8a 100644 --- a/docs/content/commands/npm-cache.md +++ b/docs/content/commands/npm-cache.md @@ -6,18 +6,26 @@ description: Manipulates packages cache ### Synopsis -```bash -npm cache add <tarball file>... -npm cache add <folder>... -npm cache add <tarball url>... -npm cache add <name>@<version>... - -npm cache clean -aliases: npm cache clear, npm cache rm +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/cache.js --> +```bash +npm cache add <tarball file> +npm cache add <folder> +npm cache add <tarball url> +npm cache add <git url> +npm cache add <name>@<version> +npm cache clean [<key>] +npm cache ls [<name>@<version>] npm cache verify ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/cache.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md index 1ce50c66d..4490fea9a 100644 --- a/docs/content/commands/npm-ci.md +++ b/docs/content/commands/npm-ci.md @@ -6,10 +6,21 @@ description: Install a project with a clean slate ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/ci.js --> + ```bash npm ci + +aliases: clean-install, ic, install-clean, isntall-clean ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/ci.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command is similar to [`npm install`](/commands/npm-install), except diff --git a/docs/content/commands/npm-completion.md b/docs/content/commands/npm-completion.md index 9dbd96091..d73a98f2e 100644 --- a/docs/content/commands/npm-completion.md +++ b/docs/content/commands/npm-completion.md @@ -6,10 +6,19 @@ description: Tab Completion for npm ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/completion.js --> + ```bash -source <(npm completion) +npm completion ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/completion.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-config.md b/docs/content/commands/npm-config.md index 2d77f045c..a66a198ce 100644 --- a/docs/content/commands/npm-config.md +++ b/docs/content/commands/npm-config.md @@ -6,18 +6,25 @@ description: Manage the npm configuration files ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/config.js --> + ```bash npm config set <key>=<value> [<key>=<value> ...] npm config get [<key> [<key> ...]] npm config delete <key> [<key> ...] npm config list [--json] npm config edit -npm set <key>=<value> [<key>=<value> ...] -npm get [<key> [<key> ...]] alias: c ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/config.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md index 53d2e6427..b5a64831c 100644 --- a/docs/content/commands/npm-dedupe.md +++ b/docs/content/commands/npm-dedupe.md @@ -6,13 +6,21 @@ description: Reduce duplication in the package tree ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/dedupe.js --> + ```bash npm dedupe -npm ddp -aliases: ddp +alias: ddp ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/dedupe.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Searches the local package tree and attempts to simplify the overall @@ -145,6 +153,24 @@ When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. +This configuration does not affect `npm ci`. + +<!-- automatically generated, do not edit manually --> +<!-- see lib/utils/config/definitions.js --> + +#### `save` + +* Default: `true` unless when using `npm update` or `npm dedupe` 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`. + <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-deprecate.md b/docs/content/commands/npm-deprecate.md index 438a54ec6..4345120d3 100644 --- a/docs/content/commands/npm-deprecate.md +++ b/docs/content/commands/npm-deprecate.md @@ -6,10 +6,19 @@ description: Deprecate a version of a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/deprecate.js --> + ```bash -npm deprecate <pkg>[@<version range>] <message> +npm deprecate <pkg>[@<version>] <message> ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/deprecate.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-diff.md b/docs/content/commands/npm-diff.md index 8d05df779..c4c9eafdb 100644 --- a/docs/content/commands/npm-diff.md +++ b/docs/content/commands/npm-diff.md @@ -6,14 +6,19 @@ description: The registry diff command ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/diff.js --> + ```bash npm diff [...<paths>] -npm diff --diff=<pkg-name> [...<paths>] -npm diff --diff=<version-a> [--diff=<version-b>] [...<paths>] -npm diff --diff=<spec-a> [--diff=<spec-b>] [...<paths>] -npm diff [--diff-ignore-all-space] [--diff-name-only] [...<paths>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/diff.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Similar to its `git diff` counterpart, this command will print diff patches diff --git a/docs/content/commands/npm-dist-tag.md b/docs/content/commands/npm-dist-tag.md index a4e0243aa..a0f306cd4 100644 --- a/docs/content/commands/npm-dist-tag.md +++ b/docs/content/commands/npm-dist-tag.md @@ -6,14 +6,23 @@ description: Modify package distribution tags ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/dist-tag.js --> + ```bash npm dist-tag add <pkg>@<version> [<tag>] npm dist-tag rm <pkg> <tag> npm dist-tag ls [<pkg>] -aliases: dist-tags +alias: dist-tags ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/dist-tag.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Add, remove, and enumerate distribution tags on a package: diff --git a/docs/content/commands/npm-docs.md b/docs/content/commands/npm-docs.md index 970d17aa8..8d5a27828 100644 --- a/docs/content/commands/npm-docs.md +++ b/docs/content/commands/npm-docs.md @@ -6,12 +6,21 @@ description: Open documentation for a package in a web browser ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/docs.js --> + ```bash npm docs [<pkgname> [<pkgname> ...]] -aliases: home +alias: home ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/docs.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command tries to guess at the likely location of a package's diff --git a/docs/content/commands/npm-doctor.md b/docs/content/commands/npm-doctor.md index 0cce60c7b..7fb63bab1 100644 --- a/docs/content/commands/npm-doctor.md +++ b/docs/content/commands/npm-doctor.md @@ -6,10 +6,19 @@ description: Check your npm environment ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/doctor.js --> + ```bash npm doctor ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/doctor.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-edit.md b/docs/content/commands/npm-edit.md index 5ae7f2481..39fc49592 100644 --- a/docs/content/commands/npm-edit.md +++ b/docs/content/commands/npm-edit.md @@ -6,10 +6,19 @@ description: Edit an installed package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/edit.js --> + ```bash -npm edit <pkg> +npm edit <pkg>[/<subpkg>...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/edit.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md index d154f5780..3645e336b 100644 --- a/docs/content/commands/npm-exec.md +++ b/docs/content/commands/npm-exec.md @@ -6,26 +6,23 @@ description: Run a command from a local or remote npm package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/exec.js --> + ```bash npm exec -- <pkg>[@<version>] [args...] npm exec --package=<pkg>[@<version>] -- <cmd> [args...] npm exec -c '<cmd> [args...]' npm exec --package=foo -c '<cmd> [args...]' -npm exec [--ws] [-w <workspace-name] [args...] -npx <pkg>[@<specifier>] [args...] -npx -p <pkg>[@<specifier>] <cmd> [args...] -npx -c '<cmd> [args...]' -npx -p <pkg>[@<specifier>] -c '<cmd> [args...]' -Run without --call or positional args to open interactive subshell +alias: x +``` -alias: npm x, npx +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/exec.js --> -common options: ---package=<pkg> (may be specified multiple times) --p is a shorthand for --package only when using npx executable --c <cmd> --call=<cmd> (may not be mixed with positional arguments) -``` +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> ### Description diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md index 5f05cac0f..765221056 100644 --- a/docs/content/commands/npm-explain.md +++ b/docs/content/commands/npm-explain.md @@ -6,12 +6,21 @@ description: Explain installed packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/explain.js --> + ```bash npm explain <folder | specifier> alias: why ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/explain.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command will print the chain of dependencies causing a given package diff --git a/docs/content/commands/npm-explore.md b/docs/content/commands/npm-explore.md index 3979da957..90753c7e0 100644 --- a/docs/content/commands/npm-explore.md +++ b/docs/content/commands/npm-explore.md @@ -6,10 +6,19 @@ description: Browse an installed package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/explore.js --> + ```bash npm explore <pkg> [ -- <command>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/explore.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-find-dupes.md b/docs/content/commands/npm-find-dupes.md index f7dc84f9c..f7366fa63 100644 --- a/docs/content/commands/npm-find-dupes.md +++ b/docs/content/commands/npm-find-dupes.md @@ -6,10 +6,19 @@ description: Find duplication in the package tree ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/find-dupes.js --> + ```bash npm find-dupes ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/find-dupes.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Runs `npm dedupe` in `--dry-run` mode, making npm only output the @@ -82,6 +91,8 @@ When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. +This configuration does not affect `npm ci`. + <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-fund.md b/docs/content/commands/npm-fund.md index 606b0a188..5b96e91ab 100644 --- a/docs/content/commands/npm-fund.md +++ b/docs/content/commands/npm-fund.md @@ -6,11 +6,19 @@ description: Retrieve funding information ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/fund.js --> + ```bash -npm fund [<pkg>] -npm fund [-w <workspace-name>] +npm fund [[<@scope>/]<pkg>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/fund.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command retrieves information on how to fund the dependencies of a diff --git a/docs/content/commands/npm-help-search.md b/docs/content/commands/npm-help-search.md index 78553a14e..152f9f6be 100644 --- a/docs/content/commands/npm-help-search.md +++ b/docs/content/commands/npm-help-search.md @@ -6,10 +6,19 @@ description: Search npm help documentation ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/help-search.js --> + ```bash npm help-search <text> ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/help-search.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-help.md b/docs/content/commands/npm-help.md index a8002eef1..83c595db6 100644 --- a/docs/content/commands/npm-help.md +++ b/docs/content/commands/npm-help.md @@ -6,10 +6,21 @@ description: Get help on npm ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/help.js --> + ```bash npm help <term> [<terms..>] + +alias: hlep ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/help.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-hook.md b/docs/content/commands/npm-hook.md index c91bce307..4a9805d02 100644 --- a/docs/content/commands/npm-hook.md +++ b/docs/content/commands/npm-hook.md @@ -6,13 +6,22 @@ description: Manage registry hooks ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/hook.js --> + ```bash +npm hook add <pkg> <url> <secret> [--type=<type>] npm hook ls [pkg] -npm hook add <entity> <url> <secret> -npm hook update <id> <url> [secret] npm hook rm <id> +npm hook update <id> <url> <secret> ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/hook.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md index e9212a37e..d9c03aef4 100644 --- a/docs/content/commands/npm-init.md +++ b/docs/content/commands/npm-init.md @@ -6,13 +6,23 @@ description: Create a package.json file ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/init.js --> + ```bash -npm init [--yes|-y|--scope] -npm init <@scope> (same as `npm exec <@scope>/create`) -npm init [<@scope>/]<name> (same as `npm exec [<@scope>/]create-<name>`) -npm init [-w <dir>] [args...] +npm init [--force|-f|--yes|-y|--scope] +npm init <@scope> (same as `npx <@scope>/create`) +npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`) + +aliases: create, innit ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/init.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description `npm init <initializer>` can be used to set up a new or existing npm diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md index 5c37ed8f5..5ad676045 100644 --- a/docs/content/commands/npm-install-ci-test.md +++ b/docs/content/commands/npm-install-ci-test.md @@ -6,12 +6,21 @@ description: Install a project with a clean slate and run tests ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/install-ci-test.js --> + ```bash npm install-ci-test -alias: npm cit +alias: cit ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/install-ci-test.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command runs `npm ci` followed immediately by `npm test`. diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md index c464e5bd0..ed39c6705 100644 --- a/docs/content/commands/npm-install-test.md +++ b/docs/content/commands/npm-install-test.md @@ -6,20 +6,30 @@ description: Install package(s) and run tests ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/install-test.js --> + ```bash -npm install-test (with no args, in package dir) -npm install-test [<@scope>/]<name> -npm install-test [<@scope>/]<name>@<tag> -npm install-test [<@scope>/]<name>@<version> -npm install-test [<@scope>/]<name>@<version range> +npm install-test [<@scope>/]<pkg> +npm install-test [<@scope>/]<pkg>@<tag> +npm install-test [<@scope>/]<pkg>@<version> +npm install-test [<@scope>/]<pkg>@<version range> +npm install-test <alias>@npm:<name> +npm install-test <folder> npm install-test <tarball file> npm install-test <tarball url> -npm install-test <folder> +npm install-test <git:// url> +npm install-test <github username>/<github project> -alias: npm it -common options: [--save|--save-dev|--save-optional] [--save-exact] [--dry-run] +alias: it ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/install-test.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command runs an `npm install` followed immediately by an `npm test`. It @@ -32,13 +42,16 @@ takes exactly the same arguments as `npm install`. <!-- see lib/utils/config/definitions.js --> #### `save` -* Default: true +* Default: `true` unless when using `npm update` or `npm dedupe` where it + defaults to `false` * Type: Boolean -Save installed packages to a package.json file as dependencies. +Save installed packages to a `package.json` file as dependencies. When used with the `npm rm` command, removes the dependency from -package.json. +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> @@ -133,6 +146,8 @@ When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. +This configuration does not affect `npm ci`. + <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md index b4f8da837..66193e733 100644 --- a/docs/content/commands/npm-install.md +++ b/docs/content/commands/npm-install.md @@ -6,23 +6,30 @@ description: Install a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/install.js --> + ```bash -npm install (with no args, in package dir) -npm install [<@scope>/]<name> -npm install [<@scope>/]<name>@<tag> -npm install [<@scope>/]<name>@<version> -npm install [<@scope>/]<name>@<version range> +npm install [<@scope>/]<pkg> +npm install [<@scope>/]<pkg>@<tag> +npm install [<@scope>/]<pkg>@<version> +npm install [<@scope>/]<pkg>@<version range> npm install <alias>@npm:<name> -npm install <git-host>:<git-user>/<repo-name> -npm install <git repo url> +npm install <folder> npm install <tarball file> npm install <tarball url> -npm install <folder> +npm install <git:// url> +npm install <github username>/<github project> -aliases: npm i, npm add -common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional|--save-peer] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run] +aliases: i, in, ins, inst, insta, instal, isnt, isnta, isntal, add ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/install.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command installs a package and any packages that it depends on. If the @@ -425,13 +432,16 @@ These are some of the most common options related to installation. <!-- see lib/utils/config/definitions.js --> #### `save` -* Default: true +* Default: `true` unless when using `npm update` or `npm dedupe` where it + defaults to `false` * Type: Boolean -Save installed packages to a package.json file as dependencies. +Save installed packages to a `package.json` file as dependencies. When used with the `npm rm` command, removes the dependency from -package.json. +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> @@ -526,6 +536,8 @@ When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. +This configuration does not affect `npm ci`. + <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md index d4ef41ae9..892b55496 100644 --- a/docs/content/commands/npm-link.md +++ b/docs/content/commands/npm-link.md @@ -6,13 +6,22 @@ description: Symlink a package folder ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/link.js --> + ```bash npm link (in package dir) npm link [<@scope>/]<pkg>[@<version>] -alias: npm ln +alias: ln ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/link.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This is handy for installing your own stuff, so that you can work on it and @@ -116,13 +125,16 @@ workspace(s). <!-- see lib/utils/config/definitions.js --> #### `save` -* Default: true +* Default: `true` unless when using `npm update` or `npm dedupe` where it + defaults to `false` * Type: Boolean -Save installed packages to a package.json file as dependencies. +Save installed packages to a `package.json` file as dependencies. When used with the `npm rm` command, removes the dependency from -package.json. +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> @@ -217,6 +229,8 @@ When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. +This configuration does not affect `npm ci`. + <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md index cb7c8496f..f0dd5cb85 100644 --- a/docs/content/commands/npm-logout.md +++ b/docs/content/commands/npm-logout.md @@ -6,10 +6,19 @@ description: Log out of the registry ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/logout.js --> + ```bash -npm logout [--registry=<url>] [--scope=<@scope>] +npm logout ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/logout.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md index 3b33f0a36..0f06e131f 100644 --- a/docs/content/commands/npm-ls.md +++ b/docs/content/commands/npm-ls.md @@ -6,12 +6,21 @@ description: List installed packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/ls.js --> + ```bash npm ls [[<@scope>/]<pkg> ...] -aliases: list, la, ll +alias: list ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/ls.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command will print to stdout all the versions of packages that are diff --git a/docs/content/commands/npm-org.md b/docs/content/commands/npm-org.md index 2f08f6115..975581c86 100644 --- a/docs/content/commands/npm-org.md +++ b/docs/content/commands/npm-org.md @@ -6,12 +6,23 @@ description: Manage orgs ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/org.js --> + ```bash -npm org set <orgname> <username> [developer | admin | owner] -npm org rm <orgname> <username> -npm org ls <orgname> [<username>] +npm org set orgname username [developer | admin | owner] +npm org rm orgname username +npm org ls orgname [<username>] + +alias: ogr ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/org.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Example diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md index 1b58a6afd..6fa026550 100644 --- a/docs/content/commands/npm-outdated.md +++ b/docs/content/commands/npm-outdated.md @@ -6,10 +6,19 @@ description: Check for outdated packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/outdated.js --> + ```bash npm outdated [[<@scope>/]<pkg> ...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/outdated.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command will check the registry to see if any (or, specific) installed diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md index 74e7f84af..0779984e1 100644 --- a/docs/content/commands/npm-owner.md +++ b/docs/content/commands/npm-owner.md @@ -6,14 +6,23 @@ description: Manage package owners ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/owner.js --> + ```bash npm owner add <user> [<@scope>/]<pkg> npm owner rm <user> [<@scope>/]<pkg> npm owner ls [<@scope>/]<pkg> -aliases: author +alias: author ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/owner.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md index 539459868..c834f643a 100644 --- a/docs/content/commands/npm-pack.md +++ b/docs/content/commands/npm-pack.md @@ -6,10 +6,19 @@ description: Create a tarball from a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/pack.js --> + ```bash -npm pack [[<@scope>/]<pkg>...] [--dry-run] [--json] +npm pack [[<@scope>/]<pkg>...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/pack.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Configuration <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md index c59a56e61..161d7292f 100644 --- a/docs/content/commands/npm-ping.md +++ b/docs/content/commands/npm-ping.md @@ -6,10 +6,19 @@ description: Ping npm registry ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/ping.js --> + ```bash -npm ping [--registry <registry>] +npm ping ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/ping.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-pkg.md b/docs/content/commands/npm-pkg.md index beee9c1c4..8f6cbecf9 100644 --- a/docs/content/commands/npm-pkg.md +++ b/docs/content/commands/npm-pkg.md @@ -6,12 +6,21 @@ description: Manages your package.json ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/pkg.js --> + ```bash -npm pkg get [<field> [.<subfield> ...]] -npm pkg set <field>=<value> [.<subfield>=<value> ...] -npm pkg delete <field> [.<subfield> ...] +npm pkg set <key>=<value> [<key>=<value> ...] +npm pkg get [<key> [<key> ...]] +npm pkg delete <key> [<key> ...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/pkg.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description A command that automates the management of `package.json` files. diff --git a/docs/content/commands/npm-prefix.md b/docs/content/commands/npm-prefix.md index 276a9e9e6..39328bcc8 100644 --- a/docs/content/commands/npm-prefix.md +++ b/docs/content/commands/npm-prefix.md @@ -6,10 +6,19 @@ description: Display prefix ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/prefix.js --> + ```bash npm prefix [-g] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/prefix.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-profile.md b/docs/content/commands/npm-profile.md index cecc48518..af1f9d8aa 100644 --- a/docs/content/commands/npm-profile.md +++ b/docs/content/commands/npm-profile.md @@ -6,14 +6,22 @@ description: Change settings on your registry profile ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/profile.js --> + ```bash -npm profile get [--json|--parseable] [<property>] -npm profile set [--json|--parseable] <property> <value> -npm profile set password -npm profile enable-2fa [auth-and-writes|auth-only] +npm profile enable-2fa [auth-only|auth-and-writes] npm profile disable-2fa +npm profile get [<key>] +npm profile set <key> <value> ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/profile.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md index 658ab2610..49420e5b9 100644 --- a/docs/content/commands/npm-prune.md +++ b/docs/content/commands/npm-prune.md @@ -6,10 +6,19 @@ description: Remove extraneous packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/prune.js --> + ```bash -npm prune [[<@scope>/]<pkg>...] [--production] [--dry-run] [--json] +npm prune [[<@scope>/]<pkg>...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/prune.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command removes "extraneous" packages. If a package name is provided, diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md index 6958b1066..ce6e1c101 100644 --- a/docs/content/commands/npm-publish.md +++ b/docs/content/commands/npm-publish.md @@ -6,13 +6,19 @@ description: Publish a package ### Synopsis -```bash -npm publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>] [--otp otpcode] [--dry-run] +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/publish.js --> -Publishes '.' if no argument supplied -Sets tag 'latest' if no --tag specified +```bash +npm publish [<folder>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/publish.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Publishes a package to the registry so that it can be installed by name. diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md index 75e71c60e..ecb4a7ce3 100644 --- a/docs/content/commands/npm-rebuild.md +++ b/docs/content/commands/npm-rebuild.md @@ -6,12 +6,21 @@ description: Rebuild a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/rebuild.js --> + ```bash npm rebuild [[<@scope>/]<name>[@<version>] ...] alias: rb ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/rebuild.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command runs the `npm build` command on the matched folders. This is diff --git a/docs/content/commands/npm-repo.md b/docs/content/commands/npm-repo.md index cd47fde47..e14f07012 100644 --- a/docs/content/commands/npm-repo.md +++ b/docs/content/commands/npm-repo.md @@ -6,10 +6,19 @@ description: Open package repository page in the browser ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/repo.js --> + ```bash npm repo [<pkgname> [<pkgname> ...]] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/repo.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command tries to guess at the likely location of a package's diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md index 80f8ab77e..f01cd014e 100644 --- a/docs/content/commands/npm-restart.md +++ b/docs/content/commands/npm-restart.md @@ -6,10 +6,19 @@ description: Restart a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/restart.js --> + ```bash npm restart [-- <args>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/restart.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This restarts a project. It is equivalent to running `npm run-script diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md index 98d1108d3..40b58e4b3 100644 --- a/docs/content/commands/npm-root.md +++ b/docs/content/commands/npm-root.md @@ -6,10 +6,19 @@ description: Display npm root ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/root.js --> + ```bash -npm root [-g] +npm root ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/root.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description Print the effective `node_modules` folder to standard out. diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md index 6dd602d03..79b7c9a25 100644 --- a/docs/content/commands/npm-run-script.md +++ b/docs/content/commands/npm-run-script.md @@ -6,14 +6,21 @@ description: Run arbitrary package scripts ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/run-script.js --> + ```bash -npm run-script <command> [--if-present] [--silent] [-- <args>] -npm run-script <command> [--workspace=<workspace-name>] -npm run-script <command> [--workspaces] +npm run-script <command> [-- <args>] aliases: run, rum, urn ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/run-script.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This runs an arbitrary command from a package's `"scripts"` object. If no diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md index 252822e71..db6a12baf 100644 --- a/docs/content/commands/npm-search.md +++ b/docs/content/commands/npm-search.md @@ -6,12 +6,21 @@ description: Search for packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/search.js --> + ```bash -npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...] +npm search [search terms ...] aliases: s, se, find ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/search.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-set-script.md b/docs/content/commands/npm-set-script.md index 869ceede0..2d8e87db8 100644 --- a/docs/content/commands/npm-set-script.md +++ b/docs/content/commands/npm-set-script.md @@ -7,10 +7,19 @@ description: Set tasks in the scripts section of package.json ### Synopsis An npm command that lets you create a task in the `scripts` section of the `package.json`. +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/set-script.js --> + ```bash npm set-script [<script>] [<command>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/set-script.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + **Example:** diff --git a/docs/content/commands/npm-shrinkwrap.md b/docs/content/commands/npm-shrinkwrap.md index 678622946..043b4ad1b 100644 --- a/docs/content/commands/npm-shrinkwrap.md +++ b/docs/content/commands/npm-shrinkwrap.md @@ -6,10 +6,19 @@ description: Lock down dependency versions for publication ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/shrinkwrap.js --> + ```bash npm shrinkwrap ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/shrinkwrap.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-star.md b/docs/content/commands/npm-star.md index 21109c350..bbec7ac5f 100644 --- a/docs/content/commands/npm-star.md +++ b/docs/content/commands/npm-star.md @@ -6,10 +6,19 @@ description: Mark your favorite packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/star.js --> + ```bash npm star [<pkg>...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/star.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-stars.md b/docs/content/commands/npm-stars.md index 101559ad9..b91538315 100644 --- a/docs/content/commands/npm-stars.md +++ b/docs/content/commands/npm-stars.md @@ -5,10 +5,20 @@ description: View packages marked as favorites --- ### Synopsis + +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/stars.js --> + ```bash npm stars [<user>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/stars.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-start.md b/docs/content/commands/npm-start.md index 50a54cb5e..8dd874b3c 100644 --- a/docs/content/commands/npm-start.md +++ b/docs/content/commands/npm-start.md @@ -6,10 +6,19 @@ description: Start a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/start.js --> + ```bash npm start [-- <args>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/start.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This runs a predefined command specified in the `"start"` property of diff --git a/docs/content/commands/npm-stop.md b/docs/content/commands/npm-stop.md index d4de4caf3..9a3a55cf3 100644 --- a/docs/content/commands/npm-stop.md +++ b/docs/content/commands/npm-stop.md @@ -6,10 +6,19 @@ description: Stop a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/stop.js --> + ```bash npm stop [-- <args>] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/stop.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This runs a predefined command specified in the "stop" property of a diff --git a/docs/content/commands/npm-team.md b/docs/content/commands/npm-team.md index 6050af1df..dc26fb53a 100644 --- a/docs/content/commands/npm-team.md +++ b/docs/content/commands/npm-team.md @@ -6,16 +6,23 @@ description: Manage organization teams and team memberships ### Synopsis -```bash -npm team create <scope:team> -npm team destroy <scope:team> - -npm team add <scope:team> <user> -npm team rm <scope:team> <user> +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/team.js --> +```bash +npm team create <scope:team> [--otp <otpcode>] +npm team destroy <scope:team> [--otp <otpcode>] +npm team add <scope:team> <user> [--otp <otpcode>] +npm team rm <scope:team> <user> [--otp <otpcode>] npm team ls <scope>|<scope:team> ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/team.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-test.md b/docs/content/commands/npm-test.md index 2059f93de..8a343ab29 100644 --- a/docs/content/commands/npm-test.md +++ b/docs/content/commands/npm-test.md @@ -6,12 +6,21 @@ description: Test a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/test.js --> + ```bash npm test [-- <args>] -aliases: t, tst +aliases: tst, t ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/test.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This runs a predefined command specified in the `"test"` property of diff --git a/docs/content/commands/npm-token.md b/docs/content/commands/npm-token.md index 16da1f731..856ad68c9 100644 --- a/docs/content/commands/npm-token.md +++ b/docs/content/commands/npm-token.md @@ -5,12 +5,22 @@ description: Manage your authentication tokens --- ### Synopsis + +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/token.js --> + ```bash - npm token list [--json|--parseable] - npm token create [--read-only] [--cidr=1.1.1.1/24,2.2.2.2/16] - npm token revoke <id|token> +npm token list +npm token revoke <id|token> +npm token create [--read-only] [--cidr=list] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/token.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-uninstall.md b/docs/content/commands/npm-uninstall.md index 824d0d876..8132bf6bc 100644 --- a/docs/content/commands/npm-uninstall.md +++ b/docs/content/commands/npm-uninstall.md @@ -6,12 +6,21 @@ description: Remove a package ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/uninstall.js --> + ```bash -npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save] +npm uninstall [<@scope>/]<pkg>... -aliases: remove, rm, r, un, unlink +aliases: un, unlink, remove, rm, r ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/uninstall.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This uninstalls a package, completely removing everything npm installed @@ -61,13 +70,16 @@ npm uninstall lodash --no-save <!-- see lib/utils/config/definitions.js --> #### `save` -* Default: true +* Default: `true` unless when using `npm update` or `npm dedupe` where it + defaults to `false` * Type: Boolean -Save installed packages to a package.json file as dependencies. +Save installed packages to a `package.json` file as dependencies. When used with the `npm rm` command, removes the dependency from -package.json. +`package.json`. + +Will also prevent writing to `package-lock.json` if set to `false`. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-unstar.md b/docs/content/commands/npm-unstar.md index d6e362077..76202190d 100644 --- a/docs/content/commands/npm-unstar.md +++ b/docs/content/commands/npm-unstar.md @@ -6,10 +6,19 @@ description: Remove an item from your favorite packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/unstar.js --> + ```bash npm unstar [<pkg>...] ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/unstar.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm-update.md b/docs/content/commands/npm-update.md index 1889d6056..e1b48a8ed 100644 --- a/docs/content/commands/npm-update.md +++ b/docs/content/commands/npm-update.md @@ -6,12 +6,21 @@ description: Update packages ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/update.js --> + ```bash -npm update [-g] [<pkg>...] +npm update [<pkg>...] -aliases: up, upgrade +aliases: up, upgrade, udpate ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/update.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command will update all the packages listed to the latest version @@ -239,6 +248,24 @@ When package package-locks are disabled, automatic pruning of extraneous modules will also be disabled. To remove extraneous modules with package-locks disabled use `npm prune`. +This configuration does not affect `npm ci`. + +<!-- automatically generated, do not edit manually --> +<!-- see lib/utils/config/definitions.js --> + +#### `save` + +* Default: `true` unless when using `npm update` or `npm dedupe` 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`. + <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-version.md b/docs/content/commands/npm-version.md index 91ab0dee0..b53dd64ae 100644 --- a/docs/content/commands/npm-version.md +++ b/docs/content/commands/npm-version.md @@ -6,14 +6,21 @@ description: Bump a package version ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/version.js --> + ```bash -npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git] +npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git] -'npm [-v | --version]' to print npm version -'npm view <pkg> version' to view a package's published version -'npm ls' to inspect current package/dependency versions +alias: verison ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/version.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Configuration <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> diff --git a/docs/content/commands/npm-view.md b/docs/content/commands/npm-view.md index 9a1793f13..53ca408a0 100644 --- a/docs/content/commands/npm-view.md +++ b/docs/content/commands/npm-view.md @@ -6,12 +6,21 @@ description: View registry info ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/view.js --> + ```bash -npm view [<@scope>/]<name>[@<version>] [<field>[.<subfield>]...] +npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...] -aliases: info, show, v +aliases: v, info, show ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/view.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + ### Description This command shows data about a package and prints it to stdout. diff --git a/docs/content/commands/npm-whoami.md b/docs/content/commands/npm-whoami.md index 2cd7ffde3..18416f633 100644 --- a/docs/content/commands/npm-whoami.md +++ b/docs/content/commands/npm-whoami.md @@ -6,10 +6,19 @@ description: Display npm username ### Synopsis +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/whoami.js --> + ```bash -npm whoami [--registry <registry>] +npm whoami ``` +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/whoami.js --> + +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> + Note: This command is unaware of workspaces. ### Description diff --git a/docs/content/commands/npm.md b/docs/content/commands/npm.md index de5108706..aaf295dfd 100644 --- a/docs/content/commands/npm.md +++ b/docs/content/commands/npm.md @@ -6,9 +6,8 @@ description: javascript package manager ### Synopsis -```bash -npm <command> [args] -``` +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> ### Version diff --git a/docs/content/commands/npx.md b/docs/content/commands/npx.md index c1aae0b9f..e7e59d00d 100644 --- a/docs/content/commands/npx.md +++ b/docs/content/commands/npx.md @@ -6,23 +6,21 @@ description: Run a command from a local or remote npm package ### Synopsis -```bash -npm exec -- <pkg>[@<version>] [args...] -npm exec --package=<pkg>[@<version>] -- <cmd> [args...] -npm exec -c '<cmd> [args...]' -npm exec --package=foo -c '<cmd> [args...]' +<!-- AUTOGENERATED USAGE DESCRIPTIONS START --> +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/exec.js --> -npx <pkg>[@<specifier>] [args...] -npx -p <pkg>[@<specifier>] <cmd> [args...] +```bash +npx -- <pkg>[@<version>] [args...] +npx --package=<pkg>[@<version>] -- <cmd> [args...] npx -c '<cmd> [args...]' -npx -p <pkg>[@<specifier>] -c '<cmd> [args...]' +npx --package=foo -c '<cmd> [args...]' +``` -alias: npm x, npx +<!-- automatically generated, do not edit manually --> +<!-- see lib/commands/exec.js --> ---package=<pkg> (may be specified multiple times) --p is a shorthand for --package only when using npx executable --c <cmd> --call=<cmd> (may not be mixed with positional arguments) -``` +<!-- AUTOGENERATED USAGE DESCRIPTIONS END --> ### Description diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js index 9db026f30..af008b7e1 100644 --- a/scripts/config-doc-command.js +++ b/scripts/config-doc-command.js @@ -1,21 +1,78 @@ const { definitions } = require('../lib/utils/config/index.js') +const usageFn = require('../lib/utils/usage.js') const { writeFileSync, readFileSync } = require('fs') const { resolve } = require('path') const configDoc = process.argv[2] const commandFile = process.argv[3] +const TAGS = { + CONFIG: { + START: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->', + END: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->', + }, + USAGE: { + START: '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->', + END: '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->', + }, +} + // Note: commands without params skip this whole process. -const { params } = require(resolve(commandFile)) +const { + params, + usage, +} = require(resolve(commandFile)) -const describeAll = () => - params.map(name => definitions[name].describe()).join( +const describeAll = (content) => + content.map(name => definitions[name].describe()).join( '\n\n<!-- automatically generated, do not edit manually -->\n' + '<!-- see lib/utils/config/definitions.js -->\n\n' ) -const addBetweenTags = (doc, startTag, endTag, body) => { +const describeUsage = ({ usage }) => { + const synopsis = [] + + // Grab the command name from the *.md filename + // NOTE: We cannot use the name property command file because in the case of + // `npx` the file being used is `lib/commands/exec.js` + const commandName = configDoc.split('/').pop().split('.')[0].replace('npm-', '') + synopsis.push('\n```bash') + + if (commandName) { + // special case for `npx`: + // `npx` is not technically a command in and of itself, + // so it just needs the usage and parameters of npm exec, and none of the aliases + if (commandName === 'npx') { + synopsis.push(usage.map(usageInfo => `npx ${usageInfo}`).join('\n')) + } else { + const baseCommand = `npm ${commandName}` + if (!usage) { + synopsis.push(baseCommand) + } else { + synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n')) + } + + const aliases = usageFn(commandName, '').trim() + if (aliases) { + synopsis.push(`\n${aliases}`) + } + } + } else { + console.error(`could not determine command name from ${commandFile}`) + } + + synopsis.push('```') + return synopsis.join('\n') +} + +const addBetweenTags = ( + doc, + startTag, + endTag, + body, + sourceFilepath = 'lib/utils/config/definitions.js') => { const startSplit = doc.split(startTag) + if (startSplit.length !== 2) { throw new Error('Did not find exactly one start tag') } @@ -29,27 +86,45 @@ const addBetweenTags = (doc, startTag, endTag, body) => { startSplit[0], startTag, '\n<!-- automatically generated, do not edit manually -->\n' + - '<!-- see lib/utils/config/definitions.js -->\n', + '<!-- see ' + sourceFilepath + ' -->\n', body, '\n\n<!-- automatically generated, do not edit manually -->\n' + - '<!-- see lib/utils/config/definitions.js -->', + '<!-- see ' + sourceFilepath + ' -->', '\n\n', endTag, endSplit[1], ].join('') } -const addDescriptions = doc => { - const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->' - const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->' - return addBetweenTags(doc, startTag, endTag, describeAll()) -} +const addDescriptions = doc => + addBetweenTags(doc, TAGS.CONFIG.START, TAGS.CONFIG.END, describeAll(params)) + +const addUsageDescriptions = doc => + addBetweenTags(doc, TAGS.USAGE.START, TAGS.USAGE.END, + describeUsage({ usage }), + commandFile + ) -// always write SOMETHING so that Make sees the file is up to date. -const doc = readFileSync(configDoc, 'utf8') -const hasTag = doc.includes('<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->') -const newDoc = params && hasTag ? addDescriptions(doc) : doc -if (params && !hasTag) { - console.error('WARNING: did not find config description section', configDoc) +try { + // always write SOMETHING so that Make sees the file is up to date. + const doc = readFileSync(configDoc, 'utf8') + const hasTag = doc.includes(TAGS.CONFIG.START) + const hasUsageTag = doc.includes(TAGS.USAGE.START) + + if (params && params.length) { + let newDoc = hasTag ? addDescriptions(doc) : doc + newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc + + if (!hasTag) { + console.error('WARNING: did not find config description section', configDoc) + } + + if ((usage && usage.length) && !hasUsageTag) { + console.error('WARNING: did not find usage description section', configDoc) + } + writeFileSync(configDoc, newDoc) + } +} catch (err) { + console.error(`WARNING: file cannot be open: ${configDoc}`) + console.error(err) } -writeFileSync(configDoc, newDoc) |