Patch
In Drupal, a patch is a diff file you apply with Git, the patch command or Composer to change core or module code you do not maintain.
A patch is a plain text file that records the differences between two versions of source code, line by line. In Drupal, a patch carries a bug fix or improvement from a Drupal.org issue. A developer can apply the file to Drupal core or a contributed module on their own site, before the fix ships in an official release.
How patches work in Drupal 11
A patch belongs to an issue, where contributors review it. Drupal.org now marks patches as deprecated and sends contributors to merge requests instead. A merge request on the project's GitLab can still be downloaded as a patch file, so you can get a patch from either route.
You can apply a patch by hand. git apply -v file.patch applies it inside a Git checkout, and patch -p1 < file.patch works without Git. If the patch does not apply cleanly, Drupal.org lists the usual causes: line-ending problems (Unix style is expected), a base version that is out of date, or a mistake in the patch. The patch command can apply most hunks and leave the rejected ones in .rej files for you to fix.
On a Composer-managed site you do not edit vendor code by hand. The cweagans/composer-patches plugin, which the Drupal.org guide uses in version 2, reads a list of patches from composer.json and applies them to the named packages. In that version, composer patches-relock rebuilds patches.lock.json and composer patches-repatch reinstalls the patched packages.
Example
Install the plugin with composer require cweagans/composer-patches:~2.0 --update-with-dependencies. Then list the patch under extra, keyed by a description that names the issue:
"extra": {
"composer-exit-on-patch-failure": true,
"patchLevel": {
"drupal/core": "-p2"
},
"patches": {
"drupal/core": {
"Issue #NNNNNNN: Short title of the issue": "patches/core-short-title.patch"
}
}
}The file sits in a patches/ folder in your own repository.
Common mistakes
- Using the wrong patch level. On the recommended webroot structure, where
composer.jsonsits one level above the webroot, a core patch needs-p2. The guide lists each patched contributed module with-p1underpatchLevel, which helps you check that the patches apply. - Forgetting why a patch is there. Without the issue number in the description, nobody can tell later whether the fix has reached a release.
- Ignoring patches during updates. A patch was made against one version of the code. After you update the package, check that it still applies and whether the issue is fixed in the new release.
- Patching
.info.ymlfiles without a workaround. The Drupal.org guide says these need one and links to an explanation.
For marketing and content teams
A patch changes code that came from Drupal.org, so updates of that package need a developer to check it. Ask your team for the list of patches the site carries. In the setup from the Drupal.org guide, it is in composer.json under extra.patches. Each entry has a description, and the guide's example puts the issue number in it, so you can follow the issue on Drupal.org and plan the day the patch can go.