Being rather ignorant about patches, how do you go about applying them?

I send many patches to various projects. Many times I was asked "What should I do with this patch file you gave me?".

Here's my answer:

1. First of all, patches are just specially formatted text files. Before applying a patch you should open it in any text editor, so that you can see what the patch actually changes. Note for Windows users: you should use an editor that honors Unix line endings, which usually means that you can use any editor besides that poor notepad.exe.

   You can read diffutils manual to get familiar with patch files format. In particular, see the description of the unified format, this is the most commonly used format.

   For simple few-line patches it's indeed possible to just read them and "apply by hand", i.e. manually do all the changes that the patch describes.

2. For larger patches you will want to use a program that applies them to your source files. This will make applying the patch faster and less error-prone.

   The traditional program to do this is the patch command-line program. Most people that ask questions about patches are Windows users, and in this case you can get the patch (and diff, and other related programs, commonly known as diffutils) from

   • Cygwin
   • There's also UnxUtils — GNU utilities for Win32 which may be more comfortable (since it doesn't require the whole large Cygwin layer).
   • AFAIK MinGW also includes this program.

   If you're under Unix (Linux, FreeBSD, etc.) then diffutils programs (most probably as implemented by GNU) are already installed and available on your $PATH.

   The simple usage instructions: usually you should place the file.patch in the top-level directory of your project, and then run from command-line patch -p0 < file.patch. Sometimes it's -p1 instead of -p0, and sometimes no -p* is needed. Don't be afraid to experiment: the patch program will output some information how the process goes, and it will stop if the file cannot be found (e.g. because you used wrong -p* option). Of course, having a backup of your files (or keeping them in some version control system) is always a good idea.

   See homepage of GNU diffutils. In particular see the extensive diffutils manual how to use all the included programs, including diff and patch. Once you install diffutils you should also have this documentation available locally somewhere (call man patch).

3. There are also programs that allow you to view and apply patches in an interactive manner, which is more comfortable than using command-line utilities:

   • Meld let's you see and visually apply patches.
   • WinMerge, visual text file differencing and merging tool for Windows.
   • Emacs (my editor for choice...). Just open the patch, and C-h m will give you help. Press C-c C-a to apply hunk of the patch, this will show in another buffer the affected file.
   • Perhaps there are other editors / IDEs that allow you to do this. (Mail me if you know about one; and note that we're talking here about programs to apply the patches, not only to generate the patches).