Best practices for applying a patch file in Drupal

In order to fix bugs, improve performance or add functions, applying a patch can be very useful, and even indispensable. Nonetheless, modifying the code is not much of a trivial matter, for it is necessary to follow basic guidelines to guarantee a clean code, thus avoiding any possible mishap, such as new bugs, or dysfunctions that could result in the waste of valuable time in terms of development. In the following post, we have emphasized some practical guidelines that will allow you to properly apply a Drupal patch.

Reminder: What is a patch file ?

A patch file (or corrective file) is a text file with a .patch extension that includes a set of formatted codes extracted using, for instance, the git diff  command. With a patch file it is possible to introduce modifications to the corecode, to a module or a theme, thus fixing bugs, optimizing performance, modifying or adding new functions. Patchs make development easier. Instead of supplying a replacement file, that consists of thousands of lines of code, the patch file only includes the introduced changes. In fact, the patch file is a list of the changes made to a file which can be used to recreate the same change on another copy of the file 

Ground rules

There are several simple ground rules to follow to make the patching process easier, such as:

• 1. To organize patches : unless you have a backup of the site in production, it is not recommended to apply a patch directly on the site under construction, given than a patch could lead to the loss of data or to the website’s instability. It is however recommended to download a backup version of the website in production, to make a copy of it and to test the second backup version to make sure that everything is properly working as expected. This is how it is possible to test the patch results, and then to import the changes to the website in production.
• 2. To organize patches : to ensure the visibility of changes, it is recommended to allocate a patch to each introduced modification. Whether fixing bugs, boosting performance or correcting codes, to each modification should be assigned a specific patch.
• 3. End of line character and directory separators : On Windows for example, it is necessary to use end of line characters Unix (LF) and directory separators (/).

How to apply a patch file

There are different ways to apply a patch file, whether manually or automatically.
Before that, it is important to identify the directory you are currently in. Patch files are created in general with relevance to the project’s root directory. It can be Drupal’s root directory or that of a contributed module.

1. Have a backup of your production site, and check the installation directory
As mentioned earlier, you have to apply the patch on a backup of your production site. It can be a local site or a site on a development server of the relevant production site.
You have to check the installation directory. If you apply a patch on a Drupal code, you have to navigate toward the Drupal directory using the cd command of your terminal.
This also applies on a module or a theme; you have to navigate toward the relevant directory.

2. Download the patch file
To apply the patch, the patch file must be in the project. Therefore, navigate to the directory and download the patch file that you’re directly interested in from the terminal by using curl or wget commands (from linux for instance):

- curl -O <https://www.drupal.org/XXXX.patch>;
- wget -O <https://www.drupal.org/XXXX.patch>.

The to-be-patched file could be in a subdirectory. However, it is necessary to apply the patch to the root directory.

3. Apply the patch.
Several commands are used in applying a patch. You can choose, according to the environment, one of the following:

• If you use Git to apply a patch : You can apply the command git apply <option><path/file.path. You can use the different options of the command according to each situation: -v is a signal of the patch’s progression with additional information, -index allows to track modifies folders, and -3 to reverse a patch if it is malfunctioning. You can find below the list of patch options using Git..
• If you are not using Git to apply a patch, you can issue the command -p1 < path/file.patch. You will have several command options such as: -p that indicates how many directory prefixes there are to apply the patch and -p0 in case the patch is not working.
• In case your patch is in the same directory as the file to be patched, you can apply the command < fichier.patch.

How to reverse a patch

You might need to reverse a patch if :

• You have tested a specific patch patch ;
• The patch has broken the code ;
• You are updating the same patch.

It is possible to reverse the patch using the same command issued to apply a patch to a codebase, but this time using an additional command. For instance :

• With Git, to reverse a patch it is necessary to use the command git apply -R path/file.patch.
• In an environment different than Git, it is possible to use the command patch -p1 -R < path/file.patch (if you had used the -p1 command to apply the patch).