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.