diff options
51 files changed, 320 insertions, 268 deletions
diff --git a/docs/content/commands/npm-cache.md b/docs/content/commands/npm-cache.md index 091e26e8a..b5eddd46c 100644 --- a/docs/content/commands/npm-cache.md +++ b/docs/content/commands/npm-cache.md @@ -11,11 +11,7 @@ description: Manipulates packages cache <!-- 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 add <package-spec> npm cache clean [<key>] npm cache ls [<name>@<version>] npm cache verify @@ -101,6 +97,7 @@ cache`](/commands/npm-cache) ### See Also +* [package spec](/using-npm/package-spec) * [npm folders](/configuring-npm/folders) * [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md index 3374bf1e2..9b8238d05 100644 --- a/docs/content/commands/npm-ci.md +++ b/docs/content/commands/npm-ci.md @@ -133,7 +133,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- 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 4345120d3..20f65140f 100644 --- a/docs/content/commands/npm-deprecate.md +++ b/docs/content/commands/npm-deprecate.md @@ -11,7 +11,7 @@ description: Deprecate a version of a package <!-- see lib/commands/deprecate.js --> ```bash -npm deprecate <pkg>[@<version>] <message> +npm deprecate <package-spec> <message> ``` <!-- automatically generated, do not edit manually --> @@ -45,8 +45,8 @@ In this case, a version `my-thing@1.0.0-beta.0` will also be deprecated. You must be the package owner to deprecate something. See the `owner` and `adduser` help topics. -To un-deprecate a package, specify an empty string (`""`) for the `message` -argument. Note that you must use double quotes with no space between them to +To un-deprecate a package, specify an empty string (`""`) for the `message` +argument. Note that you must use double quotes with no space between them to format an empty string. ### Configuration @@ -82,6 +82,7 @@ password, npm will prompt on the command line for one. ### See Also +* [package spec](/using-npm/package-spec) * [npm publish](/commands/npm-publish) * [npm registry](/using-npm/registry) * [npm owner](/commands/npm-owner) diff --git a/docs/content/commands/npm-dist-tag.md b/docs/content/commands/npm-dist-tag.md index b9caf1fbe..123e67dbf 100644 --- a/docs/content/commands/npm-dist-tag.md +++ b/docs/content/commands/npm-dist-tag.md @@ -11,9 +11,9 @@ description: Modify package distribution tags <!-- 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>] +npm dist-tag add <package-spec (with version)> [<tag>] +npm dist-tag rm <package-spec> <tag> +npm dist-tag ls [<package-spec>] alias: dist-tags ``` @@ -27,11 +27,11 @@ alias: dist-tags Add, remove, and enumerate distribution tags on a package: -* add: Tags the specified version of the package with the specified tag, or - the `--tag` config if not specified. If you have two-factor - authentication on auth-and-writes then you’ll need to include a one-time - password on the command line with `--otp <one-time password>`, or at the - OTP prompt. +* add: Tags the specified version of the package with the specified tag, + or the `--tag` config if not specified. If you have two-factor + authentication on auth-and-writes then you’ll need to include a + one-time password on the command line with + `--otp <one-time password>`, or at the OTP prompt. * rm: Clear a tag that is no longer in use from the package. If you have two-factor authentication on auth-and-writes then you’ll need to include @@ -168,6 +168,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [npm publish](/commands/npm-publish) * [npm install](/commands/npm-install) * [npm dedupe](/commands/npm-dedupe) diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md index 765221056..5ba2fe820 100644 --- a/docs/content/commands/npm-explain.md +++ b/docs/content/commands/npm-explain.md @@ -11,7 +11,7 @@ description: Explain installed packages <!-- see lib/commands/explain.js --> ```bash -npm explain <folder | specifier> +npm explain <package-spec> alias: why ``` @@ -26,9 +26,10 @@ alias: why This command will print the chain of dependencies causing a given package to be installed in the current project. -Positional arguments can be either folders within `node_modules`, or -`name@version-range` specifiers, which will select the dependency -relationships to explain. +If one or more package specs are provided, then only packages matching +one of the specifiers will have their relationships explained. + +The package spec can also refer to a folder within `./node_modules` For example, running `npm explain glob` within npm's source tree will show: @@ -110,6 +111,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) * [npm folders](/configuring-npm/folders) diff --git a/docs/content/commands/npm-fund.md b/docs/content/commands/npm-fund.md index 5b96e91ab..8db0ce910 100644 --- a/docs/content/commands/npm-fund.md +++ b/docs/content/commands/npm-fund.md @@ -11,7 +11,7 @@ description: Retrieve funding information <!-- see lib/commands/fund.js --> ```bash -npm fund [[<@scope>/]<pkg>] +npm fund [<package-spec>] ``` <!-- automatically generated, do not edit manually --> @@ -23,22 +23,22 @@ npm fund [[<@scope>/]<pkg>] This command retrieves information on how to fund the dependencies of a given project. If no package name is provided, it will list all -dependencies that are looking for funding in a tree structure, listing the -type of funding and the url to visit. If a package name is provided then it -tries to open its funding url using the `--browser` config param; if there -are multiple funding sources for the package, the user will be instructed -to pass the `--which` option to disambiguate. +dependencies that are looking for funding in a tree structure, listing +the type of funding and the url to visit. If a package name is provided +then it tries to open its funding url using the `--browser` config +param; if there are multiple funding sources for the package, the user +will be instructed to pass the `--which` option to disambiguate. The list will avoid duplicated entries and will stack all packages that -share the same url as a single entry. Thus, the list does not have the same -shape of the output from `npm ls`. +share the same url as a single entry. Thus, the list does not have the +same shape of the output from `npm ls`. #### Example ### Workspaces support -It's possible to filter the results to only include a single workspace and its -dependencies using the `workspace` config option. +It's possible to filter the results to only include a single workspace +and its dependencies using the `workspace` config option. #### Example: @@ -58,8 +58,8 @@ test-workspaces-fund@1.0.0 `-- bar@2.0.0 ``` -And here is an example of the expected result when filtering only by -a specific workspace `a` in the same project: +And here is an example of the expected result when filtering only by a +specific workspace `a` in the same project: ```bash $ npm fund -w a @@ -156,6 +156,7 @@ If there are multiple funding sources, which 1-indexed source URL to open. ## See Also +* [package spec](/using-npm/package-spec) * [npm install](/commands/npm-install) * [npm docs](/commands/npm-docs) * [npm ls](/commands/npm-ls) diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md index 35343cceb..cd0be4643 100644 --- a/docs/content/commands/npm-init.md +++ b/docs/content/commands/npm-init.md @@ -11,9 +11,8 @@ description: Create a package.json file <!-- see lib/commands/init.js --> ```bash -npm init [--force|-f|--yes|-y|--scope] +npm init <package-spec> (same as `npx <package-spec>) npm init <@scope> (same as `npx <@scope>/create`) -npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`) aliases: create, innit ``` @@ -207,6 +206,39 @@ recommended that you do not use this option! <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> +#### `scope` + +* Default: the scope of the current project, if any, or "" +* Type: String + +Associate an operation with a scope for a scoped registry. + +Useful when logging in to or out of a private registry: + +``` +# log in, linking the scope to the custom registry +npm login --scope=@mycorp --registry=https://registry.mycorp.com + +# log out, removing the link and the auth token +npm logout --scope=@mycorp +``` + +This will cause `@mycorp` to be mapped to the registry for future +installation of packages specified according to the pattern +`@mycorp/package`. + +This will also cause `npm init` to create a scoped package. + +``` +# accept all defaults, and create a package named "@foo/whatever", +# instead of just named "whatever" +npm init --scope=@foo --yes +``` + + +<!-- automatically generated, do not edit manually --> +<!-- see lib/utils/config/definitions.js --> + #### `workspace` * Default: @@ -284,6 +316,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [init-package-json module](http://npm.im/init-package-json) * [package.json](/configuring-npm/package-json) * [npm version](/commands/npm-version) diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md index 0d9470acf..74ed4667e 100644 --- a/docs/content/commands/npm-install-ci-test.md +++ b/docs/content/commands/npm-install-ci-test.md @@ -79,7 +79,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md index 3dd860ea5..d27686e73 100644 --- a/docs/content/commands/npm-install-test.md +++ b/docs/content/commands/npm-install-test.md @@ -11,16 +11,7 @@ description: Install package(s) and run tests <!-- see lib/commands/install-test.js --> ```bash -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 <git:// url> -npm install-test <github username>/<github project> +npm install-test [<package-spec> ...] alias: it ``` diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md index 445772f03..f05e53266 100644 --- a/docs/content/commands/npm-install.md +++ b/docs/content/commands/npm-install.md @@ -11,16 +11,7 @@ description: Install a package <!-- see lib/commands/install.js --> ```bash -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 <folder> -npm install <tarball file> -npm install <tarball url> -npm install <git:// url> -npm install <github username>/<github project> +npm install [<package-spec> ...] aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall ``` diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md index 975c807c3..8c1b42249 100644 --- a/docs/content/commands/npm-link.md +++ b/docs/content/commands/npm-link.md @@ -11,8 +11,7 @@ description: Symlink a package folder <!-- see lib/commands/link.js --> ```bash -npm link (in package dir) -npm link [<@scope>/]<pkg>[@<version>] +npm link [<package-spec>] alias: ln ``` @@ -29,11 +28,11 @@ test iteratively without having to continually rebuild. Package linking is a two-step process. -First, `npm link` in a package folder will create a symlink in the global -folder `{prefix}/lib/node_modules/<package>` that links to the package -where the `npm link` command was executed. It will also link any bins in -the package to `{prefix}/bin/{name}`. Note that `npm link` uses the global -prefix (see `npm prefix -g` for its value). +First, `npm link` in a package folder with no arguments will create a +symlink in the global folder `{prefix}/lib/node_modules/<package>` that +links to the package where the `npm link` command was executed. It will +also link any bins in the package to `{prefix}/bin/{name}`. Note that +`npm link` uses the global prefix (see `npm prefix -g` for its value). Next, in some other location, `npm link package-name` will create a symbolic link from globally-installed `package-name` to `node_modules/` of @@ -399,6 +398,7 @@ symlink. This option has no effect on workspaces. ### See Also +* [package spec](/using-npm/package-spec) * [npm developers](/using-npm/developers) * [package.json](/configuring-npm/package-json) * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md index ded8c0c0d..a97c5168e 100644 --- a/docs/content/commands/npm-ls.md +++ b/docs/content/commands/npm-ls.md @@ -11,7 +11,7 @@ description: List installed packages <!-- see lib/commands/ls.js --> ```bash -npm ls [[<@scope>/]<pkg> ...] +npm ls <package-spec> alias: list ``` @@ -301,6 +301,7 @@ symlink. This option has no effect on workspaces. ### See Also +* [package spec](/using-npm/package-spec) * [npm explain](/commands/npm-explain) * [npm config](/commands/npm-config) * [npmrc](/configuring-npm/npmrc) diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md index 6fa026550..c4e07a0cd 100644 --- a/docs/content/commands/npm-outdated.md +++ b/docs/content/commands/npm-outdated.md @@ -11,7 +11,7 @@ description: Check for outdated packages <!-- see lib/commands/outdated.js --> ```bash -npm outdated [[<@scope>/]<pkg> ...] +npm outdated [<package-spec> ...] ``` <!-- automatically generated, do not edit manually --> @@ -192,6 +192,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [npm update](/commands/npm-update) * [npm dist-tag](/commands/npm-dist-tag) * [npm registry](/using-npm/registry) diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md index 72dfe6a22..ebc29ef69 100644 --- a/docs/content/commands/npm-owner.md +++ b/docs/content/commands/npm-owner.md @@ -11,9 +11,9 @@ description: Manage package owners <!-- see lib/commands/owner.js --> ```bash -npm owner add <user> [<@scope>/]<pkg> -npm owner rm <user> [<@scope>/]<pkg> -npm owner ls [<@scope>/]<pkg> +npm owner add <user> <package-spec> +npm owner rm <user> <package-spec> +npm owner ls <package-spec> alias: author ``` @@ -123,6 +123,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [npm profile](/commands/npm-profile) * [npm publish](/commands/npm-publish) * [npm registry](/using-npm/registry) diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md index fa6c005e9..7921042ea 100644 --- a/docs/content/commands/npm-pack.md +++ b/docs/content/commands/npm-pack.md @@ -11,7 +11,7 @@ description: Create a tarball from a package <!-- see lib/commands/pack.js --> ```bash -npm pack [[<@scope>/]<pkg>...] +npm pack <package-spec> ``` <!-- automatically generated, do not edit manually --> @@ -144,6 +144,7 @@ If no arguments are supplied, then npm packs the current package folder. ### See Also +* [package spec](/using-npm/package-spec) * [npm-packlist package](http://npm.im/npm-packlist) * [npm cache](/commands/npm-cache) * [npm publish](/commands/npm-publish) diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md index 2995f6bc8..536d04988 100644 --- a/docs/content/commands/npm-publish.md +++ b/docs/content/commands/npm-publish.md @@ -11,7 +11,7 @@ description: Publish a package <!-- see lib/commands/publish.js --> ```bash -npm publish [<folder>] +npm publish <package-spec> ``` <!-- automatically generated, do not edit manually --> @@ -23,42 +23,26 @@ npm publish [<folder>] Publishes a package to the registry so that it can be installed by name. -By default npm will publish to the public registry. This can be overridden -by specifying a different default registry or using a -[`scope`](/using-npm/scope) in the name (see +By default npm will publish to the public registry. This can be +overridden by specifying a different default registry or using a +[`scope`](/using-npm/scope) in the name, combined with a +scope-configured registry (see [`package.json`](/configuring-npm/package-json)). -* `<folder>`: A folder containing a package.json file -* `<tarball>`: A url or file path to a gzipped tar archive containing a - single folder with a package.json file inside. +A `package` is interpreted the same way as other commands (like +`npm install` and can be: -* `[--tag <tag>]`: Registers the published package with the given tag, such - that `npm install <name>@<tag>` will install this version. By default, - `npm publish` updates and `npm install` installs the `latest` tag. See - [`npm-dist-tag`](npm-dist-tag) for details about tags. - -* `[--access <public|restricted>]`: Tells the registry whether this package - should be published as public or restricted. Only applies to scoped - packages, which default to `restricted`. If you don't have a paid - account, you must publish with `--access public` to publish scoped - packages. - -* `[--otp <otpcode>]`: If you have two-factor authentication enabled in - `auth-and-writes` mode then you can provide a code from your - authenticator with this. If you don't include this and you're running - from a TTY then you'll be prompted. - -* `[--dry-run]`: As of `npm@6`, does everything publish would do except - actually publishing to the registry. Reports the details of what would - have been published. - -* `[--workspaces]`: Enables workspace context while publishing. All - workspace packages will be published. - -* `[--workspace]`: Enables workspaces context and limits results to only - those specified by this config item. Only the packages in the - workspaces given will be published. +* a) a folder containing a program described by a + [`package.json`](/configuring-npm/package-json) file +* b) a gzipped tarball containing (a) +* c) a url that resolves to (b) +* d) a `<name>@<version>` that is published on the registry (see + [`registry`](/using-npm/registry)) with (c) +* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that + points to (d) +* f) a `<name>` that has a "latest" tag satisfying (e) +* g) a `<git remote url>` that resolves to (a) The publish will fail if the package name and version combination already exists in the specified registry. @@ -247,6 +231,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [npm-packlist package](http://npm.im/npm-packlist) * [npm registry](/using-npm/registry) * [npm scope](/using-npm/scope) diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md index 52c368c8c..6a3964212 100644 --- a/docs/content/commands/npm-rebuild.md +++ b/docs/content/commands/npm-rebuild.md @@ -11,7 +11,7 @@ description: Rebuild a package <!-- see lib/commands/rebuild.js --> ```bash -npm rebuild [[<@scope>/]<name>[@<version>] ...] +npm rebuild [<package-spec>] ...] alias: rb ``` @@ -29,9 +29,8 @@ C++ addons with the new binary. It is also useful when installing with `--ignore-scripts` and `--no-bin-links`, to explicitly choose which packages to build and/or link bins. -If one or more package names (and optionally version ranges) are provided, -then only packages with a name and version matching one of the specifiers -will be rebuilt. +If one or more package specs are provided, then only packages with a +name and version matching one of the specifiers will be rebuilt. ### Configuration @@ -178,4 +177,5 @@ symlink. This option has no effect on workspaces. ### See Also +* [package spec](/using-npm/package-spec) * [npm install](/commands/npm-install) diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md index f01cd014e..048bebb16 100644 --- a/docs/content/commands/npm-restart.md +++ b/docs/content/commands/npm-restart.md @@ -69,7 +69,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md index 73c4b1c7a..d94040f1a 100644 --- a/docs/content/commands/npm-run-script.md +++ b/docs/content/commands/npm-run-script.md @@ -246,7 +246,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-star.md b/docs/content/commands/npm-star.md index 00ef17a81..3e81c6a55 100644 --- a/docs/content/commands/npm-star.md +++ b/docs/content/commands/npm-star.md @@ -11,7 +11,7 @@ description: Mark your favorite packages <!-- see lib/commands/star.js --> ```bash -npm star [<pkg>...] +npm star [<package-spec>...] ``` <!-- automatically generated, do not edit manually --> @@ -87,6 +87,7 @@ password, npm will prompt on the command line for one. ### See Also +* [package spec](/using-npm/package-spec) * [npm unstar](/commands/npm-unstar) * [npm stars](/commands/npm-stars) * [npm view](/commands/npm-view) diff --git a/docs/content/commands/npm-start.md b/docs/content/commands/npm-start.md index 8dd874b3c..148f92606 100644 --- a/docs/content/commands/npm-start.md +++ b/docs/content/commands/npm-start.md @@ -80,7 +80,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-stop.md b/docs/content/commands/npm-stop.md index 9a3a55cf3..a3084e843 100644 --- a/docs/content/commands/npm-stop.md +++ b/docs/content/commands/npm-stop.md @@ -73,7 +73,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-test.md b/docs/content/commands/npm-test.md index 8a343ab29..72bb899d0 100644 --- a/docs/content/commands/npm-test.md +++ b/docs/content/commands/npm-test.md @@ -70,7 +70,7 @@ will *not* run any pre- or post-scripts. * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/commands/npm-unpublish.md b/docs/content/commands/npm-unpublish.md index a4c481ea5..9ad99e72a 100644 --- a/docs/content/commands/npm-unpublish.md +++ b/docs/content/commands/npm-unpublish.md @@ -11,7 +11,7 @@ description: Remove a package from the registry <!-- see lib/commands/unpublish.js --> ```bash -npm unpublish [<@scope>/]<pkg>[@<version>] +npm unpublish [<package-spec>] ``` <!-- automatically generated, do not edit manually --> @@ -146,6 +146,7 @@ This value is not exported to the environment for child processes. ### See Also +* [package spec](/using-npm/package-spec) * [npm deprecate](/commands/npm-deprecate) * [npm publish](/commands/npm-publish) * [npm registry](/using-npm/registry) diff --git a/docs/content/commands/npm-unstar.md b/docs/content/commands/npm-unstar.md index 76202190d..636e1b6ac 100644 --- a/docs/content/commands/npm-unstar.md +++ b/docs/content/commands/npm-unstar.md @@ -11,7 +11,7 @@ description: Remove an item from your favorite packages <!-- see lib/commands/unstar.js --> ```bash -npm unstar [<pkg>...] +npm unstar [<package-spec>...] ``` <!-- automatically generated, do not edit manually --> diff --git a/docs/content/commands/npm-view.md b/docs/content/commands/npm-view.md index 0ef17d8ad..d9d1daac0 100644 --- a/docs/content/commands/npm-view.md +++ b/docs/content/commands/npm-view.md @@ -11,7 +11,7 @@ description: View registry info <!-- see lib/commands/view.js --> ```bash -npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...] +npm view [<package-spec>] [<field>[.subfield]...] aliases: info, show, v ``` @@ -203,6 +203,7 @@ the field name. ### See Also +* [package spec](/using-npm/package-spec) * [npm search](/commands/npm-search) * [npm registry](/using-npm/registry) * [npm config](/commands/npm-config) diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md index 6ef854eb6..3fb431402 100644 --- a/docs/content/using-npm/config.md +++ b/docs/content/using-npm/config.md @@ -1518,7 +1518,7 @@ npm init --scope=@foo --yes * Type: null or String The shell to use for scripts run with the `npm exec`, `npm run` and `npm -init <pkg>` commands. +init <package-spec>` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> diff --git a/docs/content/using-npm/package-spec.md b/docs/content/using-npm/package-spec.md new file mode 100644 index 000000000..0d3741018 --- /dev/null +++ b/docs/content/using-npm/package-spec.md @@ -0,0 +1,106 @@ +--- +title: package-spec +section: 7 +description: Package name specifier +--- + + +### Description + +Commands like `npm install` and the dependency sections in the +`package.json` use a package name specifier. This can be many different +things that all refer to a "package". Examples include a package name, +git url, tarball, or local directory. These will generally be referred +to as `<package-spec>` in the help output for the npm commands that use +this package name specifier. + +### Package name + +* `[<@scope>/]<pkg>` +* `[<@scope>/]<pkg>@<tag>` +* `[<@scope>/]<pkg>@<version>` +* `[<@scope>/]<pkg>@<version range>` + +Refers to a package by name, with or without a scope, and optionally +tag, version, or version range. This is typically used in combination +with the [registry](/using-npm/config#registry) config to refer to a +package in a registry. + +Examples: +* `npm` +* `@npmcli/arborist` +* `@npmcli/arborist@latest` +* `npm@6.13.1` +* `npm@^4.0.0` + +### Aliases + +* `<alias>@npm:<name>` + +Primarily used by commands like `npm install` and in the dependency +sections in the `package.json`, this refers to a package by an alias. +The `<alias>` is the name of the package as it is reified in the +`node_modules` folder, and the `<name>` refers to a package name as +found in the configured registry. + +See `Package name` above for more info on referring to a package by +name, and [registry](/using-npm/config#registry) for configuring which +registry is used when referring to a package by name. + +Examples: +* `semver:@npm:@npmcli/semver-with-patch` +* `semver:@npm:semver@7.2.2` +* `semver:@npm:semver@legacy` + +### Folders + +* `<folder>` + +This refers to a package on the local filesystem. Specifically this is +a folder with a `package.json` file in it. This *should* always be +prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion. +npm currently will parse a string with more than one `/` in it as a +folder, but this is legacy behavior that may be removed in a future +version. + +Examples: + +* `./my-package` +* `/opt/npm/my-package` + +### Tarballs + +* `<tarball file>` +* `<tarball url>` + +Examples: + +* `./my-package.tgz` +* `https://registry.npmjs.org/semver/-/semver-1.0.0.tgz` + +Refers to a package in a tarball format, either on the local filesystem +or remotely via url. This is the format that packages exist in when +uploaded to a registry. + +### git urls + +* `<git:// url>` +* `<github username>/<github project>` + +Refers to a package in a git repo. This can be a full git url, git +shorthand, or a username/package on GitHub. You can specify a +git tag, branch, or other git ref by appending `#ref`. + +Examples: + +* `https://github.com/npm/cli.git` +* `git@github.com:npm/cli.git` +* `git+ssh://git@github.com/npm/cli#v6.0.0` +* `github:npm/cli#HEAD` +* `npm/cli#c12ea07` + +### See also + +[npm-package-arg](https://npm.im/npm-package-arg) +[scope](/using-npm/scope) +[config](/using-npm/config) diff --git a/docs/nav.yml b/docs/nav.yml index a82847fc3..bc39b969e 100644 --- a/docs/nav.yml +++ b/docs/nav.yml @@ -232,6 +232,9 @@ - title: Registry url: /using-npm/registry description: The JavaScript Package Registry + - title: Package spec + url: /using-npm/package-spec + description: Package name specifier - title: Config url: /using-npm/config description: About npm configuration diff --git a/lib/commands/cache.js b/lib/commands/cache.js index 862f346ad..bc52889c0 100644 --- a/lib/commands/cache.js +++ b/lib/commands/cache.js @@ -68,11 +68,7 @@ class Cache extends BaseCommand { static name = 'cache' static params = ['cache'] static usage = [ - 'add <tarball file>', - 'add <folder>', - 'add <tarball url>', - 'add <git url>', - 'add <name>@<version>', + 'add <package-spec>', 'clean [<key>]', 'ls [<name>@<version>]', 'verify', diff --git a/lib/commands/deprecate.js b/lib/commands/deprecate.js index 0ae88f192..862c214db 100644 --- a/lib/commands/deprecate.js +++ b/lib/commands/deprecate.js @@ -9,7 +9,7 @@ const BaseCommand = require('../base-command.js') class Deprecate extends BaseCommand { static description = 'Deprecate a version of a package' static name = 'deprecate' - static usage = ['<pkg>[@<version>] <message>'] + static usage = ['<package-spec> <message>'] static params = [ 'registry', 'otp', diff --git a/lib/commands/dist-tag.js b/lib/commands/dist-tag.js index a207e422c..e74a3f1d4 100644 --- a/lib/commands/dist-tag.js +++ b/lib/commands/dist-tag.js @@ -12,9 +12,9 @@ class DistTag extends BaseCommand { static params = ['workspace', 'workspaces', 'include-workspace-root'] static name = 'dist-tag' static usage = [ - 'add <pkg>@<version> [<tag>]', - 'rm <pkg> <tag>', - 'ls [<pkg>]', + 'add <package-spec (with version)> [<tag>]', + 'rm <package-spec> <tag>', + 'ls [<package-spec>]', ] static ignoreImplicitWorkspace = false @@ -90,7 +90,7 @@ class DistTag extends BaseCommand { log.verbose('dist-tag add', defaultTag, 'to', spec.name + '@' + version) if (!spec.name || !version || !defaultTag) { - throw this.usageError() + throw this.usageError('must provide a spec with a name and version, and a tag to add') } const t = defaultTag.trim() diff --git a/lib/commands/explain.js b/lib/commands/explain.js index ca6ee7540..c0ef04548 100644 --- a/lib/commands/explain.js +++ b/lib/commands/explain.js @@ -10,7 +10,7 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js') class Explain extends ArboristWorkspaceCmd { static description = 'Explain installed packages' static name = 'explain' - static usage = ['<folder | specifier>'] + static usage = ['<package-spec>'] static params = [ 'json', 'workspace', diff --git a/lib/commands/fund.js b/lib/commands/fund.js index 09ca81653..9690cbc32 100644 --- a/lib/commands/fund.js +++ b/lib/commands/fund.js @@ -20,7 +20,7 @@ class Fund extends ArboristWorkspaceCmd { static description = 'Retrieve funding information' static name = 'fund' static params = ['json', 'browser', 'unicode', 'workspace', 'which'] - static usage = ['[[<@scope>/]<pkg>]'] + static usage = ['[<package-spec>]'] // TODO /* istanbul ignore next */ diff --git a/lib/commands/init.js b/lib/commands/init.js index 4c299e651..b8b6bd5d5 100644 --- a/lib/commands/init.js +++ b/lib/commands/init.js @@ -18,6 +18,7 @@ class Init extends BaseCommand { static params = [ 'yes', 'force', + 'scope', 'workspace', 'workspaces', 'workspaces-update', @@ -26,9 +27,8 @@ class Init extends BaseCommand { static name = 'init' static usage = [ - '[--force|-f|--yes|-y|--scope]', + '<package-spec> (same as `npx <package-spec>)', '<@scope> (same as `npx <@scope>/create`)', - '[<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)', ] static ignoreImplicitWorkspace = false diff --git a/lib/commands/install.js b/lib/commands/install.js index 4cda36448..ecc0727a2 100644 --- a/lib/commands/install.js +++ b/lib/commands/install.js @@ -34,18 +34,7 @@ class Install extends ArboristWorkspaceCmd { ...super.params, ] - static usage = [ - '[<@scope>/]<pkg>', - '[<@scope>/]<pkg>@<tag>', - '[<@scope>/]<pkg>@<version>', - '[<@scope>/]<pkg>@<version range>', - '<alias>@npm:<name>', - '<folder>', - '<tarball file>', - '<tarball url>', - '<git:// url>', - '<github username>/<github project>', - ] + static usage = ['[<package-spec> ...]'] async completion (opts) { const { partialWord } = opts diff --git a/lib/commands/link.js b/lib/commands/link.js index 80a60d36e..b0b889ea7 100644 --- a/lib/commands/link.js +++ b/lib/commands/link.js @@ -15,8 +15,7 @@ class Link extends ArboristWorkspaceCmd { static description = 'Symlink a package folder' static name = 'link' static usage = [ - '(in package dir)', - '[<@scope>/]<pkg>[@<version>]', + '[<package-spec>]', ] static params = [ diff --git a/lib/commands/ls.js b/lib/commands/ls.js index cfd9cb5a5..d3932072b 100644 --- a/lib/commands/ls.js +++ b/lib/commands/ls.js @@ -27,7 +27,7 @@ const localeCompare = require('@isaacs/string-locale-compare')('en') class LS extends ArboristWorkspaceCmd { static description = 'List installed packages' static name = 'ls' - static usage = ['[[<@scope>/]<pkg> ...]'] + static usage = ['<package-spec>'] static params = [ 'all', 'json', diff --git a/lib/commands/outdated.js b/lib/commands/outdated.js index 081e75a2c..042b776f7 100644 --- a/lib/commands/outdated.js +++ b/lib/commands/outdated.js @@ -15,7 +15,7 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js') class Outdated extends ArboristWorkspaceCmd { static description = 'Check for outdated packages' static name = 'outdated' - static usage = ['[[<@scope>/]<pkg> ...]'] + static usage = ['[<package-spec> ...]'] static params = [ 'all', 'json', diff --git a/lib/commands/owner.js b/lib/commands/owner.js index 4797e9c7e..732bb40a3 100644 --- a/lib/commands/owner.js +++ b/lib/commands/owner.js @@ -27,9 +27,9 @@ class Owner extends BaseCommand { ] static usage = [ - 'add <user> [<@scope>/]<pkg>', - 'rm <user> [<@scope>/]<pkg>', - 'ls [<@scope>/]<pkg>', + 'add <user> <package-spec>', + 'rm <user> <package-spec>', + 'ls <package-spec>', ] static ignoreImplicitWorkspace = false diff --git a/lib/commands/pack.js b/lib/commands/pack.js index 8190ceeca..c6a748046 100644 --- a/lib/commands/pack.js +++ b/lib/commands/pack.js @@ -17,7 +17,7 @@ class Pack extends BaseCommand { 'include-workspace-root', ] - static usage = ['[[<@scope>/]<pkg>...]'] + static usage = ['<package-spec>'] static ignoreImplicitWorkspace = false async exec (args) { diff --git a/lib/commands/publish.js b/lib/commands/publish.js index da6437fa9..579f5d6e7 100644 --- a/lib/commands/publish.js +++ b/lib/commands/publish.js @@ -37,7 +37,7 @@ class Publish extends BaseCommand { 'include-workspace-root', ] - static usage = ['[<folder>]'] + static usage = ['<package-spec>'] static ignoreImplicitWorkspace = false async exec (args) { diff --git a/lib/commands/rebuild.js b/lib/commands/rebuild.js index 3e6046d8d..d06313ce4 100644 --- a/lib/commands/rebuild.js +++ b/lib/commands/rebuild.js @@ -16,7 +16,7 @@ class Rebuild extends ArboristWorkspaceCmd { ...super.params, ] - static usage = ['[[<@scope>/]<name>[@<version>] ...]'] + static usage = ['[<package-spec>] ...]'] // TODO /* istanbul ignore next */ diff --git a/lib/commands/star.js b/lib/commands/star.js index 7b76be3c1..20039bf89 100644 --- a/lib/commands/star.js +++ b/lib/commands/star.js @@ -7,7 +7,7 @@ const BaseCommand = require('../base-command.js') class Star extends BaseCommand { static description = 'Mark your favorite packages' static name = 'star' - static usage = ['[<pkg>...]'] + static usage = ['[<package-spec>...]'] static params = [ 'registry', 'unicode', diff --git a/lib/commands/unpublish.js b/lib/commands/unpublish.js index f27be2e41..ab929d98c 100644 --- a/lib/commands/unpublish.js +++ b/lib/commands/unpublish.js @@ -20,7 +20,7 @@ class Unpublish extends BaseCommand { static description = 'Remove a package from the registry' static name = 'unpublish' static params = ['dry-run', 'force', 'workspace', 'workspaces'] - static usage = ['[<@scope>/]<pkg>[@<version>]'] + static usage = ['[<package-spec>]'] static ignoreImplicitWorkspace = false async getKeysOfVersions (name, opts) { diff --git a/lib/commands/view.js b/lib/commands/view.js index efb298a03..db5d99b68 100644 --- a/lib/commands/view.js +++ b/lib/commands/view.js @@ -33,7 +33,7 @@ class View extends BaseCommand { static ignoreImplicitWorkspace = false - static usage = ['[<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]'] + static usage = ['[<package-spec>] [<field>[.subfield]...]'] async completion (opts) { if (opts.conf.argv.remain.length <= 2) { diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js index 4c77e375c..6b35e7d4d 100644 --- a/lib/utils/config/definitions.js +++ b/lib/utils/config/definitions.js @@ -535,7 +535,7 @@ define('dev', { define('diff', { default: [], - hint: '<pkg-name|spec|version>', + hint: '<package-spec>', type: [String, Array], description: ` Define arguments to compare in \`npm diff\`. @@ -1458,7 +1458,7 @@ define('otp', { define('package', { default: [], - hint: '<pkg>[@<version>]', + hint: '<package-spec>', type: [String, Array], description: ` The package to install for [\`npm exec\`](/commands/npm-exec) @@ -1867,7 +1867,7 @@ define('script-shell', { type: [null, String], description: ` The shell to use for scripts run with the \`npm exec\`, - \`npm run\` and \`npm init <pkg>\` commands. + \`npm run\` and \`npm init <package-spec>\` commands. `, flatten (key, obj, flatOptions) { flatOptions.scriptShell = obj[key] || undefined 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 802fa8de9..13a3b06fe 100644 --- a/tap-snapshots/test/lib/load-all-commands.js.test.cjs +++ b/tap-snapshots/test/lib/load-all-commands.js.test.cjs @@ -98,11 +98,7 @@ exports[`test/lib/load-all-commands.js TAP load each command cache > must match Manipulates packages cache Usage: -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 add <package-spec> npm cache clean [<key>] npm cache ls [<name>@<version>] npm cache verify @@ -178,7 +174,7 @@ exports[`test/lib/load-all-commands.js TAP load each command deprecate > must ma Deprecate a version of a package Usage: -npm deprecate <pkg>[@<version>] <message> +npm deprecate <package-spec> <message> Options: [--registry <registry>] [--otp <otp>] @@ -193,10 +189,10 @@ Usage: npm diff [...<paths>] Options: -[--diff <pkg-name|spec|version> [--diff <pkg-name|spec|version> ...]] -[--diff-name-only] [--diff-unified <number>] [--diff-ignore-all-space] -[--diff-no-prefix] [--diff-src-prefix <path>] [--diff-dst-prefix <path>] -[--diff-text] [-g|--global] [--tag <tag>] +[--diff <package-spec> [--diff <package-spec> ...]] [--diff-name-only] +[--diff-unified <number>] [--diff-ignore-all-space] [--diff-no-prefix] +[--diff-src-prefix <path>] [--diff-dst-prefix <path>] [--diff-text] [-g|--global] +[--tag <tag>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] [--include-workspace-root] @@ -207,9 +203,9 @@ exports[`test/lib/load-all-commands.js TAP load each command dist-tag > must mat Modify package distribution tags Usage: -npm dist-tag add <pkg>@<version> [<tag>] -npm dist-tag rm <pkg> <tag> -npm dist-tag ls [<pkg>] +npm dist-tag add <package-spec (with version)> [<tag>] +npm dist-tag rm <package-spec> <tag> +npm dist-tag ls [<package-spec>] Options: [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] @@ -270,8 +266,7 @@ npm exec -c '<cmd> [args...]' npm exec --package=foo -c '<cmd> [args...]' Options: -[--package <pkg>[@<version>] [--package <pkg>[@<version>] ...]] -[-c|--call <call>] +[--package <package-spec> [--package <package-spec> ...]] [-c|--call <call>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] [--include-workspace-root] @@ -284,7 +279,7 @@ exports[`test/lib/load-all-commands.js TAP load each command explain > must matc Explain installed packages Usage: -npm explain <folder | specifier> +npm explain <package-spec> Options: [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] @@ -326,7 +321,7 @@ exports[`test/lib/load-all-commands.js TAP load each command fund > must match s Retrieve funding information Usage: -npm fund [[<@scope>/]<pkg>] +npm fund [<package-spec>] Options: [--json] [--no-browser|--browser <browser>] [--unicode] @@ -390,12 +385,11 @@ exports[`test/lib/load-all-commands.js TAP load each command init > must match s Create a package.json file Usage: -npm init [--force|-f|--yes|-y|--scope] +npm init <package-spec> (same as \`npx <package-spec>) npm init <@scope> (same as \`npx <@scope>/create\`) -npm init [<@scope>/]<name> (same as \`npx [<@scope>/]create-<name>\`) Options: -[-y|--yes] [-f|--force] +[-y|--yes] [-f|--force] [--scope <@scope>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] [--no-workspaces-update] [--include-workspace-root] @@ -408,16 +402,7 @@ exports[`test/lib/load-all-commands.js TAP load each command install > must matc Install a package Usage: -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 <folder> -npm install <tarball file> -npm install <tarball url> -npm install <git:// url> -npm install <github username>/<github project> +npm install [<package-spec> ...] Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] @@ -452,16 +437,7 @@ exports[`test/lib/load-all-commands.js TAP load each command install-test > must Install package(s) and run tests Usage: -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 <git:// url> -npm install-test <github username>/<github project> +npm install-test [<package-spec> ...] Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] @@ -481,8 +457,7 @@ exports[`test/lib/load-all-commands.js TAP load each command link > must match s Symlink a package folder Usage: -npm link (in package dir) -npm link [<@scope>/]<pkg>[@<version>] +npm link [<package-spec>] Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] @@ -547,7 +522,7 @@ exports[`test/lib/load-all-commands.js TAP load each command ls > must match sna List installed packages Usage: -npm ls [[<@scope>/]<pkg> ...] +npm ls <package-spec> Options: [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] [--depth <depth>] @@ -581,7 +556,7 @@ exports[`test/lib/load-all-commands.js TAP load each command outdated > must mat Check for outdated packages Usage: -npm outdated [[<@scope>/]<pkg> ...] +npm outdated [<package-spec> ...] Options: [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] @@ -594,9 +569,9 @@ exports[`test/lib/load-all-commands.js TAP load each command owner > must match Manage package owners Usage: -npm owner add <user> [<@scope>/]<pkg> -npm owner rm <user> [<@scope>/]<pkg> -npm owner ls [<@scope>/]<pkg> +npm owner add <user> <package-spec> +npm owner rm <user> <package-spec> +npm owner ls <package-spec> Options: [--registry <registry>] [--otp <otp>] @@ -612,7 +587,7 @@ exports[`test/lib/load-all-commands.js TAP load each command pack > must match s Create a tarball from a package Usage: -npm pack [[<@scope>/]<pkg>...] +npm pack <package-spec> Options: [--dry-run] [--json] [--pack-destination <pack-destination>] @@ -698,7 +673,7 @@ exports[`test/lib/load-all-commands.js TAP load each command publish > must matc Publish a package Usage: -npm publish [<folder>] +npm publish <package-spec> Options: [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>] @@ -712,7 +687,7 @@ exports[`test/lib/load-all-commands.js TAP load each command rebuild > must matc Rebuild a package Usage: -npm rebuild [[<@scope>/]<name>[@<version>] ...] +npm rebuild [<package-spec>] ...] Options: [-g|--global] [--no-bin-links] [--foreground-scripts] [--ignore-scripts] @@ -829,7 +804,7 @@ exports[`test/lib/load-all-commands.js TAP load each command star > must match s Mark your favorite packages Usage: -npm star [<pkg>...] +npm star [<package-spec>...] Options: [--registry <registry>] [--unicode] [--otp <otp>] @@ -938,7 +913,7 @@ exports[`test/lib/load-all-commands.js TAP load each command unpublish > must ma Remove a package from the registry Usage: -npm unpublish [<@scope>/]<pkg>[@<version>] +npm unpublish [<package-spec>] Options: [--dry-run] [-f|--force] @@ -952,7 +927,7 @@ exports[`test/lib/load-all-commands.js TAP load each command unstar > must match Remove an item from your favorite packages Usage: -npm unstar [<pkg>...] +npm unstar [<package-spec>...] Options: [--registry <registry>] [--unicode] [--otp <otp>] @@ -1001,7 +976,7 @@ exports[`test/lib/load-all-commands.js TAP load each command view > must match s View registry info Usage: -npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...] +npm view [<package-spec>] [<field>[.subfield]...] Options: [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] diff --git a/tap-snapshots/test/lib/npm.js.test.cjs b/tap-snapshots/test/lib/npm.js.test.cjs index b2443e894..2cf4f53ec 100644 --- a/tap-snapshots/test/lib/npm.js.test.cjs +++ b/tap-snapshots/test/lib/npm.js.test.cjs @@ -238,11 +238,7 @@ All commands: cache Manipulates packages cache Usage: - 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 add <package-spec> npm cache clean [<key>] npm cache ls [<name>@<version>] npm cache verify @@ -308,7 +304,7 @@ All commands: deprecate Deprecate a version of a package Usage: - npm deprecate <pkg>[@<version>] <message> + npm deprecate <package-spec> <message> Options: [--registry <registry>] [--otp <otp>] @@ -321,10 +317,10 @@ All commands: npm diff [...<paths>] Options: - [--diff <pkg-name|spec|version> [--diff <pkg-name|spec|version> ...]] - [--diff-name-only] [--diff-unified <number>] [--diff-ignore-all-space] - [--diff-no-prefix] [--diff-src-prefix <path>] [--diff-dst-prefix <path>] - [--diff-text] [-g|--global] [--tag <tag>] + [--diff <package-spec> [--diff <package-spec> ...]] [--diff-name-only] + [--diff-unified <number>] [--diff-ignore-all-space] [--diff-no-prefix] + [--diff-src-prefix <path>] [--diff-dst-prefix <path>] [--diff-text] [-g|--global] + [--tag <tag>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] [--include-workspace-root] @@ -333,9 +329,9 @@ All commands: dist-tag Modify package distribution tags Usage: - npm dist-tag add <pkg>@<version> [<tag>] - npm dist-tag rm <pkg> <tag> - npm dist-tag ls [<pkg>] + npm dist-tag add <package-spec (with version)> [<tag>] + npm dist-tag rm <package-spec> <tag> + npm dist-tag ls [<package-spec>] Options: [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] @@ -388,8 +384,7 @@ All commands: npm exec --package=foo -c '<cmd> [args...]' Options: - [--package <pkg>[@<version>] [--package <pkg>[@<version>] ...]] - [-c|--call <call>] + [--package <package-spec> [--package <package-spec> ...]] [-c|--call <call>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] [--include-workspace-root] @@ -400,7 +395,7 @@ All commands: explain Explain installed packages Usage: - npm explain <folder | specifier> + npm explain <package-spec> Options: [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] @@ -436,7 +431,7 @@ All commands: fund Retrieve funding information Usage: - npm fund [[<@scope>/]<pkg>] + npm fund [<package-spec>] Options: [--json] [--no-browser|--browser <browser>] [--unicode] @@ -480,12 +475,11 @@ All commands: init Create a package.json file Usage: - npm init [--force|-f|--yes|-y|--scope] + npm init <package-spec> (same as \`npx <package-spec>) npm init <@scope> (same as \`npx <@scope>/create\`) - npm init [<@scope>/]<name> (same as \`npx [<@scope>/]create-<name>\`) Options: - [-y|--yes] [-f|--force] + [-y|--yes] [-f|--force] [--scope <@scope>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] [--no-workspaces-update] [--include-workspace-root] @@ -496,16 +490,7 @@ All commands: install Install a package Usage: - 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 <folder> - npm install <tarball file> - npm install <tarball url> - npm install <git:// url> - npm install <github username>/<github project> + npm install [<package-spec> ...] Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] @@ -536,16 +521,7 @@ All commands: install-test Install package(s) and run tests Usage: - 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 <git:// url> - npm install-test <github username>/<github project> + npm install-test [<package-spec> ...] Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] @@ -563,8 +539,7 @@ All commands: link Symlink a package folder Usage: - npm link (in package dir) - npm link [<@scope>/]<pkg>[@<version>] + npm link [<package-spec>] Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle] @@ -621,7 +596,7 @@ All commands: ls List installed packages Usage: - npm ls [[<@scope>/]<pkg> ...] + npm ls <package-spec> Options: [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] [--depth <depth>] @@ -651,7 +626,7 @@ All commands: outdated Check for outdated packages Usage: - npm outdated [[<@scope>/]<pkg> ...] + npm outdated [<package-spec> ...] Options: [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] @@ -662,9 +637,9 @@ All commands: owner Manage package owners Usage: - npm owner add <user> [<@scope>/]<pkg> - npm owner rm <user> [<@scope>/]<pkg> - npm owner ls [<@scope>/]<pkg> + npm owner add <user> <package-spec> + npm owner rm <user> <package-spec> + npm owner ls <package-spec> Options: [--registry <registry>] [--otp <otp>] @@ -678,7 +653,7 @@ All commands: pack Create a tarball from a package Usage: - npm pack [[<@scope>/]<pkg>...] + npm pack <package-spec> Options: [--dry-run] [--json] [--pack-destination <pack-destination>] @@ -752,7 +727,7 @@ All commands: publish Publish a package Usage: - npm publish [<folder>] + npm publish <package-spec> Options: [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>] @@ -764,7 +739,7 @@ All commands: rebuild Rebuild a package Usage: - npm rebuild [[<@scope>/]<name>[@<version>] ...] + npm rebuild [<package-spec>] ...] Options: [-g|--global] [--no-bin-links] [--foreground-scripts] [--ignore-scripts] @@ -863,7 +838,7 @@ All commands: star Mark your favorite packages Usage: - npm star [<pkg>...] + npm star [<package-spec>...] Options: [--registry <registry>] [--unicode] [--otp <otp>] @@ -956,7 +931,7 @@ All commands: unpublish Remove a package from the registry Usage: - npm unpublish [<@scope>/]<pkg>[@<version>] + npm unpublish [<package-spec>] Options: [--dry-run] [-f|--force] @@ -968,7 +943,7 @@ All commands: unstar Remove an item from your favorite packages Usage: - npm unstar [<pkg>...] + npm unstar [<package-spec>...] Options: [--registry <registry>] [--unicode] [--otp <otp>] @@ -1011,7 +986,7 @@ All commands: view View registry info Usage: - npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...] + npm view [<package-spec>] [<field>[.subfield]...] Options: [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] diff --git a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs index 33d6e4fb7..19909d8c5 100644 --- a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs +++ b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs @@ -1591,7 +1591,7 @@ exports[`test/lib/utils/config/definitions.js TAP > config description for scrip * Type: null or String The shell to use for scripts run with the \`npm exec\`, \`npm run\` and \`npm -init <pkg>\` commands. +init <package-spec>\` commands. ` exports[`test/lib/utils/config/definitions.js TAP > config description for searchexclude 1`] = ` diff --git a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs index 77f2c8768..9d95aa952 100644 --- a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs +++ b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs @@ -1391,7 +1391,7 @@ npm init --scope=@foo --yes * Type: null or String The shell to use for scripts run with the \`npm exec\`, \`npm run\` and \`npm -init <pkg>\` commands. +init <package-spec>\` commands. <!-- automatically generated, do not edit manually --> <!-- see lib/utils/config/definitions.js --> |