Making and Applying Patches

by Walt Stoneburner

---

This article is about how to make patches for maintainers and how to apply patches if you are a maintainer.

---

Submissions from Everywhere

Fundamentally, the maintainer of a piece of software has a directory with the source code sitting in it.

Over time, people download copies of that directory for their own use and for whatever reasons may be inclined to make a few changes that they would like to share with the rest of the world by making a contribution to the original source base.

However, there's a problem. The original source base may have changed and a number of other people may have gotten the same idea.

It's up to the maintainer to take all these different versions, munge them into a new version, and redistribute. It can be a lot of hard and tedious work, and that's why its important to lessen the burden on a maintainer in order to improve the changes of your submission getting accepted.

The Magic of diff

The GNU utilities have a program called diff which is capable of comparing files and directories and producing a file that contains the differences.

What's important to note is that this "difference file", also called a patch file tells how to convert one version to the other. It isn't one-way!

This means that changes made can be backed out again.

Let's assume that you downloaded a program, untared it, and it's now sitting in a subdirectory called original. You're going to keep this copy around as the master copy from which to make comparisons.

Duplicate the directory exactly and do all your changes in your own copy.

$ cp -a original myversion
$ cd myversion
(make changes to files in this directory)
$ cd ..

Be sure to clean up any temporary files, object files, map files, executable files, core files, and anything else the maintainer didn't have out there. The best way to tick off a maintainer is to send them junk.

Here's how to make a unifed diff against a single file which can be used for patching one version to the other.

$ diff -u original/somefile myversion/somefile > mypatch

You can now use this new file to convert either version to the other. If you're going to validate your patch, and you should, do so on another copy of original.

$ cp -a original origcopy

Converting Origcopy to MyVersion $ cd origcopy $ patch -p1 < ../mypatch The original version should now be patched to match your version. Care to back the change back out again? $ patch -R -p1 < ../mypatch

Converting MyVersion to Origcopy $ cd myversion $ patch -p1 < ../mypatch Your version, at this point, would be patched back to look like the original. Care to back the change back out again? $ patch -R -p1 < ../mypatch

You may be asking at this point, "what's the -p1 for?" As you recall, you made the patch file from a directory above the sources. This means the patch file contains the subdirectory names in them, which is exactly what you want, because it lets the maintainer you're submitting a patch to know what he's looking at.

However, when the actal patching process takes place, the first (and hence the '1') pathname needs to be striped to get to the real filename.

You should be all set to email the maintainer with a description of your patch (what it does and how, including which version of the code your patch should be applied against), and the patch as an attachment.

Two additional thoughts. One, if the patch file is big, compress it first. Two, download the latest version (it may have changed while you were working), apply your patch against it, so you see exactly what the maintainer will see, and make sure it works before mailing.

Maintainers

Change of shoes. Now you're the maintainer and someone has just sent you a kind email with a patch.

Read of the description, read over the patch changes themselves, and if agreeable, apply the patch to the files. It's possible to do a dry run first, which makes sure the patch applies cleanly before you really do it.

$ cd maintainerSrc
$ patch -p1 --dry-run < ../mypatch
(things look okay? yes? continue.)
$ patch -p1 < ../mypatch

Rebuild and test the changes don't break anything, then redistribute, committing the changed version to the master copy.

It's always a good idea to send an email back to submitters so that they know their efforts are appreciated, so that they'll stop resubmitting duplicate patches (which can happen if you're slow to incorporate changes), and so that they can grab a new version and verify for themselves things went according to plan.

It's also polite to give submitters credit in some text file associated with the project.