Creating a patch

From Joomla! Documentation

Other languages:
English • ‎español • ‎français • ‎Nederlands

An important part of creating a patch for Joomla! is ensuring that you're managed to create everything properly. As a standard all patches should be created in the root of your Joomla! instance. This way when we come to test it we don't need to work out what directory the file you're trying to change is in or modify your patch file to work properly on our local system. This can be a problem because if your patch only changes one file, there may be one file with that name. For example we recently received a patch for a file called banner.php. There are five different files in Joomla! called banner.php, so we then need to try and work out which file is being referenced in this particular case.

Creating a patch on the command line

For Linux/Mac users, using the command line is often the quickest way of creating a patch. Depending on how many changes you've made to your local install you might have a few different changes. The best method for avoiding this is to have a clean Joomla! check out from SVN and then make your changes to this. Then in the root of the Joomla! instance, execute the following command:

svn diff > file.patch

You need to ensure that only changes you have made are in the file and not any other irrelevant changes. If you can't do this you should specify the files that you changed to be part of the patch:

svn diff libraries/joomla/database/table.php > jtable.patch

Make sure you are in the Joomla! root directory, not in the directory of the files (you will see folders like libraries, administrator, plugins, components, modules, etc).

Creating a patch using Eclipse

If you've got Subclipse and Eclipse you can check out a new project from the Joomla! SVN (which ever branch/release is relevant to your bug) and then use this to create a patch file. Keep in mind that by default Eclipse creates patches that includes the entire path to the files, which isn't what we want. Presuming you created a new project using the checkout from SVN and used the root of a Joomla! instance, you should be able to create a valid patch easily.

To create a patch, select the files you have changed and then right click on one of them and select "Team > Create Patch". The first screen asks you where you want to put the file: the clipboard, into the filesystem or in the workspace. Typically you'll want to create it somewhere in the filesystem. I personally use a patch folder where I keep all of the patches that I make. You should also notice at the bottom of this screen the list of files that will be included in this patch. If you have included files you didn't want to, you can deselect them here. If you are missing a file from this list you will need to reselect your files and add them.

Once you have worked out where you are going to put the patch and that you've selected the right files, click "Next" to continue. If you click "Finish" here your patch will be created incorrect so it is important that you click "Next" here. In this area select "Project" and then click "Finish" to create the patch. Doing this will ensure that your patch file is created properly.

Creating a patch using NetBeans

You can use NetBeans IDE to create patch files too. There's a video that explains how to create a patch for Joomla! with SVN:

Line endings and encodings

It is important that with anything you add that you are using the correct line endings. The line ending style for Joomla! is just line feeds or Unix style, and all files should use the UTF-8 encoding. If you are using Eclipse you can change your settings in Window -> Preferences -> General -> Workspace. Select your text file encoding as UTF-8 and your line delimiter as "Unix".