Applying a patch in a feature branch

Last updated on
20 December 2023

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

  1. 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.
  2. 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:

  1. 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"
              }
            },
            ...
        }
        ...
    }
  2. Run composer update drupal/projectname to update the lock file.
  3. 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 by git 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).

Tags

Help improve this page

Page status: No known problems

You can: