GNU Info

(diff.info)Making Patches

---

Next: Invoking cmp Prev: Merging with patch Up: Top

---

Enter node , (file) or (file)node

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.