Creating patches

This page explains how to create patches with CVS or diff. Other programs can make patch files, including IDEs like Eclipse or XCode, editors like TextMate, or the tools included in Unix or Linux systems.

Related resources:

• Overview of patching
• Submitting patches to the issue tracker
• Applying patches to your own code
• Video patching tutorial

CVS example

This assumes you have an up-to-date, clean CVS checkout of the Drupal files. (More help: set up CVS, check out Drupal core and check out contributed code.)

1. Change your copy of the files and save them.
2. Change into the proper "root" directory. For Drupal core: cd /Applications/MAMP/htdocs/head. For contributed modules/themes: cd /Applications/MAMP/htdocs/6x/sites/all/modules/cck
3. Create a patch of your changes:
   cvs diff -up > example.patch
4. Review your patch in a text editor.
5. Post it to an issue on Drupal.org.

diff example

1. Make sure you have the latest copy of the file(s) by downloading the latest tarball.
2. Create a working copy of the file you are editing in the same directory as the original (e.g. example.module copied to exampleNew.module).
3. Edit the working (exampleNew.module) copy, and save it.
4. When you are ready to roll your patch, go to the command line and change (cd) to the proper "root" directory.
5. Enter this command: diff -up path/to/file/example.module path/to/file/exampleNew.module > mypatchname.patch. This creates a new patch file in the current directory that you can now attach to a reply in a Drupal project's issue thread.

CVS diff vs. diff

cvs diff compares locally-edited files to the CVS repository version. diff compares two local files (the original and edited version). diff can be used if you don't use the CVS. Both commands use the same options and produce equally effective patches.

Check your directory!

Make sure others can use your patch:

• Drupal core patches: Run the diff command in the root Drupal directory where you're making a patch (the same directory that contains the index.php, cron.php, etc. files). Core patches should always be made from Drupal root.
• Contributed module/theme patches: Run the diff command in the module or theme's root directory. (Example: /sites/all/modules/foobar).

With these guidlines, others can use your patch even if they don't have your same directory structure.

Patch readability

Readable patches are more likely to be accepted. Use the -u option for unified formatting and -p to show the function closest to the difference in the code. This makes it easier to see what changed.

Keeping things organized

To help reviewers understand the scope of changes, separate each change type into its own patch. For example, bug fixes, performance enhancements, code style fixes, and whitespace fixes all should be in different patches. Likewise all white space and code style cleanup should be in a separate patch.

Line endings and directory separators

Note for Windows users: Use Unix line endings (LF) and directory separators (/). Many text editors can convert line endings, or you can pipe diff output through dos2unix.

The diff command

In your command line, simply type in the following:

cvs diff -up original.php > filename.patch
- or -
diff -up original.php new.php > filename.patch

In this example, > writes diff's outpt in a file named filename.patch. If you omit> filename.patch, diff's output goes to your screen.

Give the patch file a descriptive name, such as modulename_code_cleanup.patch.

You can save the patch file to another place, like your desktop or a patch folder, by prefixing the filename with a path. For example: cvs diff -up original.php > path/to/desktop/filename.patch.

Switches for the diff command

When you've modified multiple files in the source tree, use diff's ability to compare directories. Add the -R (uppercase) switch to cvs diff and the -r (lowercase) switch to plain diff to instruct the respective program to recurse (sub)directories. To compare files from the root directory, cd to the root directory and use a dot (full stop) in place of the directory name:

cvs diff -uRp directory > filename.patch
or
diff -urp original_directory new_directory > filename.patch

Adding/Deleting Files Using the Diff Command

Note: the fakeadd utility can save you from fiddling with CVS internals.

Having one patch represent all code changes, including adding and deleting files is vital. The problem is that "cvs diff" won't let you diff files that haven't been added (cvs add) or deleted (cvs rm) from the repository. To do that you would normally need to get read/write permissions for the repository. Unless you are the maintainer of the module you won't have that, but there are a few solutions.

note: You use the -N switch to account for new or deleted files.

cvsdo
For linux users, a script called cvsdo is available to use that will basically do the long steps below for you:
cvsdo add file.module
it is part of the overall useful cvsutils package. for Ubuntu/Debian users:
sudo apt-get install cvsutils
Fedora users:
sudo yum install cvsutils

fakeadd
a shell script that again, does the work below for you.
http://tinyurl.com/fakeadd

by-hand method
see below about changing CVS/Entries to add and remove files manually.

Once you've added/removed the file from CVS by one of these methods, you can now use:
cvs diff -upN directory > filename.patch
or
diff -upN original_directory new_directory > filename.patch

Changing CVS/Entries to add and remove files manually

If you're using -N to account for a new file, you'll also need to edit the CVS/Entries file for that directory and manually add a line for the new file. For example, if you have created a new file called newfile.inc in the modules/system directory, you will need to add a line at the end of the modules/system/CVS/Entries file like this:

Editing modules/system/CVS/Entries:
/admin.css/1.12/Tue Jan 16 23:15:28 2007//
/defaults.css/1.2/Fri Aug 25 09:01:12 2006//
/system.css/1.22/Wed Feb 7 03:46:21 2007//
/system.info/1.3/Tue Nov 21 20:55:35 2006//
/system.install/1.79/Fri Feb 16 16:39:46 2007//
/system.js/1.1/Thu Feb 22 16:33:29 2007//
/system.module/1.451/Thu Feb 22 16:33:29 2007//
/newfile.inc/0/New file//

If you are working from a tagged version the line will have the tag at the end. Use the other entries in the file to guide you:

/newfile.inc/0/New file//TDRUPAL-5

In this example, the "New file" string is arbitrary, but the 0 must be specified as the file's revision to show that it is new. Once this new line has been added cvs diff -Nup will properly include the new file in the diff.

Note: Do not add binary files (like PNG files) to a patch file. They will cause the testing system to fail with an “Invalid PHP syntax” error. If your patch requires additional binary files, simply post them as separate attachments to the issue and specify which directory they should go in.

If you are using -N to account for a deleted file, you will also need to edit the CVS/Entries file for that directory and manually change the line for the removed file. For example, if you want to remove system.module in the modules/system directory, you will need to modify the corresponding of the modules/system/CVS/Entries file like this:

/admin.css/1.12/Tue Jan 16 23:15:28 2007//
/defaults.css/1.2/Fri Aug 25 09:01:12 2006//
/system.css/1.22/Wed Feb 7 03:46:21 2007//
/system.info/1.3/Tue Nov 21 20:55:35 2006//
/system.install/1.79/Fri Feb 16 16:39:46 2007//
/system.js/1.1/Thu Feb 22 16:33:29 2007//
/system.module/-1.451/Thu Feb 22 16:33:29 2007//

That's it! all you need to do is add a - to the version, so 1.451 becomes -1.451. (This works for files only—not directories).

Adding directories

It is also possible to use cvs patches to add a directory. For example, to add an add-on module to an existing module.

1. Within a directory that cvs knows about, add a new file to cvs shown above. With contributed modules, this would be in the root directory of that module.
2. Create the patch file by modifying CVS/Entries and using the -N switch shown above.
3. Edit the patch file adding the directory path that the files should reside in.
4. Example shown below, the first part shows the first few lines of the patch file created in the module root, after editing, I manually add 'contrib/exhibit_apachesolr' in front of any reference to the new file.
5. After running the patch file, on a cvs checked out module, it creates both the file exhibit_apachesolr.info inside the created directory exhibit_apachesolr (that resides under contrib).

An example using cvs diff

1. Make sure you have the latest CVS version of the file(s) before you begin making your changes: change (cd) to the Drupal root directory and run the update command: cvs update -dP.
2. Make your changes to the file(s).
3. When you are ready to roll your patch, change back to the Drupal root directory.
4. Do a cvs diff -up path/to/file/example.module > mypatchname.patch. This creates a new patch file in the Drupal root that you can now upload to an issue.

Reverting to Drupal head

To revert your install to the committed version of Drupal, and get rid of all differences, run the command: cvs up -dPC. Be careful with this command, because it will wipe out any changes that you are working on.