11.1 Tips for Patch Producers

To create a patch that changes an older version of a package into a newer version, first make a copy of the older and newer versions in adjacent subdirectories. It is common to do that by unpacking tar archives of the two versions.

To generate the patch, use the command ‘diff -Naur old new’ where old and new identify the old and new directories. The names old and new should not contain any slashes. The -N option lets the patch create and remove files; -a lets the patch update non-text files; -u generates useful timestamps and enough context; and -r lets the patch update subdirectories. Here is an example command, using Bourne shell syntax:

diff -Naur gcc-3.0.3 gcc-3.0.4

Tell your recipients how to apply the patches. This should include which working directory to use, and which patch options to use; the option ‘-p1’ is recommended. Test your procedure by pretending to be a recipient and applying your patches to a copy of the original files.

See Avoiding Common Mistakes, for how to avoid common mistakes when generating a patch.

11.2 Tips for Patch Consumers

A patch producer should tell recipients how to apply the patches, so the first rule of thumb for a patch consumer is to follow the instructions supplied with the patch.

GNU diff can analyze files with arbitrarily long lines and files that end in incomplete lines. However, older versions of patch cannot patch such files. If you are having trouble applying such patches, try upgrading to a recent version of GNU patch.

11.3 Avoiding Common Mistakes

When producing a patch for multiple files, apply diff to directories whose names do not have slashes. This reduces confusion when the patch consumer specifies the -pnumber option, since this option can have surprising results when the old and new file names have different numbers of slashes. For example, do not send a patch with a header that looks like this:

diff -Naur v2.0.29/prog/README prog/README
--- v2.0.29/prog/README	2002-03-10 23:30:39.942229878 -0800
+++ prog/README	2002-03-17 20:49:32.442260588 -0800

because the two file names have different numbers of slashes, and different versions of patch interpret the file names differently. To avoid confusion, send output that looks like this instead:

diff -Naur v2.0.29/prog/README v2.0.30/prog/README
--- v2.0.29/prog/README	2002-03-10 23:30:39.942229878 -0800
+++ v2.0.30/prog/README	2002-03-17 20:49:32.442260588 -0800

Make sure you have specified the file names correctly, either in a context diff header or with an ‘Index:’ line. Take care to not send out reversed patches, since these make people wonder whether they have already applied the patch.

Avoid sending patches that compare backup file names like README.orig or README~, since this might confuse patch into patching a backup file instead of the real file. Instead, send patches that compare the same base file names in different directories, e.g. old/README and new/README.

To save people from partially applying a patch before other patches that should have gone before it, you can make the first patch in the patch file update a file with a name like patchlevel.h or version.c, which contains a patch level or version number. If the input file contains the wrong version number, patch will complain immediately.

An even clearer way to prevent this problem is to put a ‘Prereq:’ line before the patch. If the leading text in the patch file contains a line that starts with ‘Prereq:’, patch takes the next word from that line (normally a version number) and checks whether the next input file contains that word, preceded and followed by either white space or a newline. If not, patch prompts you for confirmation before proceeding. This makes it difficult to accidentally apply patches in the wrong order.

11.4 Generating Smaller Patches

The simplest way to generate a patch is to use ‘diff -Naur’ (see Tips for Patch Producers), but you might be able to reduce the size of the patch by renaming or removing some files before making the patch. If the older version of the package contains any files that the newer version does not, or if any files have been renamed between the two versions, make a list of rm and mv commands for the user to execute in the old version directory before applying the patch. Then run those commands yourself in the scratch directory.

If there are any files that you don’t need to include in the patch because they can easily be rebuilt from other files (for example, TAGS and output from yacc and makeinfo), exclude them from the patch by giving diff the -x pattern option (see Comparing Directories). If you want your patch to modify a derived file because your recipients lack tools to build it, make sure that the patch for the derived file follows any patches for files that it depends on, so that the recipients’ timestamps will not confuse make.

Now you can create the patch using ‘diff -Naur’. Make sure to specify the scratch directory first and the newer directory second.

Add to the top of the patch a note telling the user any rm and mv commands to run before applying the patch. Then you can remove the scratch directory.

You can also shrink the patch size by using fewer lines of context, but bear in mind that patch typically needs at least two lines for proper operation when patches do not exactly match the input files.