1 -*- Text -*-
2
3 Xdelta -- A binary delta generator
4
5Announcing version 1.1.2 of Xdelta. Xdelta is an application program
6designed to compute changes between files. These changes (deltas) are
7similar to the output of the "diff" program in that they may be used
8to store and transmit only the changes between files. However, unlike
9diff, the output of Xdelta is not expressed in a human-readable
10format--Xdelta can also also apply these deltas to a copy of the
11original file. Xdelta uses a fast, linear algorithm and performs well
12on both binary and text files.
13
14Xdelta 1.1.2 is a stable, maintenence release. New, ongoing work on
15Xdelta has focused on a new storage system with features similar to
16the RCS command set. For more information on new development, see the
17Xdelta-2.0 release series at http://xdelta.sourceforge.net.
18
19Xdelta was designed and implemented by Joshua MacDonald. The delta
20algorithm is based on the Rsync algorithm, though implementation and
21interface considerations leave the two programs quite distinct. The
22Rsync algorithm is due to Andrew Tridgell and Paul Mackerras.
23
24To compile and install Xdelta, read the instructions in the INSTALL
25file. Once you have done this, you should at least read the first few
26sections of the documentation. It is available in info format. All
27documentation is located in the doc/ subdirectory.
28
29This release, version 1.1.2, and future releases of Xdelta can be
30found at http://xdelta.sourceforge.net.
31
32Xdelta is released under the GNU Library Public License (GPL), see the
33file COPYING for details.
34
35There is mailing list for announcements:
36
37 xdelta-announce@lists.sourceforge.net
38
39you can subscribe to the mailing list or file bug reports through
40Sourceforge at:
41
42 http://sourceforge.net/projects/xdelta/
43
44Comments about Xdelta can be addressed to the following addresses:
45
46 jmacd@cs.berkeley.edu
47
48The man page describes how to use Xdelta in more detail:
49
50NAME
51 xdelta - Invoke Xdelta
52
53SYNOPSIS
54 xdelta subcommand [ option... ] [ operand... ]
55
56DESCRIPTION
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.
181