Zoltan Kochan
cb3f29bc0a
Part of pnpm/tasks#191. Wrong claims, fixed in the v12 docs and, where the same text is wrong for v11, in the v11 docs: - logout: drop the nonexistent --scope option. - patch: the edit dir is node_modules/.pnpm_patches/<name>@<version>; drop the "*" special case. - patch-commit: fix the ---patches-dir heading. - prefix: describe the real marker walk instead of "closest package.json". - setup: setup installs pnpm as a global package and writes pn/pnpx/pnx. - start, test: "run start" and "run test" are not aliases. - unlink: drop the system-wide and link --global wording. - unpublish: a package name is required; --otp has no env var; --registry wording. - update: --depth is dependency depth, not directory depth. - version: --tag-version-prefix defaults to the tagVersionPrefix setting. - view: the first argument is always the package. - why: drop --global and --only-projects; --exclude-peers has no effect; --prod includes optionalDependencies. - install: recursiveInstall spelling; replace the stale ci-info snippet. - v12 only: pack-app runtime default and builder download, pnx provisioning list and cmd.exe typo, tasks sample priority. Missing flags, settings, and error codes on the v12 pages: install (about twenty flags), lane, licenses, link, list, outdated, owner, pack-app path rules, pack, patch, patch-remove, peers, permissions, ping, pipeline, pm, pnx, prune, publish, rebuild, recursive, remove, repo, root, run, runtime, sbom, search, self-update, set-script, setup, shim, stage, star, start, store, tasks, team, test, token, unlink, unpublish, update, version, view, why, with. Stale history on the v12 pages: removed "Added in" markers older than v12 and rewrote "Since v11.x" and "In v11" sentences as current behavior (login, logout, licenses, link, outdated, patch, pnx, publish, runtime, sbom, self-update, setup, update, and others). Review follow-up: patch's default edit directory is named after the argument as typed (both versions); self-update installs the unscoped package only for pnpm 12 and newer; only --no-bail is restricted; npm_package_* covers name, version, config, engines and bin; prefix -g prints the parent of root -g; --optional no longer claims to override --no-optional.
3.4 KiB
id, title
| id | title |
|---|---|
| patch | pnpm patch <pkg> |
Prepare a package for patching (inspired by a similar command in Yarn).
This command extracts the package to node_modules/.pnpm_patches/<pkg>, where <pkg> is the argument as given, such as foo or foo@1.0.0 (or the --edit-dir), a directory you can edit at will.
Once you're done with your changes, run pnpm patch-commit <path> (with <path> being the directory you received) to generate a patchfile and register it into your top-level manifest via the patchedDependencies field.
Usage:
pnpm patch <pkg name>@<version>
:::note
To change a package's dependencies, don't use pnpm patch to modify its package.json! Use overrides or a package hook instead.
:::
Options
--edit-dir <dir>
The package that needs to be patched will be extracted to this directory.
--ignore-existing
Ignore existing patch files when patching.
Configuration
patchedDependencies
This field is added/updated automatically when you run pnpm patch-commit. It defines patches for dependencies using a dictionary where:
- Keys: Package names with an exact version, a version range, or just the name.
- Values: Relative paths to patch files.
Example:
patchedDependencies:
express@4.18.1: patches/express@4.18.1.patch
Dependencies can be patched by version range. The priority order is:
- Exact versions (highest priority)
- Version ranges
- Name-only patches (applies to all versions unless overridden)
Example:
patchedDependencies:
foo: patches/foo-1.patch
foo@^2.0.0: patches/foo-2.patch
foo@2.1.0: patches/foo-3.patch
patches/foo-3.patchis applied tofoo@2.1.0.patches/foo-2.patchapplies to all foo versions matching^2.0.0, except2.1.0.patches/foo-1.patchapplies to all other foo versions.
Avoid overlapping version ranges. If you need to specialize a sub-range, explicitly exclude it from the broader range.
Example:
patchedDependencies:
# Specialized sub-range
"foo@2.2.0-2.8.0": patches/foo.2.2.0-2.8.0.patch
# General patch, excluding the sub-range above
"foo@>=2.0.0 <2.2.0 || >2.8.0": patches/foo.gte2.patch
In most cases, defining an exact version is enough to override a broader range.
allowUnusedPatches
Added in: v10.7.0 (Previously named allowNonAppliedPatches)
- Default: false
- Type: Boolean
When true, installation won't fail if some of the patches from the patchedDependencies field were not applied.
patchedDependencies:
express@4.18.1: patches/express@4.18.1.patch
allowUnusedPatches: true
:::note
In v11, patch application failures always throw an error. The ignorePatchFailures setting has been removed. When multiple patches in a group are applied, a failure in one does not prevent the rest from being attempted; all patch errors are reported together at the end.
:::