README

   1  -*- Text -*-
   2
   3                Xdelta -- A binary delta generator
   4
   5 Announcing version 1.1.2 of Xdelta.  Xdelta is an application program
   6 designed to compute changes between files.  These changes (deltas) are
   7 similar to the output of the "diff" program in that they may be used
   8 to store and transmit only the changes between files.  However, unlike
   9 diff, the output of Xdelta is not expressed in a human-readable
  10 format--Xdelta can also also apply these deltas to a copy of the
  11 original file.  Xdelta uses a fast, linear algorithm and performs well
  12 on both binary and text files.
  13
  14 Xdelta 1.1.2 is a stable, maintenence release.  New, ongoing work on
  15 Xdelta has focused on a new storage system with features similar to
  16 the RCS command set.  For more information on new development, see the
  17 Xdelta-2.0 release series at http://xdelta.sourceforge.net.
  18
  19 Xdelta was designed and implemented by Joshua MacDonald.  The delta
  20 algorithm is based on the Rsync algorithm, though implementation and
  21 interface considerations leave the two programs quite distinct.  The
  22 Rsync algorithm is due to Andrew Tridgell and Paul Mackerras.
  23
  24 To compile and install Xdelta, read the instructions in the INSTALL
  25 file.  Once you have done this, you should at least read the first few
  26 sections of the documentation.  It is available in info format.  All
  27 documentation is located in the doc/ subdirectory.
  28
  29 This release, version 1.1.2, and future releases of Xdelta can be
  30 found at http://xdelta.sourceforge.net.
  31
  32 Xdelta is released under the GNU Library Public License (GPL), see the
  33 file COPYING for details.
  34
  35 There is mailing list for announcements:
  36
  37    xdelta-announce@lists.sourceforge.net
  38
  39 you can subscribe to the mailing list or file bug reports through
  40 Sourceforge at:
  41
  42    http://sourceforge.net/projects/xdelta/
  43
  44 Comments about Xdelta can be addressed to the following addresses:
  45
  46    jmacd@cs.berkeley.edu
  47
  48 The man page describes how to use Xdelta in more detail:
  49
  50 NAME
  51        xdelta - Invoke Xdelta
  52
  53 SYNOPSIS
  54        xdelta subcommand [ option...  ] [ operand...  ]
  55
  56 DESCRIPTION
  57
  58        Xdelta provides the ability to generate deltas between a pair
  59        of files and later apply those deltas.  It operates similar to
  60        the diff and patch commands, but works on binary files and does
  61        not produce a human readable output.
  62
  63        Xdelta has three subcommands, delta, patch, and info.  Delta
  64        accepts two file versions and produces a delta, while patch
  65        accepts the original file version and delta and produces the
  66        second version.  The info command prints useful information
  67        about a delta.  Each subcommand will be detailed seperately.
  68
  69    Gzip processing
  70
  71        Attempting to compute a delta between compressed input files
  72        usually results in poor compression.  This is because small
  73        differences between the original contents causes changes in the
  74        compression of whole blocks of data.  To simplify things,
  75        Xdelta implements a special case for gzip(1) compressed files.
  76        If any version input to the delta command is recognized as
  77        having gzip compression, it will be automatically decompressed
  78        into a temporary location prior to comparison.  This temporary
  79        location is either the value of the TMPDIR environment
  80        variable, if set, otherwise "/tmp".
  81
  82        The Xdelta patch header contains a flag indicating that the
  83        reconstructed version should be recompressed after applying
  84        the patch.  In general, this allows Xdelta to operate
  85        transparently on gzip compressed inputs.
  86
  87        There is one potential problem when automatically processing
  88        gzip compressed files, which is that the recompressed content
  89        does not always match byte-for-byte with the original
  90        compressed content.  The uncompressed content still matches,
  91        but if there is an external integrity check such as
  92        cryptographic signature verification, it may fail.  To prevent
  93        this from happening, the --pristine option disables automatic
  94        gzip processing.
  95
  96    MD5 integrity check
  97
  98        By default, Xdelta always verifies the MD5 checksum of the
  99        files it reconstructs.  This prevents you from supplying an
 100        incorrect input during patch, which would result in corrupt
 101        output.  Because of this feature, you can feel confident that
 102        patch has produced valid results.  The --noverify option
 103        disables MD5 verification, but this is only recommended for
 104        performance testing.
 105
 106    Compressed patch format
 107
 108        Xdelta uses a fairly simple encoding for its delta, then
 109        applies zlib compression to the result.  You should not have to
 110        post-compress an Xdelta delta.
 111
 112    Delta
 113
 114        The delta subcommand has the following synopsis:
 115
 116        xdelta delta [ option...  ] fromfile tofile patchout
 117
 118        Computes a delta from fromfile to tofile and writes it to patchout
 119
 120    Patch
 121
 122        The patch subcommand has the following synopsis:
 123
 124        xdelta patch [ option...  ] patchin [ fromfile [ tofile ]]
 125
 126        Applies patchin to fromfile and produces a reconstructed
 127        version of tofile.
 128
 129        If fromfile was omitted, Xdelta attempts to use the original
 130        fromfile name, which is stored in the delta.  The from file
 131        must be identical to the one used to create the delta.  If its
 132        length or MD5 checksum differs, patch will abort with an error
 133        message.
 134
 135        If tofile was omitted, Xdelta attempts to use the original
 136        tofile name, which is also stored in the delta.  If the
 137        original tofile name already exists, a unique filename
 138        extension will be added to avoid destroying any existing data.
 139
 140    Info
 141        The info subcommand has the following synopsis:
 142
 143        xdelta info patchinfo
 144
 145        Prints information about patchinfo and the version it
 146        reconstructs, including file names, lengths, and MD5 checksums.
 147
 148    Options
 149        -0..9  Set  the  zlib compression level.  Zero indicates no
 150               compression.  Nine indicates maximum compression.
 151
 152        -h, --help
 153               Print a short help message and exit.
 154
 155        -q, --quiet
 156               Quiet.  Surpresses several warning messages.
 157
 158        -v, --version
 159               Print the Xdelta version number and exit.
 160
 161        -V, --verbose
 162               Verbose.  Prints a bit of extra information.
 163
 164        -n, --noverify
 165               No verify.  Turns off MD5 checksum verification of the
 166               input and output files.
 167
 168        -m=SIZE, --maxmem=SIZE
 169               Set an upper bound on the size of an in-memory page
 170               cache. For example, --maxmem=32M will use a 32 megabyte
 171               page cache.
 172
 173        -s=BLOCK_SIZE
 174               Set the block size, unless it was hard coded (20% speed
 175               improvement).  Should be a power of 2.
 176
 177        -p, --pristine
 178               Disable  the  automatic  decompression of gzipped
 179               inputs,  to prevent unexpected differences in the
 180               re-compressed content.