The Art of Patch

[Michael van Acken <mvacken@t-online.de>]

I was reminded that patching can be a rather arcane art, only
available to the initiated.  Because it is such a useful tool for
keeping up to date with the latest developments, I will summarize
potential pitfals I know of here.


Which `patch' to use?
=====================

The `patch' command distributed by the OS vendor may or may not know
about the unified output format of GNU `diff'.  Unfortunately almost
all patch files on the internet are generated with this output format.
This format can easily be scanned and understood by a human reader,
and such a patch can be applied to files that differ (within limits)
from the original file from which the patch was generated.  

If the preinstalled `patch' does not understand the format of the diff
file, you need to install a copy of GNU `patch' yourself.  Versions
prior to 2.4(?) did not accept lines longer than 1024 characters.
Such a line caused `patch' to abort and to report incorrectly a broken
input file.  Humans usually do not write long lines, but files written
by programs can easily exceed this length.  In the oo2c distribution
this is the case for the files `ChangeLog' and `src.c/makefile.oo2c.in'.

If you run into troubles I suggest to install the GNU `patch'.  AFAIK
the current version is 2.5.


Invoking `patch'
================

There are various ways to generate patch files by means of the `diff'
command.  The invokation of `patch' depends to a certain degree on the
settings used for the patch file.  I will only describe how to install
ooc and oo2c diff files, although this particular format is used for
most of the patch files floating around in the net.

Assuming you have oo2c-1.3.10, and want to upgrade it to 1.3.11, you
should do this:

1. Unpack the old source archive, say oo2c_32-1.3.10.tar.gz.  (If you
   have it already unpacked and used it for installation, you should do
   "make distclean" in the top-level directory.)

2. Change into the top-level directory, e.g. with "cd oo2c_32-1.3.10".

3. Feed the unpacked diff file to `patch', e.g. by doing
     gzip -cd ../oo2c_32-1.3.10-1.3.11.diff.gz | patch -p1
   The option "-p1" tells `patch' to ignore the first directory part
   of the file names in the diff.

4. To update to higher version numbers, repeat step 3 and apply
   sucessive patch files in order.

Note: If you discover that files that were not in the original tar
file are created by `patch' in the wrong directory, chances are high
that you missed the "-p1" option and/or started the process from the
wrong directory.

Older versions of patch leave backup copies of modified files lying
around, e.g. with the name suffix ".orig".  These files can be ignored
or removed (e.g. by a suitable combination of `find' and `rm'):

-- mva