It’s been a while since I posted something new on the use of Subversion. I’ve been working with the tool a lot, and I’ve found that patches are a great way to communicate code changes.

For those of you who are still learning, let me first explain what a patch is. A patch is a text file that contains the alteration that were made to a specific file. It includes the lines that have been removed and the lines that have been added. In short, if you have a ruby script and edited it, you could create a patch file, containing the changes you’ve made.

Why is this useful? You could check in your changes to your repository directly. True, but there are cases that you don’t have write access to the repository. For example, if you wanted to contribute code changes to Acts As Exportable, you should create a new ticket and attach a patch file. I will then review your changes before I apply them to the code and commit them to the repository.

So, how do you go about creating a patch file and how do you later apply it to your source?

Creating a patch file

Creating a patch file is really easy. First, check out the most recent version of the code from Subversion using the ‘checkout’ command.

Make your changes.

Then, in the root the project run the following command. It will store the patch file in your home directory. Make sure to give it meaningful filename.

svn diff > ~/fix_ugly_bug.diff

The file has the .diff extention, which stands for differences. This extension is recognized by many text editors and enables ‘syntax highlighting’ automatically. (Give it a try with TextMate and you’ll know what I mean.)

You can send the diff-file to the author of the project by email, or you can create a ticket in Trac and add it as an attachment. The author will review the changes you made and possibly apply them to the source.

Applying a patch

You should never apply patches from any person other than your development team without first reading through the changes, apply them locally and test your application and then commit them. Patches can not only include bug fixes, but also alterations to create back doors or add other exploits to your code.

Always read through a patch before applying it!

When you are sure the patch will bring no harm to you, your application or your customers, go ahead an apply it to your working copy. Here, I assume that you downloaded the patch file we previously generated, and placed it in your home directory. In the root of your application now run:

patch -p0 -i ~/fix_ugly_bug.diff

This will apply all the changes in the patch to your source. The -p0 option makes sure that all files can be found correctly (this has to do with something called ‘zero directories’, I won’t get into that right now). The -i option tells ‘patch’ what to use as input, in this case the ‘fix_ugly_bug.diff’ file in your home directory.

With the code changes in place, run your tests and make sure everything works as expected. If it does, commit your changes and celebrate with a cup of coffee.