Working with Patches

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 bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. or contributing to a new feature, a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. is required so the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. developers and committers can consider your code for inclusion in the repository.

For betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 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 (SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase.) using the command line interface (CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress.), 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 Grunt

If you like to automatically submit the created patch to an existing ticketticket Created for both bug reports and feature development on the bug tracker., there is an easy-to-use Grunt command available that can take care of both creating the patch and uploading it. In order to use the command, you need to have Node.js and Grunt-CLI globally installed, and you need to ensure that the WordPress development dependencies are installed locally, which you can do by running npm install.

Top ↑

Apply a patch from the command line

  1. Have a diff or a patch file in your working Directory, then run grunt patch. If multiple files are found, you’ll be asked which one to apply.
  2. Enter a ticket number, e.g.

grunt patch:15705

  1. Enter a ticket url, e.g.

grunt patch:https://core.trac.wordpress.org/ticket/15705

  1. Enter a patch url, e.g.

grunt patch:https://core.trac.wordpress.org/attachment/ticket/11817/13711.diff

  1. Enter a githubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ url that points to a changeset such as a Pull Request, e.g.

grunt patch:https://github.com/muhammadfaizanhaidar/develop.wordpress/pull/23

Top ↑

Upload a patch from the command line

After you’ve made changes to your local WordPress develop repository, you can upload a patch file directly to a TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket. e.g. given the ticket number is 2907,

grunt upload_patch:2907

You can also store your WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ credentials in environment variables. Please exercise caution when using this option, as it may cause your credentials to be leaked!

export WPORG_USERNAME=matt
export WPORG_PASSWORD=MyPasswordIsVerySecure12345
grunt uploadPatch:40000

Top ↑

Creating and Applying Patches with TortoiseSVN

Before starting, you need:

Top ↑

Creating a Patch with TortoiseSVN

Top ↑

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.

It is important to create patches from the root directory (the folder containing all of the WordPress files). To do that, either right-click on white space in the folder or move one level up from that folder and right-click on it.

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#.diff.

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

TortoiseUDiff Editor

Top ↑

Applying a Patch with TortoiseSVN

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 trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. install from a Trac ticket that you are involved in.

To download a patch, click on the Download icon next to the patch filename in the Attachments section of the ticket (just below the Description section), and save it to a folder called patches.

Download A Patch From Trac Ticket Screen

Top ↑

2. Applying a Patch with TortoiseSVN

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 ↑

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 with the Command Line

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 JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. files or RTL CSSCSS Cascading Style Sheets. 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.diff

If you also like to automatically submit the created patch to an existing ticket, there is an easy-to-use Grunt command available that can take care of both creating the patch and uploading it. In order to use the command, you need to have Node.js and Grunt-CLI globally installed, and you need to ensure that the WordPress development dependencies are installed locally, which you can do by running npm install.

The actual command to create and upload a patch works as follows:

grunt upload_patch:00000

Make sure to replace 00000 with the ticket number from Trac. During execution of the command, you may be asked for your wordpress.org user name and password.

Top ↑

Applying a Patch with the Command Line

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 https://core.trac.wordpress.org/raw-attachment/ticket/00000/00000.diff
If you download the patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. this way, make sure that it is coming from the raw-attachment directory on the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. server. You can get this URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org 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 -p 0 < 00000.diff

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.

If the patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. fails to apply cleanly, you will need to leave a note on the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. that the patch needs to be refreshed, and add the needs-refresh keyword to the ticket.

To make this process a little easier for you, there is another Grunt command available that takes care of both downloading a patch from an existing ticket and applying it. As mentioned before, in order to use it, you need to have both Node.js and Grunt-CLI globally installed, and you also need to have the local dependencies set up, which you can do by using the command npm install.

You can then use the following command:

grunt patch:00000

Make sure to replace 00000 with the ticket number from Trac. The command will automatically download the patch file from the ticket if there is only a single patch available. Otherwise, you can select which patch to download from a list, using the arrow keys on your keyboard.

Top ↑

Reverting a Patch with the Command Line

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 ↑

Download a GitHub pull request

With hub is very easy to download a pull request from a WordPress fork on a Git repo (like on GitHub). For the purpose of this section you need to install this tool on your system.

Now you have a super version of Git that include the Hub version so inside the `public_html on VVV or your WP trunk folder you can execute this command (as example):

git checkout https://github.com/WordPress/wordpress-develop/pull/195

This command will create automatically for you a new branch with the content of this pull request, with the ability to update that branch with the code over there.

Otherwise you can download the patch or diff version of a pull request appending to the pull request url .patch or .diff like:

Top ↑

Next Steps

Last updated: