This section of the handbook contains tutorials that will help you learn how to create, apply, and revert patches.

Patches are the only way that a contributor, like you, can submit code to the WordPress project.

Whether you are fixing a bug or contributing to a new feature, a patch is required so the core developers and committers can consider your code for inclusion in the repository.

For beta testing the latest development version of WordPress, you will need to be able to apply patches that other contributors have created to determine if the patch fixes the issue.

SVN Client or Command Line Interface? #

Many developers prefer to work with Subversion (SVN) using the command line interface (CLI), while others prefer to use a GUI application. Both are acceptable, and will allow you to create, apply, and revert patches.

For command line users, there are programs such as Cygwin (Windows), Terminal (Mac), and Bash (Mac).

If you prefer to use a GUI application, the recommended SVN clients are TortoiseSVN (Windows, free/open-source), and Cornerstone (Mac, purchase).

Top ↑

Creating and Applying Patches with TortoiseSVN #

Before starting, you need:

Creating A Patch With TortoiseSVN #

1. Editing/Saving A File #

Open the folder, and find the file you need to change. Open it in your favorite plain-text editor. Note: Do not use a rich-text editor such as Word or OpenOffice to edit the files.

Make the changes necessary, then save the file.

You will notice that the green checkmark has changed to a red exclamation point. That means the file has been changed, and is no longer in sync with the repo version.

TortoiseSVN Changed File Indicator

Top ↑

2. Creating/Naming A Patch #

Next you will create the patch file. Right-click in the root directory of your SVN checkout folder, and select SVN Create Patch.

TortoiseSVN Create Patch Context Menu

A pop-up window will show you the list of changed files. Make sure the file(s) you want to include in the patch are checked, then click OK.

Check the box for all file(s) that should be included in the patch

You will be prompted to save the file. Create a folder called patches, then type in the filename you want to save it as. Use the format ticket#.patch.

The TortoiseUDiff editor will open and show you the patch file you just created.

TortoiseUDiff Editor

Top ↑

Applying a Patch #

Got a patch you want to test with your local environment? Follow these steps to test your patch.

Top ↑

1. Downloading a Patch #

Part of the troubleshooting/testing process involves downloading and applying patches to your local WordPress trunk install from a Trac ticket that you are involved in.

To download a patch, right-click on the filename in the Attachments section of the ticket (just below the Description section), select Save Link As in the context menu, and save it to a folder called patches.

Download A Patch From Trac Ticket Screen

Top ↑

2. Applying A Patch #

To apply the patch you just downloaded, right-click in the folder for your working copy of WordPress, which will bring up a context menu. Click on SVN Apply Patch.

TortoiseSVN Apply Patch Context Menu Screen

This will bring up a file open dialog window, allowing you to select the patch file to apply. By default, only .patch or .diff files are shown, but you can change the file type to All files if you don’t see the patch file you are looking for.

TortoiseSVN Select Local File Screen

Applying a patch file to your working copy of WordPress should be done at the same folder level as was used to create the patch. If you are in the correct working copy, but picked the wrong folder level, TortoiseSVN will display a notice, suggesting the correct level, and allows you to select that.

TortoiseSVN Wrong Directory Screen

Once you have selected the patch file and correct working copy location, TortoiseMerge will run to merge the changes from the patch file with your working copy. A small window lists the files which have been changed. Double-click each filename, review the changes, and save the patched file to your working copy.

TortoiseSVN File Patched Screen

Top ↑

(ignore me) #

Top ↑

Creating and Applying Patches with the Command Line #

This article will walk you through creating, applying, and reverting a patch using the command line. Before starting, you’ll need the following:

Top ↑

Creating A Patch #

During beta testing, you may run across a bug that you are able to fix. Before you submit the Trac ticket, however, you should create a patch with the proposed fix so you can attach it to the ticket.

Open the folder where you have WordPress installed via SVN, and find the file you need to change. Open the file in your favorite plain-text editor. Make the changes necessary to fix the bug, then save the file. Do not create patches for minified JS files or RTL CSS files. These are generated automatically from source files. Read more about this build process.

Next you will create the patch file, which records the differences between your version of the files and those from WordPress trunk. Patches should be created from the root directory of your WordPress SVN install.

To do so, ensure that you are in the root directory created by your SVN checkout (wordpress-svn), then run the following command, where 00000 is replaced with the ticket number from Trac:

$ svn diff > 00000.patch

Top ↑

Applying A Patch #

Part of the troubleshooting/testing process involves downloading and applying patches to your local WordPress trunk install from a Trac ticket that you are involved in.

To download a patch, click on the handy download icon next to the patch’s name in trac:

Download a Patch from Trac Ticket Screen

On a Mac, this will save it to your default downloads folder, from where you can move it to your chosen wordpress-svn directory. On a Windows machine, this will prompt you to save it in your chosen location, which should be the aforementioned directory.

You can also download a patch via command line. Make sure that you are in the wordpress-svn directory, then download the patch into the patches folder.

$ curl -O

Note: If you download the patch this way, make sure that it is coming from the raw-attachment directory on the Trac server. You can get this URL by clicking on the patch in Trac, then grabbing the URL linked to by Original Format at the bottom of the page.

You will need to apply the patch from the wordpress-svn directory, where you have downloaded the patch file. Use the following command to apply the patch:

$ patch -p0 < 00000.patch

Now, the wordpress-svn code has been patched with the file you downloaded, giving you the version of the code that the developer who submitted that patch was working with.

Note: If the patch fails to apply cleanly, you will need to leave a note on the Trac ticket that the patch needs to be refreshed, and add the needs-refresh keyword to the ticket.

Top ↑

Reverting A Patch #

When you have finished testing, it is best to revert your SVN install back to the latest version of trunk, removing all applied patches and any changes you have made. You will use the following command to revert all patches/changes:

$ svn revert -R *

Top ↑

Next Steps #