How to apply a patch to a module - beginner's version

Much of the existing documentation (see links below) on how to apply a patch 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, if there is an important feature that has been developed for your module, but that is still not available in an official release. Or if 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 very simple 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 from time to time. 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 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 really know what you are doing, please apply only patches that are well, well proven by other, more experienced members of the Drupal community and/or patches you've been asked by the module maintainer to test.

You can tell a module patch has been 'well proven by the community' either: 1) by seeing a notation in the issue queue which states the thread has been 'reviewed & tested by the community' and/or 2) by 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 is used to modify or change an existing file containing code for a Drupal module. The 'patch' command is a Linux command 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 patches files for Drupal modules, the patch file is normally intended to change the existing .module file in the module folder. 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, but rather it is done in Linux or something that emulates Linux.

Because the 'patch' command is Linux command, not a Drupal command or a Windows command, Windows users need to utilize a tool that allows them to run Linux commands. There are several tools for doing this as listed here - http://drupal.org/node/60179. 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. Applying patches can be a bit risky, so you want to avoid mistakes.

• Applying patches - Intro page to the existing materials on patching. Most pages here are written for fairly technical audience.
• Applying patches manually - this is interesting to read because it helps explain what is actually in a 'patch' file - and, for simple patches, doing them manually might be just as fast as the steps below
• Apply patches on Windows - very cryptically written series of pages for using various tools - Cygwin, GnuWin32, and UnxUtils - for patching
• Apply patches on Mac OS - don't know Macs myself, but this material looks just as cryptic as the Windows info
• Applying patches to core - useful video that's worth watching since patching modules and patching core is procedurally about the same, but the video flashes through the command line steps that are likely to be the most vexing to first timers and less technical folks.

Prerequisite #1 - 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.

Please visit the Cygwin website to learn more. You can download the Cygwin setup.exe file here.

If you need additional information on how to install Cygwin, please Google 'install cygwin' and read some of the how-tos.

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 like myself, 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

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

Prerequisite #2 - Install Notepad++

Most likely you are already familiar with plain text editors such as Notepad++ and have one on your system. You will need it to create your local patch file (step #2).

If you don't already have one, you can download Notepad++ from Sourceforge.net here. If you prefer another plain text editor, feel free to use that.

Microsoft Word is not a plain text editor and cannot be used for patching. It will insert extra invisible characters that will derail the Linux patch command.

Step-by-Step: Patch a Module

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

1. Make backups of the current .module file and your DB.

For the .module file, navigate in Windows Explorer to the folder of the module you want to patch - let's call it module 'ScaryNames', then do this:

• Locate the file with a .module suffix - e.g., scarynames.module.
• Make a copy of the file.
• Rename the copy by adding '.original' to the end of the file name (after the existing .module) - e.g., scarynames.module.original. This is crucial. If you have two files with the suffix .module in the folder, it will mess things up.
• If you want to be extra safe, then you should also make a backup copy of your DB.

For your DB, open phpMyAdmin (or whatever you use) and make a backup of the DB as normal.

2. Create a local version of the patch file. Follow these steps to create a local copy of the patch file. Patch files are not downloaded as zipped files like modules or Drupal core. They open in your browser window and you need to copy and paste them into a file on your local machine.

• On drupal.org, navigate to the page with the patch file. Remember: please install only patches proven by the community. Bad patches could cause serious damage to your system.
• Confirm that it works on your exact version of the module. Using a patch on written for another version is not likely to work and could damage your system.
• On the thread, identify the exact patch which has been proven to work. A patch may go through many iterations before becoming stable. Be sure to choose the most recent / most stable version.
• Click on the patch file and the file will open in your browser window
• Verify that the patch is to be applied to the .module file by reading the first few lines of the file. In the first line, you should see something like this: 'Index: nice_menus.module'. If it doesn't say .module, then the patch needs to be applied to a different file. In that case, you need to go back to step #1 and follow same procedure, but for the relevant file.
• Assuming we are good to go with a .module patch, please highlight and copy the ENTIRE file (use Ctrl - A, then Ctrl - C)
• On your desktop, open Notepad++ (or other plain text editor)
• Paste patch file into Notepad++. Visually compare to what's in your browser window to ensure the pasted file is identical.
• Save the patch file as a .txt file using any name as long as it has no spaces - e.g., my_patch_file.txt. This next steps will not work if your file name has spaces.
• Save the file directly into your module folder
• In Windows Explorer, confirm that both the .module file and the new .txt patch file are in the module folder

3. In Cygwin, navigate to the module folder. Until you get the hang of it, this next step may take a bit of wangling to get right. While it can be done from other locations, the simplest way to patch is to get the Cygwin command prompt into the module directory. To do this, you typically need to navigate up a few levels in your file directory, then over to your drupal directory, then down into the module folder.

• Open Cygwin and at the prompt, type 'ls' to list the files in your current directory.
• In Windows Explorer, locate the folder these files are in.
• Using commands listed above, navigate up, across, and down to your module directory.
• Or, you can try to jump straight there by fully specifying your path: e.g., c:/xampp/htdocs/drupal/sites/all/modules/ScaryNames (correcting typos is a pain, so type carefully)
• Confirm you are in your module directory, by typing 'ls' to list the local files and confirm that you see your .module file and your .txt patch file both listed.

You're almost there!

4. Patch the file. Now you are ready to run the patch command and patch the file.

• Still in Cygwin in the module folder (and with your fingers crossed), type this command at the prompt:
  patch -p0 < my_patch_file.txt .
• If all goes well, you should see something like: 'patching file nice_menus.module' and nothing else. It's rather unsatisfying, but it won't actually say if the patch successfully applied. The absence of errors is as good as it gets. It may also say something like '(Stripping trailing CRs from patch.)' which you can safely ignore.
• If you get things like 'Hunk #1 FAILED at 220.' then the patch didn't apply properly. 'Hunk #1' refers to the first chunk of add/delete lines in the patch file. '220' is the line of the file where the fail occurred.
• If you got no errors, then you can confirm the patch was applied by opening the .module file and looking for some of the new lines that were marked by '+' in the patch file. If those lines are there, then the patch worked and you can go to step #5.
• If you get a fail, well, then, uh... make sure you executed the steps right, maybe go back to the issue queue to see if you missed something,... If you can't see what went wrong, the go to step #6 and revert back to the original .module version.

Note: you do not need to run update.php after applying a patch.

5. See if the patch applied. If the patch appears to have worked, you should now visit your site and reload some pages. First make sure that the site appears to be working normally in all respects. Then check to see if the desired new feature or fix has been enabled and that it does what it was supposed to do. In some cases, you may need to clear cache to see changes. If it works in all respects, then you are good to go and are done. I would recommend leaving the .module.original file in place as backup, but it is probably also safe to delete if you are fastidious about housekeeping.

If the patch does not appear to do anything, then you should re-read the issue thread to see if you missed anything (a lot of patches simply don't work). If you can't get it working properly, then you need to revert back to the original .module file (step #6) and hope the module developers officially release the feature soon.

6. Reverting back to the original file. If your patch successfully applied and works, please ignore this step. If your patch either failed to apply (step #4) or appeared to apply, but didn't actually change site behavior (step #5), then you should revert to the original .module version as follows:

• Delete the current .module version of the file that you have been working with
• Rename the .module.original version back to simply .module -- e.g., scarynames.module.original becomes scarynames.module
• Visit your site and load a bunch of pages to ensure everything is still working properly, particularly the module you attempted to patch