Archived:Learn more about patch files

This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

This Page Needs Your Help

Test this patch, make a patch, are things you hear when you report an issue or when you're working on bugs. What exactly is a patch?

A patch is a file that indicates which exact lines in which exact files should be changed.

As an example, here's a patch from issue 11354 which corrected a simple typo.

Index: plugins/authentication/gmail.php
===================================================================
--- plugins/authentication/gmail.php (revision 10386)
+++ plugins/authentication/gmail.php (working copy)
@@ -87,7 +87,7 @@
 }
 }
 else {
- $message = 'curl isn\'t insalled';
+ $message = 'curl isn\'t installed';
 } 
 if ($success)

Looking more closely, we see that the patch always starts with the name of the changed file relative to the Joomla! root. In this case it is the file gmail.php in the plugins/authentication folder.

Next we see the file named again in two lines. The number in the first line represents the version of the code base or build on which the patch was created. The working copy is the copy that is changed. What do I mean by build? Every time a change is made to the codebase, that creates a new revision or build. You can find your build number in the changelog.php file in your Joomla! root.

Next comes @@ -87,7 +87,7 @@ which tells us that the change will start on line 87 of the file.

Finally we see the code. The old line 87 has a – in front of it and the new line 87 has a +.

The new version of the line will replace the old line in the file.

Of course most patches are much more complex than this, but they really just are repeated instances of this structure.

So if you saw this patch file and wanted to fix your version of Joomla! all you would need to do is find line 87 of gmail.php and make that change. So if someone tells you “There's a patch on the tracker” what they are saying is that you can go download the patch and apply it to your version of Joomla. However one thing to keep in mind is that if your version does not match the version in the code repository it is possible that that patch will not work because it depends on or impacts other parts of the code.

Now, if you're contributing a bug fix as opposed to just reporting an issue, the ideal is to submit a patch file that you have tested. However, if you can't do that, at least give this information:

• The complete names and paths of any files changed
• The line numbers of the changes
• The old and new versions of the changed lines

However, making a patch file is even better and is not complicated if you install a subversion client such as Tortoise or the Subclipse plugin for Eclipse. For information on how to install the Eclipse IDE, see Setting up your workstation for Joomla! development.

Patch Files and UTF-8 Characters

Most patch files are for PHP files that contain simple text. However, patch files can also be used to patch language INI files, and these can often contain UTF-8 characters. There is a known problem when you try to apply a patch with UTF-8 characters using Eclipse. The patch file may show errors when you try to apply it. One possible work-around to this problem is to copy the file to your clipboard and then in the Patch Input Specification in Eclipse, select Clipboard instead of File. Note that the preview for the patched files may show question marks for the UTF-8 characters, but the patch will apply correctly.

You can check that the patch did apply correctly by using the Compare With→Base Revision feature in Eclipse.

Other Important Articles About Patch Files

• Important Notes About Patch File Format
• Apply Patches and Pull Requests Without Branches
• Apply Patches and Pull Requests Using Branches