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.
112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
---
|
|
id: patch
|
|
title: "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`](#--edit-dir-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:
|
|
|
|
```sh
|
|
pnpm patch <pkg name>@<version>
|
|
```
|
|
|
|
[`patchedDependencies`]: #patcheddependencies
|
|
|
|
:::note
|
|
|
|
To change a package's dependencies, don't use `pnpm patch` to modify its `package.json`! Use [overrides] or a [package hook] instead.
|
|
|
|
:::
|
|
|
|
[overrides]: ../settings/dependency-resolution.md#overrides
|
|
[package hook]: ../pnpmfile#hooksreadpackagepkg-context-pkg--promisepkg
|
|
|
|
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/0GjLqRGRbcY" title="The pnpm patch command demo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
|
|
|
|
## 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:
|
|
|
|
[pnpm patch-commit]: ./patch-commit.md
|
|
|
|
* **Keys**: Package names with an exact version, a version range, or just the name.
|
|
* **Values**: Relative paths to patch files.
|
|
|
|
Example:
|
|
|
|
```yaml title="pnpm-workspace.yaml"
|
|
patchedDependencies:
|
|
express@4.18.1: patches/express@4.18.1.patch
|
|
```
|
|
|
|
Dependencies can be patched by version range. The priority order is:
|
|
|
|
1. Exact versions (highest priority)
|
|
2. Version ranges
|
|
3. Name-only patches (applies to all versions unless overridden)
|
|
|
|
Example:
|
|
|
|
```yaml title="pnpm-workspace.yaml"
|
|
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.patch` is applied to `foo@2.1.0`.
|
|
* `patches/foo-2.patch` applies to all foo versions matching `^2.0.0`, except `2.1.0`.
|
|
* `patches/foo-1.patch` applies 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:
|
|
|
|
```yaml title="pnpm-workspace.yaml"
|
|
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.
|
|
|
|
```yaml title="pnpm-workspace.yaml"
|
|
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.
|
|
|
|
:::
|