HowTo: How to apply a patch to a contributed module - Beginner's version (Windows)

Last updated August 17, 2010. Created by john.kenney on November 1, 2009.
Edited by PB1, vegantriathlete. Log in to edit this page.

This page answers the question: How do I apply a patch to a module?

Much of the existing patching documentation on how to apply a patch (see links below) is extremely cryptic and assumes more technical knowledge than some aspiring, but worthy patchers have.

But even those with somewhat lesser technical know-how may want (or need) to apply a module patch from time to time. For instance, there is an important feature that has been developed for your module, but it is still not available in an official release. Or, you have reported a bug in the module, and the module maintainer has asked you to test a patch that fixes it.

This how-to provides a detailed step-by-step guide to applying patches to contributed modules. It is designed for first-time patchers and/or less technical folks who have the need to apply a patch. The how-to specifically relates to applying patches on Windows machines, but the basic information and steps may be helpful for others. It is also written for a localhost (i.e., a development environment, and the particular directory structure follows XAMPP's naming) configuration, but the same steps would apply to a hosted environment as well, if it is a Windows environment. You'll just need to switch the location where some of the steps are executed.

Caution: Patches can break, and even permanently damage your system. Unless you know what you are doing, please only apply patches that are well proven by the Drupal community and/or patches you've been asked by the module maintainer to test.

This guide can't cover every possible situation that you are likely to encounter. You need to develop a solid general understanding of what a patch is and what happens when you apply it. You should always first apply patches to a development environment. Take the time to learn how to set up a development environment. Also, make sure to read through and understand the entire set of instructions provided here before you actually follow the steps.

You can tell a module patch has been "well proven by the community" by either:

• seeing a notation in the issue queue which states the thread has been "reviewed & tested by the community"

and/or

• reading the associated issue thread and seeing that many people have confirmed successful application of the patch.

If you find a patch that has not been validated by seasoned Drupalers, do not install it, as it may break your system.

What is a Patch?

A "patch file" is a specific kind of file that contains code that is used to modify one or more existing files for a Drupal module. The "patch" command is a Linux command that performs the patching operation. Patching and patch files are not unique to Drupal; they are widely used to modify all sorts of files.

In the context of patch files for Drupal modules, the patch file is normally intended to change existing .module files. The patch file contains lines of code that are either being added to the .module file (indicated by a "+") or being deleted from the .module file (indicated by a "-" sign). As well, each block of lines with +/- signs is preceded and followed by unmarked reference lines that serve to tell the patching program where to insert/delete the lines. If you look at a typical patch file, you will see several such groups of lines - beginning and ending reference lines, plus variable numbers of +/- lines. Each such grouping is called a "hunk." If the patch fails to apply, you will often see "hunk failed" errors.

Patching does not happen in Drupal per se, nor does it happen in Windows. Rather, it is done in Linux (or other Unix flavor) or a Linux emulator. The UnxUtils package also provides a Windows native implementation of the patch command.

Because the "patch" command is a Unix command—not a Drupal command or a Windows command—Windows users need to utilize a tool that allows them to run Unix commands. There are several tools for doing this. This how-to assumes you are using a Linux emulator called Cygwin to apply patches, but you could use one of the other tools instead.

Additional Drupal patching sources

Before trying to apply a patch, we recommend you read some of the other materials available on drupal.org to help you more fully understand the process. While the patching process itself is quite simple, the changes that occur from applying the patch can be quite complex. Applying patches can be a bit risky, so you want to avoid mistakes and understand what is happening when you apply patches. There is a procedure that one is "supposed" to follow to create a patch. Be aware that the procedure may have been followed properly and it may not have. Also, the procedure allows for two different ways to "roll" the patch. This is why it was recommended earlier that you apply only the patches that have already been "well-proven."

• Applying patches - This is the Intro page to the existing materials on patching. Most pages here are written for a fairly technical audience.
• Applying patches manually - This is interesting to read because it helps explain what is actually in a "patch" file. Furthermore, for simple patches, doing them manually might be just as fast as the steps below. If you are going to apply patches manually, you will definitely need to use a plain text editor, such as Notepad++.
• Apply patches on Windows - This is a cryptically written series of pages for using various tools - Cygwin, GnuWin32, and UnxUtils - for patching.
• Apply patches on Mac OS - This material looks just as cryptic as the Windows information.
• Applying patches to core - This provides a link to a useful video that's definitely worth watching, since patching modules and patching core is procedurally about the same. Be aware: the video flashes through the command line steps that are likely to be the most vexing to first timers and less technical folks.

Prerequisite - Install Cygwin

Before you can apply a patch, you need to install Cygwin on your Windows machine. Cygwin is an open source program that is widely used and very safe. It will work on most any Windows machine, including Vista and 64 bit versions.

As described on the Cygwin home page:

Cygwin is a Linux-like environment for Windows. It consists of two parts:

• A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing substantial Linux API functionality.
• A collection of tools which provide Linux look and feel.

Visit the Cygwin website to learn more. You can run or download the Cygwin setup.exe file here.

Cygwin's site provides great information on how to install it. However, if you want to find more information, you may conduct a search with Google or your preferred search engine using keywords "install cygwin." Also, these posts/videos by Drupalers may be of help: Lullabot cygwin installation video (this is for XP, but same approach works with Vista, etc.) and a post at RandyFay.com.

Cygwin Basics

Once you have installed Cygwin, you will be able to open it like a normal program. However, the program has a cryptic interface and doesn't do anything unless you give it commands. In the hands of novices, using it is like stepping back 20 years on a PC, but it gets the job done (and is actually very powerful if you know what you are doing).

The following commands should be enough to get your patch installed:

• cd .. - moves you up a level in the directory ('cd' means 'change directory')
• cd folder_name - moves you down 1 level into folder_name
• cd folder_x/folder_y - moves you down 2 levels into that folder_y (you can drop down however many levels you want)
• cd c:/folder_x/folder_y - moves from anywhere to folder_y on the specified path
• cd - returns you to your default cygwin directory
• ls - lists the folders and files in the directory you are currently in
• logout - this is how you get out of cygwin's terminal emulation window

The key initial challenge with cygwin is figuring out where you are within your file directory. Cygwin does give you a hint of where you are with the line it displays above your prompt. To apply your patch, you will want to navigate into the module's folder. This may take you a while to figure out - see step #3 - but the above commands will get you there eventually, especially if you open Windows Explorer and use that to help you move around.

Preparatory steps

Prior to applying the patch, the following steps are highly recommended:

• Apply the patch to a development environment or test site. Once you are sure that it works, you can apply it to your production environment.
• Backup your database. Since patches don't always work correctly, there is a possibility that a successfully applied patch may trash your database. A backup is advised.
• Backup the module files (Note: there is a way that you can have patch create backups of any files it modifies. See instructions below). In case you need to revert to the original version, it may be helpful to have a backup of the module files. You can either copy the entire folder or, if you know the exact files being patched, just those individual files. You can figure out what files are being patched by looking at the .patch file. To do this, open the patch file (preferably in a plain text editor such as Notepad++) and take a look through it to see which files are going to be affected. The patch may have more than one section, depending on whether more than one file is going to be modified. In each new section you will find a couple of lines that specify what file is being changed. The first line should start with --- and then have the name of the file that is being changed. The second line should start with +++ and then specify the name of the file in which the changes were made. For this example, we will assume that only one file (scary_module.module) is being changed. (So, we would make a copy of that file and name it something like scary_module.module.backup. The name you choose is unimportant; it just gives you a way to save a backup.)

Step-by-Step: Patch a Contributed Module

Okay, now we are ready to patch a module. Here are the steps:

1. Locate the desired patch

• Navigate to the appropriate issue on drupal.org
• Make sure you are choosing a patch that is designed for your version of the module
• Look through the entire series of comments attached to the issue and choose the most recent, stable patch. A patch may need to go through several iterations.
• Note that a patch file can be saved in any of several file formats. '.patch' is perhaps the most common, but you may also find patches with '.txt' or other file types. The same procedure applies regardless of the file type - you just need to modify the command shown below accordingly.
• For illustrative purposes here, we will assume that the module being changed is called 'scary_module' and that the patch being applied is called fix_scary_module.patch.