From b3eee14a96befd966b5b4ec10e1944a1be2dcebe Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Fri, 23 Oct 2026 00:49:08 +0200 Subject: [PATCH] docs(cli): correct the command reference from access to init (#17247) Part of pnpm/tasks#191. Wrong claims, fixed on the v12 page and on the v11 twin where it had the same text: - audit: `--interactive` implies `--fix=override`; `info` is a valid audit level. - change check validates the pending intents. - deploy copies the publish packlist unless `deployAllFiles` is set. - deprecate: an empty message fails, use `pnpm undeprecate`. - deprecate, dist-tag: only `--otp` supplies the one-time password. - dist-tag add defaults to `latest`, not the `tag` setting. - docs takes exactly one package. - env: there is no `add` subcommand, and `list` queries the Node.js mirror only. - v12 only: clean no longer says it uses Node.js, add no longer presents `-w` as an alias, the deploy package-manager-pin history is no longer contradictory, doctor sample shows store v11. Missing facts: - add: `--save-prefix`, `--save-build`, `--no-save-peer`, `--no-save-types`, `--lockfile-only`, `--force`; where Yarn vs npm and Bun pins go; catalog and configDependencies links. - access status shorthands; approve-builds error codes, the placeholder value and the immediate rebuild; audit exit code, `--optional`, `--production`, and how to make `--ignore` write `audit.ignore`; `--ignore` exits with code 0 and `--ignore-unfixable` fails on an advisory without a GHSA ID. - bugs and docs `--registry`; ci accepts install options; clean script override and modulesDir; config `--location` type and `get` output; create name mapping, `--shell-mode`, `--cpu`, `--os`, `--libc`; dedupe flags; deploy error codes and Dockerfile WORKDIR; dist-tag aliases and web OTP; env `--global` requirement; exec recursive options and PNPM_PACKAGE_NAME; fetch `--ignore-pnpmfile`, lockfile requirement, optional pnpmfile in the Dockerfiles. - usage, examples, and output for bin, cache, cache list, cache delete (with the no-argument warning), cache view, cat-file, cat-index, find-hash, ignored-builds, import, and init (`initPackageManager`, `initType`, ERR_PNPM_PACKAGE_JSON_EXISTS). Stale history on v12 pages: removed "Added in" markers for v10 and v11 and rewrote "Since v11..." passages as current behavior in access, add, approve-builds, audit, bugs, cache-list-registries, cache-path, cache-prune, change, ci, config, create, deploy, deprecate, dist-tag, docs, doctor, help, ignored-builds, and init. Review follow-up: cat-file now says it rejects the hex digest that cat-index prints; the settings index links initPackageManager and initType; `change check` says it plans the release without reporting it (both versions); `pnpm bin` follows a custom modulesDir. --- pnpm/docs/cli/access.md | 4 +-- pnpm/docs/cli/add.md | 38 ++++++++++++--------- pnpm/docs/cli/approve-builds.md | 24 +++----------- pnpm/docs/cli/audit.md | 46 ++++++++++++-------------- pnpm/docs/cli/bin.md | 7 +++- pnpm/docs/cli/bugs.md | 14 ++++---- pnpm/docs/cli/cache-delete.md | 16 +++++++++ pnpm/docs/cli/cache-list-registries.md | 2 +- pnpm/docs/cli/cache-list.md | 10 ++++++ pnpm/docs/cli/cache-path.md | 6 ++-- pnpm/docs/cli/cache-prune.md | 9 +++-- pnpm/docs/cli/cache-view.md | 10 +++++- pnpm/docs/cli/cache.md | 14 ++++---- pnpm/docs/cli/cat-file.md | 2 +- pnpm/docs/cli/cat-index.md | 2 ++ pnpm/docs/cli/change.md | 6 ++-- pnpm/docs/cli/ci.md | 6 ++-- pnpm/docs/cli/clean.md | 8 +++-- pnpm/docs/cli/config.md | 12 +++---- pnpm/docs/cli/create.md | 37 ++++++++++++++++++--- pnpm/docs/cli/dedupe.md | 20 +++++++++++ pnpm/docs/cli/deploy.md | 14 ++++---- pnpm/docs/cli/deprecate.md | 14 +++----- pnpm/docs/cli/dist-tag.md | 10 +++--- pnpm/docs/cli/docs.md | 26 +++++---------- pnpm/docs/cli/doctor.md | 4 +-- pnpm/docs/cli/env.md | 31 +++-------------- pnpm/docs/cli/exec.md | 9 ++--- pnpm/docs/cli/fetch.md | 21 ++++++------ pnpm/docs/cli/find-hash.md | 4 ++- pnpm/docs/cli/help.md | 2 -- pnpm/docs/cli/ignored-builds.md | 9 +++-- pnpm/docs/cli/import.md | 16 +++++++-- pnpm/docs/cli/init.md | 34 ++++++++++++++----- pnpm/docs/settings.md | 2 +- pnpm11/docs/cli/audit.md | 6 ++-- pnpm11/docs/cli/change.md | 4 +-- pnpm11/docs/cli/deploy.md | 4 ++- pnpm11/docs/cli/deprecate.md | 12 +++---- pnpm11/docs/cli/dist-tag.md | 4 +-- pnpm11/docs/cli/docs.md | 16 ++------- pnpm11/docs/cli/env.md | 26 +++------------ 42 files changed, 303 insertions(+), 258 deletions(-) diff --git a/pnpm/docs/cli/access.md b/pnpm/docs/cli/access.md index dcdb6bb032..c2dccea8ae 100644 --- a/pnpm/docs/cli/access.md +++ b/pnpm/docs/cli/access.md @@ -3,8 +3,6 @@ id: access title: pnpm access --- -Added in: v11.11.0 - Manages package access and visibility on the registry. ```sh @@ -60,6 +58,8 @@ pnpm access set status=public @myorg/pkg pnpm access set status=private @myorg/pkg ``` +`restricted` is accepted as a synonym for `private`. `pnpm access public ` and `pnpm access restricted ` are shorthands for `set status=public` and `set status=private`. + Only scoped packages can change visibility. Unscoped packages are always public, and attempting to change one fails with `ERR_PNPM_ACCESS_SET_STATUS_UNSCOPED`. ### set mfa diff --git a/pnpm/docs/cli/add.md b/pnpm/docs/cli/add.md index 562e35726d..eb34b338fe 100644 --- a/pnpm/docs/cli/add.md +++ b/pnpm/docs/cli/add.md @@ -65,7 +65,7 @@ Naming a [package manager](../package-managers.md) (`npm`, `yarn` or `bun`) reco pnpm add yarn@4 ``` -writes `"packageManager": "yarn@4.18.0"`, and every other package manager is recorded as a range in [`devEngines.packageManager`](../package_json.md#devenginespackagemanager). Naming a runtime (`node`, `deno`) records it under `engines.runtime`, as the explicit [`node@tool:22`](../package-sources.md#provisioned-tools) spelling does since v12.13.0. `bun` is both, and is declared as the project's package manager unless you ask for the runtime (`pnpm add bun@tool:1.3.0`). +writes `"packageManager": "yarn@4.18.0"`. npm and Bun are recorded as a range in [`devEngines.packageManager`](../package_json.md#devenginespackagemanager) instead. Each write removes the other field. Naming a runtime (`node`, `deno`) records it under `engines.runtime`, as the explicit [`node@tool:22`](../package-sources.md#provisioned-tools) spelling does since v12.13.0. `bun` is both, and is declared as the project's package manager unless you ask for the runtime (`pnpm add bun@tool:1.3.0`). Globally, `pnpm add -g yarn` installs the current Yarn line rather than the Classic-only `yarn` package, and `pnpm add -g node@22` installs that Node.js release rather than a wrapper that downloads one. @@ -124,10 +124,14 @@ Install the specified packages as `optionalDependencies`. Saved dependencies will be configured with an exact version rather than using pnpm's default semver range operator. +### --save-build + +Install `crate:` packages as Cargo build dependencies. + ### --save-peer Using `--save-peer` will add one or more packages to `peerDependencies` and -install them as dev dependencies. +install them as dev dependencies. `--no-save-peer` overrides a `savePeer: true` setting. ### --save-types @@ -141,7 +145,11 @@ pnpm add express --save-types # saves express to dependencies, @types/express to devDependencies ``` -Set `saveTypes: true` in `pnpm-workspace.yaml` to enable this by default. +Set [`saveTypes: true`](../settings/other.md#savetypes) in `pnpm-workspace.yaml` to enable this by default. `--no-save-types` overrides that setting. + +### --save-prefix <prefix\> + +The prefix of the saved version range: `^`, `~`, `=` for an explicit exact pin, or an empty string for a bare exact version. Overrides the [`savePrefix`](../settings/other.md#saveprefix) setting. ### --tilde @@ -152,30 +160,24 @@ range (`~1.2.3`) instead of the default caret range (`^1.2.3`). ### --save-catalog -Added in: v10.12.1 - Save the new dependency to the default [catalog]. ### --save-catalog-name <catalog_name\> -Added in: v10.12.1 - Save the new dependency to the specified [catalog]. -[catalog]: catalogs.md +[catalog]: ../catalogs.md ### --config -Added in: v10.8.0 - -Save the dependency to [configDependencies](config-dependencies.md). +Save the dependency to [configDependencies](../config-dependencies.md). Since v12.12.0, the saved range follows the same rules as for a dependency in `package.json`. ### --ignore-workspace-root-check -Adding a new dependency to the root workspace package fails, unless the -`--ignore-workspace-root-check` or `-w` flag is used. +Adding a new dependency to the root workspace package fails, unless you pass +`--ignore-workspace-root-check` or target the root with `-w` (`--workspace-root`). For instance, `pnpm add debug -w`. @@ -196,8 +198,6 @@ registry. ### --allow-build -Added in: v10.4.0 - A list of package names that are allowed to run postinstall scripts during installation. Example: @@ -216,6 +216,14 @@ pnpm add --allow-build=!core-js my-bundler writes `allowBuilds: { core-js: false }`, so the package is never asked about again. Global installs (`pnpm add -g`) record the denial too. +### --lockfile-only + +Update `package.json` and `pnpm-lock.yaml` without downloading dependencies or writing `node_modules`. + +### --force + +Reinstall every package the lockfile names, relinking packages that an earlier install already linked. + ### --registry Specify the registry to use for this installation: diff --git a/pnpm/docs/cli/approve-builds.md b/pnpm/docs/cli/approve-builds.md index 043b27cd38..d15ac4b1ee 100644 --- a/pnpm/docs/cli/approve-builds.md +++ b/pnpm/docs/cli/approve-builds.md @@ -3,8 +3,6 @@ id: approve-builds title: pnpm approve-builds --- -Added in: v10.1.0 - Approve dependencies for running scripts during installation. The approved dependencies are added to the [`allowBuilds`] map in `pnpm-workspace.yaml` with a value of `true`, while unapproved ones are saved with a value of `false`. You can also update these settings manually if you prefer. @@ -22,21 +20,19 @@ You can run `pnpm approve-builds` without arguments to get an interactive prompt pnpm approve-builds esbuild fsevents !core-js ``` -Prefix a package name with `!` to deny it. Only mentioned packages are affected; the rest are left untouched. +Prefix a package name with `!` to deny it. Only mentioned packages are affected; the rest are left untouched. Approved packages that are awaiting approval are rebuilt right away. Naming a package both approved and denied fails with `ERR_PNPM_APPROVE_BUILDS_CONTRADICTING_ARGS`. Since v12.4.0, a decision is saved even when nothing is awaiting approval, so a policy can be written before the package is installed. A named package that is not awaiting approval is reported with a warning rather than an error, and is not rebuilt: it may not be installed yet, and rebuilding it would need a lockfile the project may not have. An argument that names no package at all is rejected before anything is written. -During install, packages with ignored builds that are not yet listed in `allowBuilds` are automatically added to `pnpm-workspace.yaml` with a placeholder value, so you can manually set them to `true` or `false`. +During install, packages with ignored builds that are not yet listed in `allowBuilds` are automatically added to `pnpm-workspace.yaml` with the placeholder value `set this to true or false`, so you can manually set them to `true` or `false`. -Since v11.23.0, writing `allowBuilds` also removes `onlyBuiltDependencies`, `onlyBuiltDependenciesFile`, `neverBuiltDependencies`, and `ignoredBuiltDependencies` from `pnpm-workspace.yaml`. `allowBuilds` replaced those settings in pnpm 11 and they have been ignored since, so a workspace migrated from pnpm 10 kept them around looking active. +Writing `allowBuilds` also removes the ignored legacy settings `onlyBuiltDependencies`, `onlyBuiltDependenciesFile`, `neverBuiltDependencies`, and `ignoredBuiltDependencies` from `pnpm-workspace.yaml`. ## Options ### --all -Added in: v10.32.0 - -Approve all pending builds without interactive prompts. +Approve all pending builds without interactive prompts. Cannot be combined with package names (`ERR_PNPM_APPROVE_BUILDS_ALL_WITH_ARGS`). ### --global, -g @@ -47,15 +43,3 @@ group](../global-packages.md#isolated-installations), asks about them once, and writes a single policy into the `pnpm-workspace.yaml` of the global packages directory. Only the groups that actually contain an approved package are then rebuilt. - -:::info Removed in v11.0.0, back in v11.24.0 - -Isolated global installs gave every install group its own manifest, and -`pnpm approve-builds -g` was removed rather than made to guess which one to -write to. Since v11.24.0 it writes one policy for all of them, so it works -again. From v11.0.0 until v11.24.0, use `--allow-build` when -installing globally (e.g. `pnpm add -g --allow-build=esbuild esbuild`), or -answer the prompt pnpm shows during a global install. Both options remain -available if you prefer to decide at install time. - -::: diff --git a/pnpm/docs/cli/audit.md b/pnpm/docs/cli/audit.md index ee43343cd3..21cf10fbd3 100644 --- a/pnpm/docs/cli/audit.md +++ b/pnpm/docs/cli/audit.md @@ -19,7 +19,9 @@ Or alternatively, run `pnpm audit --fix`. If you want to tolerate some vulnerabilities as they don't affect your project, you may use the [`audit.ignore`] setting. -Since v11, `pnpm audit` queries the registry's `/-/npm/v1/security/advisories/bulk` endpoint. The response does not include CVE identifiers, so advisories are filtered by GitHub advisory ID (GHSA) instead. If you previously listed CVEs under `auditConfig.ignoreCves`, replace each entry with the corresponding `GHSA-xxxx-xxxx-xxxx` value (shown in the `More info` column of `pnpm audit` output) under [`audit.ignore`]. +`pnpm audit` queries the registry's `/-/npm/v1/security/advisories/bulk` endpoint. The response does not include CVE identifiers, so advisories are identified by the GitHub advisory ID (GHSA) in their URL. + +The command exits with code `1` when an advisory at or above the [audit level](#--audit-level-severity) remains after ignored advisories are removed. With `--ignore` or `--ignore-unfixable`, the command only saves the IDs and exits with code `0`. [overrides]: ../settings/dependency-resolution.md#overrides [`audit.ignore`]: #auditignore @@ -28,8 +30,6 @@ Since v11, `pnpm audit` queries the registry's `/-/npm/v1/security/advisories/bu ### signatures -Added in: v11.1.0 - ```sh pnpm audit signatures ``` @@ -46,10 +46,10 @@ The command exits with code `1` if any package has an invalid signature, or if a ### --audit-level <severity\> -* Type: **low**, **moderate**, **high**, **critical** +* Type: **info**, **low**, **moderate**, **high**, **critical** * Default: **low** -Only print advisories with severity greater than or equal to ``. +Only print advisories with severity greater than or equal to ``. Advisories below this level also do not fail the command. This can also be set via [`audit.level`](#auditlevel) in `pnpm-workspace.yaml`. @@ -57,15 +57,13 @@ This can also be set via [`audit.level`](#auditlevel) in `pnpm-workspace.yaml`. Add overrides to the `pnpm-workspace.yaml` file to force non-vulnerable versions of the dependencies. -Use `--fix=update` (added in v11.0.0) to fix vulnerabilities by updating the vulnerable packages in the lockfile instead of adding overrides. +Use `--fix=update` to fix vulnerabilities by updating the vulnerable packages in the lockfile instead of adding overrides. When [`minimumReleaseAge`](../settings/dependency-resolution.md#minimumreleaseage) is set, `--fix` also adds the minimum patched version of each advisory to [`minimumReleaseAgeExclude`](../settings/dependency-resolution.md#minimumreleaseageexclude) in `pnpm-workspace.yaml`, so the security fix can be installed without waiting for the release age window. ### --interactive, -i -Added in: v11.0.0 - -Review the advisories selected by `--fix` and pick which ones to apply. Only usable together with `--fix`. +Review the advisories selected by `--fix` and pick which ones to apply. Implies `--fix=override` when `--fix` is not given. ### --json @@ -77,9 +75,13 @@ Output audit report in JSON format. Only audit dev dependencies. -### --prod, -P +### --prod, --production, -P -Only audit production dependencies. +Only audit `dependencies` and `optionalDependencies`. + +### --optional + +Audit `optionalDependencies`. This is the default. ### --no-optional @@ -92,25 +94,19 @@ So the process will fail only if the registry actually successfully responds wit ### --ignore-unfixable -Added in: v10.11.0 +Ignore all advisories with no resolution. An unfixable advisory without a GHSA ID cannot be ignored and fails the command with `ERR_PNPM_AUDIT_MISSING_GHSA`. -Ignore all advisories with no resolution. - -Since v11, unfixable advisories are tracked by GHSA rather than CVE. - -Their IDs are saved in `pnpm-workspace.yaml` the same way as with [`--ignore`](#--ignore-vulnerability). +Their GHSA IDs are saved in `pnpm-workspace.yaml` the same way as with [`--ignore`](#--ignore-vulnerability). ### --ignore <vulnerability\> -Added in: v10.11.0 +Ignore a vulnerability by its GitHub advisory ID (GHSA). -Ignore a vulnerability by its GitHub advisory ID (GHSA). Before v11 this flag accepted CVE identifiers. - -The ID is saved in `pnpm-workspace.yaml`, which is created if missing, and no audit report is printed. It is added to [`audit.ignore`](#auditignore) if that list is already set, otherwise to `auditConfig.ignoreGhsas`. pnpm 12 still reads `auditConfig.ignoreGhsas`, so the advisory stays ignored either way. +The ID is saved in `pnpm-workspace.yaml`, which is created if missing, and no audit report is printed. It is added to [`audit.ignore`](#auditignore) if that list is already set, otherwise to the deprecated `auditConfig.ignoreGhsas`, which pnpm still reads. To have a new project write to `audit.ignore`, create the list first (`audit: { ignore: [] }`). ## Configuration -`pnpm audit` is configured in the `audit` section of `pnpm-workspace.yaml` (added in v11.16.0): +`pnpm audit` is configured in the `audit` section of `pnpm-workspace.yaml`: ```yaml title="pnpm-workspace.yaml" audit: @@ -122,7 +118,7 @@ audit: ### audit.level * Default: **low** -* Type: **low**, **moderate**, **high**, **critical** +* Type: **info**, **low**, **moderate**, **high**, **critical** Only print advisories with severity greater than or equal to this level. Same as the [`--audit-level`](#--audit-level-severity) flag. @@ -161,8 +157,8 @@ audit: :::info -Before v11.16.0, these settings were named `auditLevel` and `auditConfig.ignoreGhsas`. These deprecated names are still supported in pnpm v12; when both are set, the `audit` section takes precedence and a warning is printed. +`auditLevel` and `auditConfig.ignoreGhsas` are deprecated names for `audit.level` and `audit.ignore`, and pnpm still reads them. When both spellings are set, the `audit` section takes precedence and a warning is printed. -Before v11, `auditConfig.ignoreCves` was used to filter advisories by CVE identifier. That setting is no longer recognized. +`auditConfig.ignoreCves` is not recognized. Replace each CVE with the matching `GHSA-xxxx-xxxx-xxxx` ID, shown in the `More info` column of `pnpm audit` output, under [`audit.ignore`](#auditignore). ::: diff --git a/pnpm/docs/cli/bin.md b/pnpm/docs/cli/bin.md index 5fbf76ee49..9a4ba6096a 100644 --- a/pnpm/docs/cli/bin.md +++ b/pnpm/docs/cli/bin.md @@ -3,7 +3,12 @@ id: bin title: pnpm bin --- -Prints the directory into which the executables of dependencies are linked. +Prints the directory into which the executables of dependencies are linked, the project's `node_modules/.bin`, or `/.bin` with a custom [`modulesDir`](../settings/node-modules.md#modulesdir). + +```sh +$ pnpm bin +/path/to/project/node_modules/.bin +``` ## Options diff --git a/pnpm/docs/cli/bugs.md b/pnpm/docs/cli/bugs.md index a521d6e3cf..461128c334 100644 --- a/pnpm/docs/cli/bugs.md +++ b/pnpm/docs/cli/bugs.md @@ -3,24 +3,26 @@ id: bugs title: pnpm bugs --- -Added in: v11.1.0 - Opens a package's bug tracker URL in the browser. +Aliases: `issues` + ```sh pnpm bugs [ ...] ``` -## Aliases - -`pnpm issues` (added in v11.10.0) is an alias of `pnpm bugs`. - When run without arguments inside a package directory, it opens the bug tracker for the current project (using the `bugs` field from `package.json`). When one or more package names are passed, pnpm fetches each package's metadata from the registry and opens its bug tracker. If a package does not declare a `bugs` field, pnpm falls back to `/issues` derived from the `repository` field. +## Options + +### --registry <url\> + +The registry to fetch the named packages' metadata from. + ## Examples Open the bug tracker for a published package: diff --git a/pnpm/docs/cli/cache-delete.md b/pnpm/docs/cli/cache-delete.md index 81c1372d56..343d648606 100644 --- a/pnpm/docs/cli/cache-delete.md +++ b/pnpm/docs/cli/cache-delete.md @@ -10,3 +10,19 @@ This command is experimental ::: Deletes metadata cache for the specified packages. Supports patterns. + +```sh +pnpm cache delete [...] +``` + +Each pattern is a glob segment matched against `/.jsonl`, and only the cache of the configured registry is affected. Use `--registry` to pick another one. The deleted files are printed one per line. + +```sh +pnpm cache delete '@babel/*' +``` + +:::warning + +Without arguments, `pnpm cache delete` deletes every cached metadata file of the configured registry. The descriptor-scoped metadata under `v12/metadata-private` is not affected. + +::: diff --git a/pnpm/docs/cli/cache-list-registries.md b/pnpm/docs/cli/cache-list-registries.md index dfb4888c65..8f33f3b8a2 100644 --- a/pnpm/docs/cli/cache-list-registries.md +++ b/pnpm/docs/cli/cache-list-registries.md @@ -16,4 +16,4 @@ https://registry.npmjs.org/ https://npm.example.com:8443/team-a/ ``` -Since v12.4.0, the metadata cache is keyed by the registry's full URL, including its path and scheme, so two registries served from one host under different paths no longer share cached packuments and metadata fetched over HTTP is never reused for HTTPS. Up to v12.4.2 this command printed the cache directory name, such as `https%3A+registry.npmjs.org`, and since v12.5.0 it prints the URL, matching [`pnpm cache view`](./cache-view.md). A script that parsed the old host-shaped directory names, here or in `pnpm cache list`, needs updating, and the first install after upgrading refetches registry metadata. The package store is untouched. +The metadata cache is keyed by the registry's full URL, including its path and scheme. Two registries served from one host under different paths do not share cached metadata, and metadata fetched over HTTP is never reused for HTTPS. diff --git a/pnpm/docs/cli/cache-list.md b/pnpm/docs/cli/cache-list.md index 2d3a6084d2..f73d94e70c 100644 --- a/pnpm/docs/cli/cache-list.md +++ b/pnpm/docs/cli/cache-list.md @@ -10,3 +10,13 @@ This command is experimental ::: Lists the available packages metadata cache. Supports filtering by glob. + +```sh +pnpm cache list [...] +``` + +The command searches the cache of the configured registry, in the metadata directory that the current resolution mode reads. Each match is printed on its own line as a path relative to that directory, `/.jsonl`. Without arguments, every package in it is listed. + +```sh +pnpm cache list 'react*' +``` diff --git a/pnpm/docs/cli/cache-path.md b/pnpm/docs/cli/cache-path.md index 15a4ed3718..9b776164d2 100644 --- a/pnpm/docs/cli/cache-path.md +++ b/pnpm/docs/cli/cache-path.md @@ -3,22 +3,20 @@ id: cache-path title: pnpm cache path --- -Added in: v11.22.0 - Prints the directory pnpm uses for its metadata cache, mirroring [`pnpm store path`](./store.md#path). The path is printed absolute and lexically cleaned, so a relative [`cacheDir`](../settings/other.md#cachedir) yields a path other tools can consume. ```sh pnpm cache path ``` -pnpm derives this directory from the platform and the `cacheDir` setting, so a CI setup that wants to cache it no longer has to mirror that resolution by hand: +pnpm derives this directory from the platform and the `cacheDir` setting, so a CI setup that wants to cache it does not have to mirror that resolution by hand: ```yaml title=".github/workflows/ci.yaml" - name: Get the cache directory run: echo "PNPM_CACHE_DIR=$(pnpm cache path)" >> $GITHUB_ENV ``` -Besides registry metadata and the [`pnpm dlx`](./pnx.md) cache, that directory holds the lockfile verification log: the record of which lockfile passed which [supply-chain policies](../supply-chain-security.md). Restoring it lets a job skip re-verifying a lockfile the log already covers under the policies currently configured. That check is the dominant cost of an install in CI once the store is warm. Since v11.22.0, [`pnpm store prune`](./store.md#prune) no longer deletes that log. +Besides registry metadata and the [`pnpm dlx`](./pnx.md) cache, that directory holds the lockfile verification log: the record of which lockfile passed which [supply-chain policies](../supply-chain-security.md). Restoring it lets a job skip re-verifying a lockfile the log already covers under the policies currently configured. That check is the dominant cost of an install in CI once the store is warm. [`pnpm store prune`](./store.md#prune) keeps that log. :::important diff --git a/pnpm/docs/cli/cache-prune.md b/pnpm/docs/cli/cache-prune.md index 42fb2913a7..5ab9cdc493 100644 --- a/pnpm/docs/cli/cache-prune.md +++ b/pnpm/docs/cli/cache-prune.md @@ -17,9 +17,12 @@ Deletes the registry metadata cache directories that this version of pnpm can no pnpm cache prune ``` -pnpm v12.4.0 changed the metadata cache directory name of every registry, so the first install after upgrading refetched metadata into a new directory and left the old one in place. Nothing reads it, and no other subcommand removes it, because [`cache list`](./cache-list.md), [`cache view`](./cache-view.md) and [`cache delete`](./cache-delete.md) all search under the configured registry's current directory name. `cache prune` goes through all three metadata roots, `v12/metadata`, `v12/metadata-full` and `v12/metadata-full-filtered`, and removes the directories whose names this version cannot read. +pnpm keeps registry metadata in three roots, `v12/metadata`, `v12/metadata-full` and `v12/metadata-full-filtered`, with one directory per registry named after the registry's full URL. `cache prune` removes: -A later version moved the metadata cache from `v11/` to `v12/`, because the cache file format changed. `cache prune` removes every directory under `v11/metadata`, `v11/metadata-full`, `v11/metadata-full-filtered` and `v11/metadata-private`. +- every directory under `v11/metadata`, `v11/metadata-full`, `v11/metadata-full-filtered` and `v11/metadata-private`, which older pnpm versions use; +- the directories under the `v12/` roots that are named after the registry's host alone, which this version cannot read. + +No other subcommand removes these directories, because [`cache list`](./cache-list.md), [`cache view`](./cache-view.md) and [`cache delete`](./cache-delete.md) all search under the configured registry's current directory name. Each removed directory is printed as the metadata root followed by the directory name: @@ -45,7 +48,7 @@ The list on stdout is the same as a real prune's, so you can diff the two runs o :::warning -The cache directory is shared by every pnpm on the machine. If an older pnpm runs on the same machine under the same [`cacheDir`](../settings/other.md#cachedir), it may still read and write the directories that prune removes, and pruning costs that CLI one metadata refetch. Only the cache is affected, and it refills itself. Use `--dry-run` to see the list before removing anything. +The cache directory is shared by every pnpm on the machine. If an older pnpm runs on the same machine under the same [`cacheDir`](../settings/other.md#cachedir), it may still read and write the directories that prune removes. Projects that use that pnpm refetch registry metadata after a prune, and their offline installs fail until they do. Only the cache is affected, and it refills itself. Use `--dry-run` to see the list before removing anything. ::: diff --git a/pnpm/docs/cli/cache-view.md b/pnpm/docs/cli/cache-view.md index acdd8f8fc5..6e337c7b71 100644 --- a/pnpm/docs/cli/cache-view.md +++ b/pnpm/docs/cli/cache-view.md @@ -11,4 +11,12 @@ This command is experimental Views information from the specified package's cache. -Since v12.4.0, the output identifies each cached entry by the registry's full URL rather than by its host. +```sh +pnpm cache view +``` + +The output is a JSON object keyed by registry URL. Each entry lists `cachedVersions` (versions present in the store), `nonCachedVersions`, `cachedAt`, and `distTags`. When the cache directory does not exist, `{}` is printed. + +```sh +pnpm cache view react +``` diff --git a/pnpm/docs/cli/cache.md b/pnpm/docs/cli/cache.md index 97d786ffca..b563c20d98 100644 --- a/pnpm/docs/cli/cache.md +++ b/pnpm/docs/cli/cache.md @@ -3,10 +3,12 @@ id: cache title: pnpm cache --- +Manages the registry metadata cache: the package metadata that pnpm downloads from registries and keeps in the [`cacheDir`](../settings/other.md#cachedir) directory. + Commands: -* [cache list](/cli/cache-list.md) -* [cache list-registries](/cli/cache-list-registries.md) -* [cache delete](/cli/cache-delete.md) -* [cache view](/cli/cache-view.md) -* [cache path](/cli/cache-path.md) -* [cache prune](/cli/cache-prune.md) +* [cache list](./cache-list.md) +* [cache list-registries](./cache-list-registries.md) +* [cache delete](./cache-delete.md) +* [cache view](./cache-view.md) +* [cache path](./cache-path.md) +* [cache prune](./cache-prune.md) diff --git a/pnpm/docs/cli/cat-file.md b/pnpm/docs/cli/cat-file.md index b5dcbba2de..f6113b5b7d 100644 --- a/pnpm/docs/cli/cat-file.md +++ b/pnpm/docs/cli/cat-file.md @@ -3,7 +3,7 @@ id: cat-file title: "pnpm cat-file" --- -Prints the contents of a file based on the hash value stored in the index file. For example: +Prints the contents of a file from the store, given its `sha512-` hash. The hex `digest` that [`pnpm cat-index`](./cat-index.md) prints is not accepted. For example: ```sh pnpm cat-file sha512-mvavhfVcEREI7d8dfvfvIkuBLnx7+rrkHHnPi8mpEDUlNpY4CUY+CvJ5mrrLl18iQYo1odFwBV7z/cOypG7xxQ== diff --git a/pnpm/docs/cli/cat-index.md b/pnpm/docs/cli/cat-index.md index c82a931d8d..b3cc5373ca 100644 --- a/pnpm/docs/cli/cat-index.md +++ b/pnpm/docs/cli/cat-index.md @@ -8,3 +8,5 @@ Prints the index file of a specific package from the store. The package is speci ```sh pnpm cat-index @ ``` + +The output is JSON that lists each file of the package with its `digest`, `mode`, and `size`. To find the packages that contain a file, pass its hash to [`pnpm find-hash`](./find-hash.md). diff --git a/pnpm/docs/cli/change.md b/pnpm/docs/cli/change.md index 452d4b50bf..1693b81360 100644 --- a/pnpm/docs/cli/change.md +++ b/pnpm/docs/cli/change.md @@ -3,8 +3,6 @@ id: change title: pnpm change --- -Added in: v11.13.0 - Records a change intent: which packages a change affects, the bump type for each, and a summary that becomes the changelog entry. The intent file is written to `.changeset/` in the [changesets](https://github.com/changesets/changesets) format. ```sh @@ -75,13 +73,13 @@ Private packages (`"private": true`) are never checked against the registry for Added in: v12.4.0 -Validate the versions committed in the workspace against the [epic](../versioning.md#epics) bands and [fixed group](../versioning.md#fixed-groups) lockstep declared in `pnpm-workspace.yaml`. +Validate the pending change intents, and check the versions committed in the workspace against the [epic](../versioning.md#epics) bands and [fixed group](../versioning.md#fixed-groups) lockstep declared in `pnpm-workspace.yaml`. ```sh pnpm change check ``` -Unlike `pnpm change status`, which reports the release the pending intents produce, `check` looks only at the versions already in the manifests. It reads no intents, so it is the step to run on every pull request: a package whose version drifted out of its epic's band, or out of step with its fixed group, fails the command. Every violation is listed, including ones in packages the current release does not touch. +Unlike `pnpm change status`, which reports the release the pending intents produce, `check` plans the release from the pending intents without reporting it, and checks only the versions already in the manifests. An intent that would fail at release time, such as one naming a package outside the workspace, fails the command. Run it on every pull request: a package whose version drifted out of its epic's band, or out of step with its fixed group, fails the command. Every violation is listed, including ones in packages the current release does not touch. ## Options diff --git a/pnpm/docs/cli/ci.md b/pnpm/docs/cli/ci.md index 19d93b66ef..44f32b1b5d 100644 --- a/pnpm/docs/cli/ci.md +++ b/pnpm/docs/cli/ci.md @@ -3,8 +3,6 @@ id: ci title: pnpm ci --- -Added in: v11.0.0 - Aliases: `clean-install`, `ic`, `install-clean` Perform a clean install. This command runs [`pnpm clean`](./clean.md) followed by [`pnpm install --frozen-lockfile`](./install.md). @@ -14,3 +12,7 @@ Designed for CI/CD environments where reproducible builds are critical. ```sh pnpm ci ``` + +## Options + +`pnpm ci` accepts the options of [`pnpm install`](./install.md), such as `--prod`, `--offline`, and `--filter`. diff --git a/pnpm/docs/cli/clean.md b/pnpm/docs/cli/clean.md index f83d98710f..9c23fe38ca 100644 --- a/pnpm/docs/cli/clean.md +++ b/pnpm/docs/cli/clean.md @@ -5,9 +5,11 @@ title: pnpm clean Aliases: `purge` -Safely remove `node_modules` contents from all workspace projects. Uses Node.js to remove directories, which correctly handles NTFS junctions on Windows without following them into their targets. +Safely remove `node_modules` contents from all workspace projects. Removes directories without following NTFS junctions on Windows into their targets. -In a workspace, `node_modules` directories are cleaned in the root and every workspace package. Non-pnpm hidden entries (e.g., `.cache`) inside `node_modules` are preserved. +In a workspace, `node_modules` directories are cleaned in the root and every workspace package. Non-pnpm hidden entries (e.g., `.cache`) inside `node_modules` are preserved. A custom [`modulesDir`](../settings/node-modules.md#modulesdir) is cleaned instead of `node_modules`. + +A `clean` or `purge` script in `package.json` overrides the built-in command. `pnpm pm clean` and `pnpm pm purge` run the built-in command regardless. If a custom [`virtualStoreDir`](../settings/node-modules.md#virtualstoredir) or `globalVirtualStoreDir` is configured and it resides inside the project root (but outside `node_modules`), it is also removed. @@ -15,4 +17,4 @@ If a custom [`virtualStoreDir`](../settings/node-modules.md#virtualstoredir) or ### --lockfile, -l -Also remove `pnpm-lock.yaml` files. +Also remove the `pnpm-lock.yaml` of the workspace root, or of the project outside a workspace. diff --git a/pnpm/docs/cli/config.md b/pnpm/docs/cli/config.md index beb0153482..5583392e0e 100644 --- a/pnpm/docs/cli/config.md +++ b/pnpm/docs/cli/config.md @@ -30,7 +30,7 @@ The global `rc` file (registry/auth settings only) is at: * On macOS: **~/Library/Preferences/pnpm/rc** * On Linux: **~/.config/pnpm/rc** -You can also retrieve the path to your global config file by running (added in v10.21.0): +You can also retrieve the path to your global config file by running: ```sh pnpm config get globalconfig @@ -67,7 +67,7 @@ The `set` command does not accept a property path. ### get <key> -Print the config value for the provided key. +Print the config value for the provided key. Strings, numbers, and booleans are printed as plain text, objects and arrays as JSON, and an unset key as `undefined`. With `--json`, every value is printed as JSON. The `key` can be a simple key: @@ -102,12 +102,6 @@ Show all the config settings. Output is a JSON object. Auth-related settings are hidden from the output; use `pnpm config get ` to read them explicitly. -:::note - -Since v11, `pnpm config get` (without `--json`) no longer prints INI-formatted text. It prints JSON for objects and arrays, and raw strings for strings, numbers, booleans, and nulls. `pnpm config get --json` prints all values as JSON. `pnpm config list` always prints a JSON object. - -::: - ## Options ### --global, -g @@ -118,6 +112,8 @@ With `get` and `list`, show the global configuration without the settings from t ### --location +* Type: **project**, **global** + By default, `--location` is set to `global`. When set to `project`, pnpm writes the setting to `pnpm-workspace.yaml` at the workspace root (or, for registry/auth settings, to the `.npmrc` in the workspace root). diff --git a/pnpm/docs/cli/create.md b/pnpm/docs/cli/create.md index 3bb1ba2c91..7a7abfb450 100644 --- a/pnpm/docs/cli/create.md +++ b/pnpm/docs/cli/create.md @@ -5,20 +5,49 @@ title: "pnpm create" Create a project from a `create-*` or `@foo/create-*` starter kit. +```sh +pnpm create [...] +``` + +The name is mapped to a starter kit package: + +| Name | Package | +|------|---------| +| `foo` | `create-foo` | +| `create-foo` | `create-foo` | +| `@scope` | `@scope/create` | +| `@scope/foo` | `@scope/create-foo` | + +pnpm runs the starter kit with [`pnx`](./pnx.md) and passes the remaining arguments to it. + ## Examples ```sh -pnpm create react-app my-app +pnpm create vite my-app ``` ## Options ### --allow-build -Added in: v10.2.0 - A list of package names that are allowed to run postinstall scripts during installation. +### --shell-mode, -c + +Run the command inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. + +import CpuFlag from '../settings/_cpuFlag.mdx' + + + +import OsFlag from '../settings/_osFlag.mdx' + + + +import LibcFlag from '../settings/_libcFlag.mdx' + + + ## Security and trust policies -Since v11.0.0, `pnpm create` honors the project-level security and trust policy settings when resolving and fetching the starter kit. These include [`minimumReleaseAge`](../settings/dependency-resolution.md#minimumreleaseage), `minimumReleaseAgeExclude`, `minimumReleaseAgeStrict`, [`trustPolicy`](../settings/dependency-resolution.md#trustpolicy), `trustPolicyExclude`, and `trustPolicyIgnoreAfter`. +`pnpm create` honors the project-level security and trust policy settings when resolving and fetching the starter kit. These include [`minimumReleaseAge`](../settings/dependency-resolution.md#minimumreleaseage), `minimumReleaseAgeExclude`, `minimumReleaseAgeStrict`, [`trustPolicy`](../settings/dependency-resolution.md#trustpolicy), `trustPolicyExclude`, and `trustPolicyIgnoreAfter`. diff --git a/pnpm/docs/cli/dedupe.md b/pnpm/docs/cli/dedupe.md index 08d0b5ccf9..350c6179d6 100644 --- a/pnpm/docs/cli/dedupe.md +++ b/pnpm/docs/cli/dedupe.md @@ -15,6 +15,26 @@ Since v12.4.1, `pnpm dedupe` processes every project in the workspace by default Check if running dedupe would result in changes without installing packages or editing the lockfile. Exits with a non-zero status code if changes are possible. +### `--lockfile-only` + +Only update `pnpm-lock.yaml`. Packages are not downloaded and `node_modules` is not written. + +### `--ignore-scripts` + +Don't run lifecycle scripts of the project or its dependencies. + +### `--ignore-pnpmfile` + +Don't run the hooks of the [pnpmfile](../pnpmfile.md). + +### `--offline` + +Use only packages already in the store. A package missing from the store fails the command. + +### `--prefer-offline` + +Prefer cached packages and metadata over the network, even past their freshness window. + ### `--filter ` Restrict the command to the selected projects. [Read more about filtering.](../filtering.md) diff --git a/pnpm/docs/cli/deploy.md b/pnpm/docs/cli/deploy.md index f098401a57..5fec07a26c 100644 --- a/pnpm/docs/cli/deploy.md +++ b/pnpm/docs/cli/deploy.md @@ -11,7 +11,7 @@ Since v12.2.0, `pnpm deploy` no longer requires [`injectWorkspacePackages`](../w The binding is ambiguous when the ancestors provide more than one package or version, or when no ancestor provides the peer and the deployed graph holds more than one version. The deploy then fails with `ERR_PNPM_DEPLOY_AMBIGUOUS_PEER`, naming the package, the peer, and the competing resolutions. Pin the peer to one version with an [`overrides`](../settings/dependency-resolution.md#overrides) entry, or turn `injectWorkspacePackages` on, which is the setting that decides between the candidates. -Before those releases the command refused every non-injected workspace up front. `--legacy`, or `forceLegacyDeploy: true`, still selects the older implementation. +Before v12.2.0, the command refused every non-injected workspace up front. `--legacy`, or `forceLegacyDeploy: true`, still selects the older implementation. ::: @@ -27,6 +27,8 @@ Usage: pnpm --filter= deploy ``` +The filter must select exactly one project. Selecting none fails with `ERR_PNPM_NOTHING_TO_DEPLOY`, and selecting several fails with `ERR_PNPM_CANNOT_DEPLOY_MANY`. A target directory that is unsafe to write, such as the workspace root, fails with `ERR_PNPM_INVALID_DEPLOY_TARGET`. + In case you build your project before deployment, also use the `--prod` option to skip `devDependencies` installation. ```sh @@ -38,6 +40,7 @@ Usage in a docker image. After building everything in your monorepo, do this in ```dockerfile title="Dockerfile" # syntax=docker/dockerfile:1.4 +# The workspace image must use WORKDIR /app FROM workspace as pruned RUN pnpm --filter --prod deploy pruned @@ -91,11 +94,8 @@ Since v12.16.0, it checks the source workspace lockfile against [`minimumRelease ## What the deployed project gets -Since v12.7.0: - * The `packageManager` and `devEngines.packageManager` fields of the workspace - root `package.json` are not copied into the deployed `package.json`. Versions - v12.7.0 through v12.8.x copied them. + root `package.json` are not copied into the deployed `package.json`. * The virtual store is placed at [`virtualStoreDir`](../settings/node-modules.md#virtualstoredir), resolved against the deploy directory. With the global virtual store enabled or an absolute `virtualStoreDir`, it stays at `node_modules/.pnpm`. @@ -109,12 +109,14 @@ The next `pnpm install` or `pnpm run` in that directory checks the installed dep ## Files included in the deployed project -By default, all the files of the project are copied during deployment but this can be modified in _one_ of the following ways which are resolved in order: +By default, pnpm copies the files that `pnpm pack` would include. They are selected in _one_ of the following ways, resolved in order: 1. The project's `package.json` may contain a "files" field to list the files and directories that should be copied. 2. If there is an `.npmignore` file in the application directory then any files listed here are ignored. 3. If there is a `.gitignore` file in the application directory then any files listed here are ignored. +To copy every file of the project, set [`deployAllFiles`](../settings/other.md#deployallfiles) to `true`. + ## Configuration ### forceLegacyDeploy diff --git a/pnpm/docs/cli/deprecate.md b/pnpm/docs/cli/deprecate.md index d3ae48bf32..f08176abeb 100644 --- a/pnpm/docs/cli/deprecate.md +++ b/pnpm/docs/cli/deprecate.md @@ -3,19 +3,13 @@ id: deprecate title: pnpm deprecate --- -Added in: v11.0.0 - Set a deprecation message on a published package version. Consumers running `pnpm install` will see this message when the matching version is installed. ```sh pnpm deprecate [@] ``` -To clear a deprecation message, use [`pnpm undeprecate`](#pnpm-undeprecate) or pass an empty string: - -```sh -pnpm deprecate foo@1.0.0 "" -``` +To clear a deprecation message, use [`pnpm undeprecate`](#pnpm-undeprecate). An empty message fails with `ERR_PNPM_DEPRECATE_MESSAGE_REQUIRED`. ## Examples @@ -41,15 +35,15 @@ pnpm deprecate foo "This package is no longer maintained" ### --registry <url\> -The registry to publish to. Defaults to the registry configured for the package. +The registry to write the deprecation to. Defaults to the registry configured for the package. ### --otp <code\> -When the registry requires two-factor authentication, supply the one-time password via this flag or the `PNPM_CONFIG_OTP` environment variable. +When the registry requires two-factor authentication, supply the one-time password via this flag. ## pnpm undeprecate -Remove a deprecation message from a package version. Equivalent to running `pnpm deprecate [@] ""`. +Remove a deprecation message from a package version. ```sh pnpm undeprecate [@] diff --git a/pnpm/docs/cli/dist-tag.md b/pnpm/docs/cli/dist-tag.md index 5f19df68e6..5798658f66 100644 --- a/pnpm/docs/cli/dist-tag.md +++ b/pnpm/docs/cli/dist-tag.md @@ -3,10 +3,10 @@ id: dist-tag title: pnpm dist-tag --- -Added in: v11.0.0 - Manage distribution tags for a package. Dist-tags provide human-readable aliases (like `latest`, `next`, `beta`) that point to specific package versions on the registry. +Aliases: `dist-tags` + ```sh pnpm dist-tag add @ [] pnpm dist-tag rm @@ -17,7 +17,7 @@ pnpm dist-tag ls [] ### add <pkg\>@<version\> [<tag\>] -Tag the specified version of a package with a dist-tag. If `` is omitted, the value of the [`tag`](../settings/other.md#tag) setting is used (defaults to `latest`). +Tag the specified version of a package with a dist-tag. If `` is omitted, `latest` is used. The version must be an exact semver version. A range fails with `ERR_PNPM_DIST_TAG_ADD_INVALID_VERSION`. ```sh pnpm dist-tag add foo@1.2.0 next @@ -33,7 +33,7 @@ pnpm dist-tag rm foo next ### ls [<pkg\>] -List all dist-tags for a package. If no package name is given, the dist-tags for the current package (read from the local `package.json`) are shown. +List all dist-tags for a package. `list` is accepted as an alias of `ls`. If no package name is given, the dist-tags for the current package (read from the local `package.json`) are shown. ```sh pnpm dist-tag ls foo @@ -60,4 +60,4 @@ The registry to operate on. Defaults to the registry configured for the package. ### --otp <code\> -When the registry requires two-factor authentication, supply the one-time password via this flag or the `PNPM_CONFIG_OTP` environment variable. +When the registry requires two-factor authentication, supply the one-time password via this flag. When the registry uses web-based authentication, pnpm prints a URL to open instead. Rerun the command with `--otp` once the login finishes. diff --git a/pnpm/docs/cli/docs.md b/pnpm/docs/cli/docs.md index 60955a4e35..9a67e4fc30 100644 --- a/pnpm/docs/cli/docs.md +++ b/pnpm/docs/cli/docs.md @@ -3,19 +3,23 @@ id: docs title: pnpm docs --- -Added in: v11.0.0 - Aliases: `home` Open a package's documentation (or homepage) in the browser. ```sh -pnpm docs [ ...] +pnpm docs [@] ``` -When run without arguments inside a package directory, it opens the documentation for the current project. +pnpm fetches the package's metadata from the registry. -If the package does not declare a valid `homepage`, pnpm falls back to `https://npmx.dev/package/`. +If the package does not declare a valid `homepage`, pnpm falls back to `https://npmx.dev/package/`. When no browser can be opened, pnpm prints the URL. + +## Options + +### --registry <url\> + +The registry to fetch the package's metadata from. ## Examples @@ -24,15 +28,3 @@ Open the documentation for a published package: ```sh pnpm docs lodash ``` - -Open the documentation for multiple packages at once: - -```sh -pnpm docs react react-dom -``` - -Open the documentation for the current project: - -```sh -pnpm docs -``` diff --git a/pnpm/docs/cli/doctor.md b/pnpm/docs/cli/doctor.md index bbe5b62d64..08794d17a5 100644 --- a/pnpm/docs/cli/doctor.md +++ b/pnpm/docs/cli/doctor.md @@ -3,8 +3,6 @@ id: doctor title: pnpm doctor --- -Added in: v11.14.0 - Runs diagnostics on the pnpm installation and the environment it runs in. ```sh @@ -18,7 +16,7 @@ Each check reports how to fix what it finds, and the command exits with a non-ze ✓ Install method: pnpm ✓ Global bin directory: /Users/example/Library/pnpm/bin ✓ Cache directory: /Users/example/Library/Caches/pnpm -✓ Store directory: /Users/example/Library/pnpm/store/v10 +✓ Store directory: /Users/example/Library/pnpm/store/v11 ✓ Filesystem: available: reflink, hardlink, symlink ✓ Registry connectivity: https://registry.npmjs.org/ (128ms) ✓ Install smoke test: offline "file:" install linked its dependency diff --git a/pnpm/docs/cli/env.md b/pnpm/docs/cli/env.md index 6ae3b9874b..d556f94374 100644 --- a/pnpm/docs/cli/env.md +++ b/pnpm/docs/cli/env.md @@ -5,15 +5,12 @@ title: "pnpm env " :::warning Deprecated -`pnpm env` is deprecated. Use [`pnpm runtime`](./runtime.md) instead. For example, `pnpm env use --global lts` becomes `pnpm runtime set node lts -g`. +`pnpm env` is deprecated. Use [`pnpm runtime`](./runtime.md) instead. For example, `pnpm env use --global lts` becomes `pnpm runtime set node lts -g`, and `pnpm env remove --global ` becomes `pnpm remove -g node`. ::: Manages the Node.js environment. - - - ## Commands ### use @@ -55,16 +52,6 @@ pnpm env use --global argon [codename]: https://github.com/nodejs/Release/blob/main/CODENAMES.md -### add - -Installs the specified versions of Node.js without activating them as the current version. - -Example: - -```sh -pnpm env add --global lts 18 20.0.1 -``` - ### remove, rm Removes the specified versions of Node.js. @@ -78,28 +65,20 @@ pnpm env remove --global 14.0.0 16.2.3 ### list, ls -List Node.js versions available locally or remotely. - -Print locally installed versions: +Print the Node.js versions available from the Node.js mirror that match a version range. Without a range, only the newest version is printed. ```sh pnpm env list ``` -Print remotely available Node.js versions: +Print the available Node.js v16 versions: ```sh -pnpm env list --remote -``` - -Print remotely available Node.js v16 versions: - -```sh -pnpm env list --remote 16 +pnpm env list 16 ``` ## Options ### --global, -g -The changes are made systemwide. +The changes are made systemwide. `use` and `remove` require this option. Without it, they fail with `ERR_PNPM_NOT_IMPLEMENTED_YET`. diff --git a/pnpm/docs/cli/exec.md b/pnpm/docs/cli/exec.md index 85d7420835..ae2eb58259 100644 --- a/pnpm/docs/cli/exec.md +++ b/pnpm/docs/cli/exec.md @@ -5,7 +5,7 @@ title: pnpm exec Execute a shell command in scope of a project. -`node_modules/.bin` is added to the `PATH`, so `pnpm exec` allows executing commands of dependencies. +`node_modules/.bin` is added to the `PATH`, so `pnpm exec` allows executing commands of dependencies. The name of the current package is available through the environment variable `PNPM_PACKAGE_NAME`. ## Examples @@ -40,10 +40,7 @@ pnpm exec jest -r ### --recursive, -r -Execute the shell command in every project of the workspace. - -The name of the current package is available through the environment variable -`PNPM_PACKAGE_NAME`. +Execute the shell command in every project of the workspace. The [recursive options](./recursive.md#options), such as `--workspace-concurrency`, `--[no-]sort`, and `--reverse`, apply. #### Examples @@ -81,7 +78,7 @@ lengthy build process. ### --shell-mode, -c -Runs the command inside of a shell. Uses `/bin/sh` on UNIX and `\cmd.exe` on Windows. +Runs the command inside a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. ### --report-summary diff --git a/pnpm/docs/cli/fetch.md b/pnpm/docs/cli/fetch.md index 69183ab1c9..956a3a0e61 100644 --- a/pnpm/docs/cli/fetch.md +++ b/pnpm/docs/cli/fetch.md @@ -6,15 +6,14 @@ title: pnpm fetch Fetch packages from a lockfile into virtual store, package manifest is ignored. A missing package manifest is not created. +`pnpm fetch` requires `pnpm-lock.yaml` and does not update it. When the project pins a pnpm version that commands would switch to, `pnpm fetch` also downloads that pnpm into the store, so a later `pnpm install --offline` finds it. + ## Usage scenario This command is specifically designed to improve building a docker image. -You may have read the [official guide] to writing a Dockerfile for a Node.js -app, if you haven't read it yet, you may want to read it first. - -From that guide, we learn to write an optimized Dockerfile for projects using -pnpm, which looks like +A typical Dockerfile for a project using pnpm looks like this (see also +[Working with Docker](../docker.md)): ```dockerfile title="Dockerfile" FROM ghcr.io/pnpm/pnpm:12 @@ -23,7 +22,8 @@ RUN pnpm runtime set node 22 -g WORKDIR /app -# Files required by pnpm install +# Files required by pnpm install. Leave out .pnpmfile.mjs if the project has none, +# because COPY fails on a missing source. COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .pnpmfile.mjs ./ # If you patched any package, include patches before install too @@ -58,7 +58,8 @@ RUN pnpm runtime set node 22 -g WORKDIR /app -# Files required by pnpm install +# Files required by pnpm install. Leave out .pnpmfile.mjs if the project has none, +# because COPY fails on a missing source. COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .pnpmfile.mjs ./ # If you patched any package, include patches before install too @@ -131,10 +132,10 @@ Local `file:` protocol dependencies are skipped during `pnpm fetch`, since they Only development packages will be fetched -### --prod, -P +### --prod, --production, -P Development packages will not be fetched +### --ignore-pnpmfile - -[official guide]: https://github.com/nodejs/docker-node#readme +Don't run the hooks of the [pnpmfile](../pnpmfile.md). diff --git a/pnpm/docs/cli/find-hash.md b/pnpm/docs/cli/find-hash.md index fa0d2ef27d..43c218bb22 100644 --- a/pnpm/docs/cli/find-hash.md +++ b/pnpm/docs/cli/find-hash.md @@ -9,8 +9,10 @@ This command is experimental ::: -Lists the packages that include the file with the specified hash. For example: +Lists the packages that include the file with the specified hash. The hash is either in `sha512-` form or a hex digest, as printed by [`pnpm cat-index`](./cat-index.md). For example: ```sh pnpm find-hash sha512-mvavhfVcEREI7d8dfvfvIkuBLnx7+rrkHHnPi8mpEDUlNpY4CUY+CvJ5mrrLl18iQYo1odFwBV7z/cOypG7xxQ== ``` + +Each match is printed on its own line as `@` followed by its key in the store index. diff --git a/pnpm/docs/cli/help.md b/pnpm/docs/cli/help.md index f512028104..ab2cc7cfae 100644 --- a/pnpm/docs/cli/help.md +++ b/pnpm/docs/cli/help.md @@ -9,6 +9,4 @@ Display help information about pnpm. ### --all, -a -Added in: v10.20.0 - Print all the available commands. diff --git a/pnpm/docs/cli/ignored-builds.md b/pnpm/docs/cli/ignored-builds.md index ae11f4a516..65832b8b5a 100644 --- a/pnpm/docs/cli/ignored-builds.md +++ b/pnpm/docs/cli/ignored-builds.md @@ -3,6 +3,11 @@ id: ignored-builds title: pnpm ignored-builds --- -Added in: v10.1.0 - Print the list of packages with blocked build scripts. + +The command lists two groups: + +* builds that the last install ignored automatically, read from `node_modules/.modules.yaml`. Before the first install, there is nothing to report; +* builds denied explicitly with `false` in [`allowBuilds`](../settings/build.md#allowbuilds). + +Each package is printed under the key it takes in `allowBuilds`. To approve a build, use [`pnpm approve-builds`](./approve-builds.md). diff --git a/pnpm/docs/cli/import.md b/pnpm/docs/cli/import.md index cccb744f55..a9a0ea10df 100644 --- a/pnpm/docs/cli/import.md +++ b/pnpm/docs/cli/import.md @@ -3,9 +3,19 @@ id: import title: pnpm import --- -`pnpm import` generates a `pnpm-lock.yaml` from another package manager's lockfile. Supported source files: +`pnpm import` generates a `pnpm-lock.yaml` from another package manager's lockfile. Supported source files, in the order pnpm looks for them: +* `yarn.lock` * `package-lock.json` * `npm-shrinkwrap.json` -* `yarn.lock` -Declare workspaces in [pnpm-workspace.yaml](../settings.md) before running `pnpm import`. +```sh +pnpm import +``` + +The import is not a one-to-one conversion. The versions in the source lockfile are preferred during a fresh resolution, so the result can differ where the source lockfile does not satisfy the manifests. In a workspace, the `yarn.lock` files of individual projects are read too. Dependencies that use Yarn's `patch:` protocol become [`patchedDependencies`](./patch.md#patcheddependencies) entries. + +An existing `pnpm-lock.yaml` is replaced. If the import fails, the previous file is restored. + +Without a supported lockfile, the command fails with `ERR_PNPM_LOCKFILE_NOT_FOUND`. A `yarn.lock` that cannot be parsed, including one with merge conflict markers, fails with `ERR_PNPM_YARN_LOCKFILE_PARSE_FAILED`. + +Declare workspaces in [pnpm-workspace.yaml](../workspaces.md) before running `pnpm import`. diff --git a/pnpm/docs/cli/init.md b/pnpm/docs/cli/init.md index 0caff8d267..c9d8ccaa78 100644 --- a/pnpm/docs/cli/init.md +++ b/pnpm/docs/cli/init.md @@ -3,14 +3,16 @@ id: init title: "pnpm init" --- -Create a `package.json` file. +Create a `package.json` file. If `package.json` already exists, the command fails with `ERR_PNPM_PACKAGE_JSON_EXISTS`. + +```sh +pnpm init +``` ## Options ### --bare -Added in: v10.25.0 - Creates a `package.json` with only the required fields. ### --init-type <type\> @@ -18,17 +20,19 @@ Creates a `package.json` with only the required fields. * Default: **module** * Type: **commonjs**, **module** -Set the module system for the package. +Set the module system for the package. Set [`initType`](#inittype) to change the default. ### --init-package-manager -Pin the project to a pnpm version. +* Default: **true** -Since v11, the pin is written as a [`devEngines.packageManager`](../package_json.md#devenginespackagemanager) entry, so the resolved version is captured in `pnpm-lock.yaml`. Since v11.23.0 it is also written to the legacy `packageManager` field, as an exact version rather than a `^` range, because Corepack reads only `packageManager` and accepts nothing but an exact version. +Pin the project to a pnpm version. Set [`initPackageManager`](#initpackagemanager) to change the default. -Since v11.25.0, the pin can be newer than the pnpm that ran the command, so a project scaffolded by an outdated pnpm no longer inherits that staleness through its own pin ([#7490](https://github.com/pnpm/pnpm/issues/7490)). pnpm looks up the version published under the `latest` tag on the package-manager registries, and pins it **only when it is newer than the running version**. The lookup raises the pin, it never lowers it. +The pin is written as a [`devEngines.packageManager`](../package_json.md#devenginespackagemanager) entry, so the resolved version is captured in `pnpm-lock.yaml`. It is also written to the `packageManager` field as an exact version, because Corepack reads only `packageManager` and accepts nothing but an exact version. -Two things follow from that. `latest` is a tag rather than "the newest release", so the pin tracks whichever line the tag points at: with `latest` on the pnpm 12 line, a pnpm 11.25 running `pnpm init` pins the newest pnpm 12, while a pnpm 12 newer than the `latest` tag pins itself (so does anything older than 11.25, which predates the lookup). And when the lookup cannot answer (no network, an unreachable or slow registry, `--offline`, or a `latest` that [`minimumReleaseAge`](../settings/dependency-resolution.md#minimumreleaseage) or [`trustPolicy`](../settings/dependency-resolution.md#trustpolicy) rejects), the running version is pinned, as before. The lookup never fails or hangs the command. +pnpm looks up the version published under the `latest` tag on the package-manager registries, and pins it **only when it is newer than the running version**. Otherwise the running version is pinned. The lookup raises the pin, it never lowers it. + +`latest` is a tag rather than "the newest release", so the pin tracks whichever line the tag points at. A pnpm newer than the `latest` tag pins itself. When the lookup cannot answer (no network, an unreachable or slow registry, `--offline`, or a `latest` that [`minimumReleaseAge`](../settings/dependency-resolution.md#minimumreleaseage) or [`trustPolicy`](../settings/dependency-resolution.md#trustpolicy) rejects), the running version is pinned. The lookup never fails or hangs the command. Inside a workspace subpackage this flag has no effect. The pin is only added to the workspace root's `package.json`, and the subpackage follows it. Pass `--no-init-package-manager` to scaffold a manifest with no pin at all. @@ -36,6 +40,20 @@ Inside a workspace subpackage this flag has no effect. The pin is only added to These settings fill in fields of the scaffolded `package.json`. They may be set in `pnpm-workspace.yaml`, in the [global configuration file](./config.md), or through the environment as `PNPM_CONFIG_INIT_VERSION` and friends. +### initPackageManager + +* Default: **true** +* Type: **Boolean** + +Whether `pnpm init` pins the project to a pnpm version. Same as the [`--init-package-manager`](#--init-package-manager) flag. + +### initType + +* Default: **module** +* Type: **commonjs**, **module** + +The module system written into the new `package.json`. Same as the [`--init-type`](#--init-type-type) flag. + ### initVersion * Default: **1.0.0** diff --git a/pnpm/docs/settings.md b/pnpm/docs/settings.md index 51d432b3a5..5291535cd0 100644 --- a/pnpm/docs/settings.md +++ b/pnpm/docs/settings.md @@ -388,7 +388,7 @@ These settings are configured in `pnpm-workspace.yaml` as well, but are document * [patchedDependencies](./cli/patch.md#patcheddependencies) * [pnpmfile](./pnpmfile.md#pnpmfile), [globalPnpmfile](./pnpmfile.md#globalpnpmfile) and [ignorePnpmfile](./pnpmfile.md#ignorepnpmfile) * [audit.level](./cli/audit.md#auditlevel), [audit.ignore](./cli/audit.md#auditignore) and [audit.ignorePrune](./cli/audit.md#auditignoreprune) -* [initVersion](./cli/init.md#initversion), [initLicense](./cli/init.md#initlicense) and [initAuthorName / initAuthorEmail / initAuthorUrl](./cli/init.md#initauthorname-initauthoremail-initauthorurl) +* [initPackageManager](./cli/init.md#initpackagemanager), [initType](./cli/init.md#inittype), [initVersion](./cli/init.md#initversion), [initLicense](./cli/init.md#initlicense) and [initAuthorName / initAuthorEmail / initAuthorUrl](./cli/init.md#initauthorname-initauthoremail-initauthorurl) * [legacyDirFiltering](./filtering.md#legacydirfiltering) * [concurrencyGroups](./workspace-task-orchestration.md#concurrencygroups) * [tasks](./workspace-task-orchestration.md#configure-task-dependencies), [pipelines](./cli/pipeline.md#pipelines) and [pipelineBase](./cli/pipeline.md#pipelinebase) diff --git a/pnpm11/docs/cli/audit.md b/pnpm11/docs/cli/audit.md index 125bc06499..46a0d18d6f 100644 --- a/pnpm11/docs/cli/audit.md +++ b/pnpm11/docs/cli/audit.md @@ -44,7 +44,7 @@ The command exits with code `1` if any package has an invalid signature, or if a ### --audit-level <severity\> -* Type: **low**, **moderate**, **high**, **critical** +* Type: **info**, **low**, **moderate**, **high**, **critical** * Default: **low** Only print advisories with severity greater than or equal to ``. @@ -63,7 +63,7 @@ When [`minimumReleaseAge`](../settings/dependency-resolution.md#minimumreleaseag Added in: v11.0.0 -Review the advisories selected by `--fix` and pick which ones to apply. Only usable together with `--fix`. +Review the advisories selected by `--fix` and pick which ones to apply. Implies `--fix=override` when `--fix` is not given. ### --json @@ -120,7 +120,7 @@ audit: ### audit.level * Default: **low** -* Type: **low**, **moderate**, **high**, **critical** +* Type: **info**, **low**, **moderate**, **high**, **critical** Only print advisories with severity greater than or equal to this level. Same as the [`--audit-level`](#--audit-level-severity) flag. diff --git a/pnpm11/docs/cli/change.md b/pnpm11/docs/cli/change.md index 98b49e558b..9b95787ca3 100644 --- a/pnpm11/docs/cli/change.md +++ b/pnpm11/docs/cli/change.md @@ -75,13 +75,13 @@ Private packages (`"private": true`) are never checked against the registry for Added in: v11.26.0 -Validate the versions committed in the workspace against the [epic](../versioning.md#epics) bands and [fixed group](../versioning.md#fixed-groups) lockstep declared in `pnpm-workspace.yaml`. +Validate the pending change intents, and check the versions committed in the workspace against the [epic](../versioning.md#epics) bands and [fixed group](../versioning.md#fixed-groups) lockstep declared in `pnpm-workspace.yaml`. ```sh pnpm change check ``` -Unlike `pnpm change status`, which reports the release the pending intents produce, `check` looks only at the versions already in the manifests. It reads no intents, so it is the step to run on every pull request: a package whose version drifted out of its epic's band, or out of step with its fixed group, fails the command. Every violation is listed, including ones in packages the current release does not touch. +Unlike `pnpm change status`, which reports the release the pending intents produce, `check` plans the release from the pending intents without reporting it, and checks only the versions already in the manifests. An intent that would fail at release time, such as one naming a package outside the workspace, fails the command. Run it on every pull request: a package whose version drifted out of its epic's band, or out of step with its fixed group, fails the command. Every violation is listed, including ones in packages the current release does not touch. ## Options diff --git a/pnpm11/docs/cli/deploy.md b/pnpm11/docs/cli/deploy.md index 47f6fde864..2a18e508b4 100644 --- a/pnpm11/docs/cli/deploy.md +++ b/pnpm11/docs/cli/deploy.md @@ -87,12 +87,14 @@ By default, `pnpm deploy` will try creating a dedicated lockfile from a shared l ## Files included in the deployed project -By default, all the files of the project are copied during deployment but this can be modified in _one_ of the following ways which are resolved in order: +By default, pnpm copies the files that `pnpm pack` would include. They are selected in _one_ of the following ways, resolved in order: 1. The project's `package.json` may contain a "files" field to list the files and directories that should be copied. 2. If there is an `.npmignore` file in the application directory then any files listed here are ignored. 3. If there is a `.gitignore` file in the application directory then any files listed here are ignored. +To copy every file of the project, set [`deployAllFiles`](../settings/other.md#deployallfiles) to `true`. + Since v11.28.0, symlinks that point to files or directories included in the deployed project are kept as symlinks. ## The deployed project diff --git a/pnpm11/docs/cli/deprecate.md b/pnpm11/docs/cli/deprecate.md index d3ae48bf32..fc05f677af 100644 --- a/pnpm11/docs/cli/deprecate.md +++ b/pnpm11/docs/cli/deprecate.md @@ -11,11 +11,7 @@ Set a deprecation message on a published package version. Consumers running `pnp pnpm deprecate [@] ``` -To clear a deprecation message, use [`pnpm undeprecate`](#pnpm-undeprecate) or pass an empty string: - -```sh -pnpm deprecate foo@1.0.0 "" -``` +To clear a deprecation message, use [`pnpm undeprecate`](#pnpm-undeprecate). An empty message fails with `ERR_PNPM_DEPRECATE_MESSAGE_REQUIRED`. ## Examples @@ -41,15 +37,15 @@ pnpm deprecate foo "This package is no longer maintained" ### --registry <url\> -The registry to publish to. Defaults to the registry configured for the package. +The registry to write the deprecation to. Defaults to the registry configured for the package. ### --otp <code\> -When the registry requires two-factor authentication, supply the one-time password via this flag or the `PNPM_CONFIG_OTP` environment variable. +When the registry requires two-factor authentication, supply the one-time password via this flag. ## pnpm undeprecate -Remove a deprecation message from a package version. Equivalent to running `pnpm deprecate [@] ""`. +Remove a deprecation message from a package version. ```sh pnpm undeprecate [@] diff --git a/pnpm11/docs/cli/dist-tag.md b/pnpm11/docs/cli/dist-tag.md index 57ffd27ded..fe7c50fa5e 100644 --- a/pnpm11/docs/cli/dist-tag.md +++ b/pnpm11/docs/cli/dist-tag.md @@ -17,7 +17,7 @@ pnpm dist-tag ls [] ### add <pkg\>@<version\> [<tag\>] -Tag the specified version of a package with a dist-tag. If `` is omitted, the value of the [`tag`](../settings/other.md#tag) setting is used (defaults to `latest`). +Tag the specified version of a package with a dist-tag. If `` is omitted, `latest` is used. The version must be an exact semver version. A range fails with `ERR_PNPM_DIST_TAG_ADD_INVALID_VERSION`. ```sh pnpm dist-tag add foo@1.2.0 next @@ -47,4 +47,4 @@ The registry to operate on. Defaults to the registry configured for the package. ### --otp <code\> -When the registry requires two-factor authentication, supply the one-time password via this flag or the `PNPM_CONFIG_OTP` environment variable. +When the registry requires two-factor authentication, supply the one-time password via this flag. diff --git a/pnpm11/docs/cli/docs.md b/pnpm11/docs/cli/docs.md index 60955a4e35..98d2b95909 100644 --- a/pnpm11/docs/cli/docs.md +++ b/pnpm11/docs/cli/docs.md @@ -10,10 +10,10 @@ Aliases: `home` Open a package's documentation (or homepage) in the browser. ```sh -pnpm docs [ ...] +pnpm docs [@] ``` -When run without arguments inside a package directory, it opens the documentation for the current project. +pnpm fetches the package's metadata from the registry. If the package does not declare a valid `homepage`, pnpm falls back to `https://npmx.dev/package/`. @@ -24,15 +24,3 @@ Open the documentation for a published package: ```sh pnpm docs lodash ``` - -Open the documentation for multiple packages at once: - -```sh -pnpm docs react react-dom -``` - -Open the documentation for the current project: - -```sh -pnpm docs -``` diff --git a/pnpm11/docs/cli/env.md b/pnpm11/docs/cli/env.md index 6ae3b9874b..1f7c716ce7 100644 --- a/pnpm11/docs/cli/env.md +++ b/pnpm11/docs/cli/env.md @@ -55,16 +55,6 @@ pnpm env use --global argon [codename]: https://github.com/nodejs/Release/blob/main/CODENAMES.md -### add - -Installs the specified versions of Node.js without activating them as the current version. - -Example: - -```sh -pnpm env add --global lts 18 20.0.1 -``` - ### remove, rm Removes the specified versions of Node.js. @@ -78,28 +68,20 @@ pnpm env remove --global 14.0.0 16.2.3 ### list, ls -List Node.js versions available locally or remotely. - -Print locally installed versions: +Print the Node.js versions available from the Node.js mirror that match a version range. Without a range, only the newest version is printed. ```sh pnpm env list ``` -Print remotely available Node.js versions: +Print the available Node.js v16 versions: ```sh -pnpm env list --remote -``` - -Print remotely available Node.js v16 versions: - -```sh -pnpm env list --remote 16 +pnpm env list 16 ``` ## Options ### --global, -g -The changes are made systemwide. +The changes are made systemwide. `use` and `remove` require this option. Without it, they fail with `ERR_PNPM_NOT_IMPLEMENTED_YET`.