---

   patch    ( 1 )

---

NOTES FOR PATCH SENDERS

There are several things you should bear in mind if you are going to be sending out patches.

Create your patch systematically. A good method is 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 diff command's headers should have dates and times in Universal Time using traditional Unix format, so that patch recipients can use the -Z or --set-utc option. Here is an example command, using Bourne shell syntax:

LC_ALL=C TZ=UTC0 diff -Naur gcc-2.7 gcc-2.8

Tell your recipients how to apply the patch by telling them which directory to cd to, and which patch options to use. The option string -Np1 is recommended. Test your procedure by pretending to be a recipient and applying your patch to a copy of the original files.

You can save people a lot of grief by keeping a patchlevel.h file which is patched to increment the patch level as the first diff in the patch file you send out. If you put a Prereq: line in with the patch, it won't let them apply patches out of order without some warning.

You can create a file by sending out a diff that compares /dev/null or an empty file dated the Epoch (1970-01-01 00:00:00 UTC) to the file you want to create. This only works if the file you want to create doesn't exist already in the target directory. Conversely, you can remove a file by sending out a context diff that compares the file to be deleted with an empty file dated the Epoch. The file will be removed unless patch is conforming to POSIX and the -E or --remove-empty-files option is not given. An easy way to generate patches that create and remove files is to use GNU diff's -N or --new-file option.

If the recipient is supposed to use the -pN option, do not send output that looks like this:

diff -Naur v2.0.29/prog/README prog/README --- v2.0.29/prog/README Mon Mar 10 15:13:12 1997 +++ prog/README Mon Mar 17 14:58:22 1997

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 Mon Mar 10 15:13:12 1997 +++ v2.0.30/prog/README Mon Mar 17 14:58:22 1997

Avoid sending patches that compare backup file names like README.orig, 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.

Take care not to send out reversed patches, since it makes people wonder whether they already applied the patch.

Try not to have your patch modify derived files (e.g. the file configure where there is a line configure: configure.in in your makefile), since the recipient should be able to regenerate the derived files anyway. If you must send diffs of derived files, generate the diffs using UTC, have the recipients apply the patch with the -Z or --set-utc option, and have them remove any unpatched files that depend on patched files (e.g. with make clean).

While you may be able to get away with putting 582 diff listings into one file, it may be wiser to group related patches into separate files in case something goes haywire.