This is the makepatch package, containing a pair of programs to assist
in the generation and application of patch kits to synchronise source
trees.

INTRODUCTION

Traditionally, source trees are updated with the 'patch' program,
processing patch information that is generated by the 'diff' program.
Although 'diff' and 'patch' do a very good job at patching file
contents, most versions do not handle creating and deleting files and
directories, and adjusting of file modes and time stamps. Newer
versions of 'diff' and 'patch' seem to be able to create files, and
very new versions of 'patch' can remove files. But that's about it.

Another typical problem is that patch kits are typically downloaded
from the Internet, or transmitted via electronic mail. It is often
desirable to verify the correctness of a patch kit before even
attempting to apply it.

The makepatch package is designed to overcome these limitations.

DESCRIPTION

The makepatch package contains two programs, both written in Perl:
'makepatch' and 'applypatch'.

'makepatch' will generate a patch kit from two source trees. 
It traverses the source directory and runs a 'diff' on each pair of
corresponding files, accumulating the output into a patch kit. It
knows about the conventions for patch kits: if a file named
patchlevel.h exists, it is handled first, so 'patch' can check the
version of the source tree. Also, to deal with the non-perfect
versions of 'patch' that are in use, it supplies 'Index:' and
'Prereq:' lines, so 'patch' can correctly locate the files to patch,
and it relocates the patch to the current directory to avoid problems
with creating new files.

The list of files can be specified in a so called 'manifest' file, but
it can also be generated by recursively traversing the source tree.
Files can be excluded using shell style wildcards and Perl regex
patterns.

Moreover, 'makepatch' prepends a small shell script in front of the
patch kit that creates the necessary files and directories for the
patch process. By running the patch kit as a shell script your source
directory is prepared for the patching process.

But that is not it! 'makepatch' also inserts some additional
information in the patch kit for use by the 'applypatch' program.

The 'applypatch' program will do the following:

  - It will extensively verify that the patch kit is complete and not
    corrupted during transfer.
  - It will apply some heuristics to verify that the directory in
    which the patch will be applied does indeed contain the expected
    sources.
  - It creates files and directories as necessary.
  - It applies the patch by running the 'patch' program.
  - Upon completion, obsolete files, directories and .orig files are
    removed, file modes of new files are set, and the timestamps of
    all patched files are adjusted.

Note that 'applypatch' only requires the 'patch' program. It does not
rely on a shell or shell tools. This makes it possible to apply
patches on non-Unix systems.

REQUIREMENTS

  - Perl 5.004 standard installation.
  - For 'makepatch': the 'diff' program.
  - For 'applypatch': the 'patch' program.

--------------------------------------------------------------------------
Johan Vromans                                         jvromans@squirrel.nl
Squirrel Consultancy                              Haarlem, the Netherlands
http://www.squirrel.nl              http://www.squirrel.nl/people/jvromans
PGP Key 2048/4783B14D KFP=65 44 CA 66 B3 50 0B 34  CE 0E FB CA 2D 95 34 D0
---------------------- "Arms are made for hugging" -----------------------
