Applying a patch in a feature branch
This page outlines a workflow for downloading and applying patches to a local workspace, based on local "topic branches".
Note: You can also use the drupalorg-cli tool to create an issue branch and apply the patch.
Prepare the local repository
- Follow the steps on Cloning a Drupal git repository to make a local copy of the repository or update your existing local copy to the latest version.
- Create a local "feature branch" for the issue you're working on.
git checkout -b [issue-number]-[short-description] # e.g. 123456-some-bug
Obtain and apply a patch file
Download the patch file from the issue (see Downloading a patch file), and apply the code changes in the patch to your working directory.
There are several command variations you can use (the following commands assume you're in a terminal window in the project's root directory):
- Download the patch file manually from the issue (click the link and save to your local computer). Then:
git apply --index -v [patch-name].patch
- Use
curl
to download the file, then use git to apply the patch:
curl -O https://www.drupal.org/files/[patch-name].patch git apply --index [patch-name].patch
Or in a single line:
curl https://www.drupal.org/files/[patch-name].patch | git apply --index -
- Use
wget
to download the file, then use git to apply the patch:
wget https://www.drupal.org/files/[patch-name].patch git apply --index [patch-name].patch
Or in a single line:
wget -q -O - https://www.drupal.org/files/[patch-name].patch | git apply --index -
- Set up a git alias to download and apply the patch in one command. In
~/.gitconfig
:
[alias] # Download and apply a patch. a = apply --index ac = "!f() { curl $@ | git a; }; f"
Then run
git ac https://www.drupal.org/patch-url
Also, there are many command-line arguments to the git apply
command. One useful one is -v
, which gives a more verbose output:
git apply -v patchname.patch
See the git apply documentation for more information.
If the patch does not apply, and you perhaps are getting a "Skipped patch ..." message, try the patch
command (see "Footnotes" below for more) or reroll the patch:
patch -p1 < [patch-name].patch
Reverse the patch, by adding the -R
parameter:
patch -R -p1 < [patch-name].patch
Commit the patch
If you are planning to work on improving the patch, the next step is to commit the original patch to your local repository branch:
git add FILESAFFECTED
git commit -m “Patch COMMENTNUMBER by OTHERPERSON”
When you're done: Code cleanup
After you have finished testing the patch, you'll want to get your repository back to a "clean" state:
- Use this command to revert the patch:
git apply -R path/file.patch
- Use this command to delete the feature branch you created:
git branch -D [branch-name]
Composer
git.drupalcode.org: The contents of merge request patch file will change as commits are pushed!
This means that you will get the latest version of the code from an issue. So, it brings a security risk because any new commit to the issue’s branch will be automatically deployed to your site when composer runs.
It's strongly recommended to lock the patch file versions on production sites. To do so you must download the patch file and use it in composer from a local directory. If you use the URL to the Gitlab MR directly, your codebase will change without warning, as people work on the merge request.
If you are maintaining the code for a Drupal site with Composer, and one of the projects needs to have a patch:
- Add the URL of the patch file to the composer.json file:
{ ... "extra": { ... "patches": { "drupal/myproject": { "#12345 - Fix some issues": "https://www.drupal.org/files/issues/2021-06-21/MyProjectPatch-12345-28.patch" } }, ... } ... }
- Run
composer update drupal/projectname
to update the lock file. - Verify that the patch applied cleanly and the functionality is working as expected.
* In order to apply patches using composer you need to install composer-patches project:
composer require cweagans/composer-patches:~1.0 --update-with-dependencies
Footnotes
- You can also apply patches with
git am
.git am
is also useful if the patches were created bygit format-patch
. - The
patch
command is useful for patches that don't apply, as it will apply most of the patch and then you may be able to look at the.rej
file it creates for the rejected "hunks" of the patch, and fix them manually. If it is too complicated, try rerolling the patch. - Since the patch files themselves should not ever be added to the project, you may wish to tell Git to ignore them by adding the line
*.patch
to the.git/info/exclude
file in the project, or to a global ~/.gitignore file. Alternatively, you can download them to a different location. - If you have errors when you try to apply a patch, check for the following:
- The patch may have the wrong end-of-line encoding. Our standard is to use Unix-style end-of-line encoding (see Patch Guidelines).
- The patch may not match the latest development version. See Rerolling patches for how to merge in later changes.
- If the automatic testing also flagged the patch as not applying at the time it was created, the developer who created the patch may have made an error (such as not using Git or not using the latest development version).
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion