Whole document tree

Tips for Making Patch Distributions

Here are some things you should keep in mind if you are going to distribute patches for updating a software package.

Make sure you have specified the file names correctly, either in a context diff header or with an `Index:' line. If you are patching files in a subdirectory, be sure to tell the patch user to specify a `-p' or `--strip' option as needed. Take care to not send out reversed patches, since these make people wonder whether they have already applied the patch.

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.

Since patch does not handle incomplete lines properly, make sure that all the source files in your program end with a newline whenever you release a version.

To create a patch that changes an older version of a package into a newer version, first make a copy of the older version in a scratch directory. Typically you do that by unpacking a tar or shar archive of the older version.

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), replace the versions in the scratch directory with the newer versions, using rm and ln or cp.

Now you can create the patch. The de-facto standard diff format for patch distributions is context format with two lines of context, produced by giving diff the `-C 2' option. Do not use less than two lines of context, because patch typically needs at least two lines for proper operation. Give diff the `-P' option in case the newer version of the package contains any files that the older one does not. 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.

Go to the first, previous, next, last section, table of contents.