diff options
author | Gar <gar+gh@danger.computer> | 2022-06-22 23:45:41 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-06-22 23:45:41 +0300 |
commit | 69b5a9674e8c03219c3da088b35b8ec6dea69770 (patch) | |
tree | e6799096e6a86cdd1d14bae35e4fcbf45b59fb80 /docs | |
parent | f2340f816f5a137038945229bf8a0d30160e76e8 (diff) |
docs: consolidate docs and help for package spec (#5048)
Many of our commands parse their args via
[npm-package-arg](https://npm.im/npm-package-arg), which is a good
standard way of parsing a "package" argument. However the docs
surrounding these args are not very consistent. This can lead to
confusion in commands such as `npm publish` where the behavior is
slightly different than in the past due to this.
This adds a new help command `npm help package-spec` that describes what
this argument is, and can be, and also updates all the commands that
interpret their args this with to refer to them as `<package-spec>`. It
also adds a link to the new help page on their docs pages.
Diffstat (limited to 'docs')
29 files changed, 234 insertions, 116 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 |