diffutils: Avoiding Common Mistakes
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.