$treeview $search $mathjax $extrastylesheet
librsync
2.0.2
$projectbrief
|
$projectbrief
|
$searchbox |
00001 # rdiff {#rdiff} 00002 00003 Introduction 00004 ============ 00005 00006 *rdiff* is a program to compute and apply network deltas. An *rdiff 00007 delta* is a delta between binary files, describing how a *basis* (or 00008 *old*) file can be automatically edited to produce a *result* (or *new*) 00009 file. 00010 00011 Unlike most diff programs, librsync does not require access to both of 00012 the files when the diff is computed. Computing a delta requires just a 00013 short "signature" of the old file and the complete contents of the new 00014 file. The signature contains checksums for blocks of the old file. Using 00015 these checksums, rdiff finds matching blocks in the new file, and then 00016 computes the delta. 00017 00018 rdiff deltas are usually less compact and also slower to produce than 00019 xdeltas or regular text diffs. If it is possible to have both the old 00020 and new files present when computing the delta, 00021 [xdelta](http://www.xcf.berkeley.edu/~jmacd/xdelta.html) will generally 00022 produce a much smaller file. If the files being compared are plain text, 00023 then GNU [diff](http://www.gnu.org/software/diffutils/diffutils.html) is 00024 usually a better choice, as the diffs can be viewed by humans and 00025 applied as inexact matches. 00026 00027 rdiff comes into its own when it is not convenient to have both files 00028 present at the same time. One example of this is that the two files are 00029 on separate machines, and you want to transfer only the differences. 00030 Another example is when one of the files has been moved to archive or 00031 backup media, leaving only its signature. 00032 00033 Symbolically 00034 00035 > signature(*basis-file*) -> *sig-file* 00036 > 00037 > delta(*sig-file*, *new-file*) -> *delta-file* 00038 > 00039 > patch(*basis-file*, *delta-file*) -> *recreated-file* 00040 00041 rdiff signatures and deltas are binary files in a format specific to 00042 rdiff. Signatures consist of a header, followed by a list of checksums 00043 for successive fixed-size blocks. Deltas consist of a header followed by 00044 an instruction stream, which when executed produces the output file. 00045 There are instructions to insert new data specified in the patch, or to 00046 copy data from the basis file. 00047 00048 Unlike regular text diffs, rdiff deltas can describe sections of the 00049 input file which have been reordered or copied. 00050 00051 Because block checksums are used to find identical sections, rdiff 00052 cannot find common sections smaller than one block, and it may not 00053 exactly identify common sections near changed sections. Changes that 00054 touch every block of the file, such as changing newlines to CRLF, are 00055 likely to cause no blocks to match at all. 00056 00057 rdiff does not deal with file metadata or structure, such as filenames, 00058 permissions, or directories. To rdiff, a file is just a stream of bytes. 00059 Higher-level tools, such as 00060 [rdiff-backup](http://rdiff-backup.stanford.edu/) can deal with these 00061 issues in a way appropriate to their users. 00062 00063 Use patterns 00064 ============ 00065 00066 A typical application of the rsync algorithm is to transfer a file *A2* 00067 from a machine A to a machine B which has a similar file *A1*. This can 00068 be done as follows: 00069 00070 1. B generates the rdiff signature of *A1*. Call this *S1*. B sends the 00071 signature to A. (The signature is usually much smaller than the file 00072 it describes.) 00073 2. A computes the rdiff delta between *S1* and *A2*. Call this delta 00074 *D*. A sends the delta to B. 00075 3. B applies the delta to recreate *A2*. 00076 00077 In cases where *A1* and *A2* contain runs of identical bytes, rdiff 00078 should give a significant space saving. 00079 00080 Invoking rdiff 00081 ============== 00082 00083 There are three distinct modes of operation: *signature*, *delta* and 00084 *patch*. The mode is selected by the first command argument. 00085 00086 signature 00087 --------- 00088 00089 > rdiff \[OPTIONS\] signature INPUT SIGNATURE 00090 00091 **rdiff signature** generates a signature file from an input file. The 00092 signature can later be used to generate a delta relative to the old 00093 file. 00094 00095 delta 00096 ----- 00097 00098 > rdiff \[OPTIONS\] delta SIGNATURE NEWFILE DELTA 00099 00100 **rdiff delta** reads in a delta describing a basis file. It then 00101 calculates and writes a delta delta that transforms the basis into the 00102 new file. 00103 00104 patch 00105 ----- 00106 00107 > rdiff \[OPTIONS\] patch BASIS DELTA OUTPUT 00108 00109 rdiff applies a delta to a basis file and writes out the result. 00110 00111 rdiff cannot update files in place: the output file must not be the same 00112 as the input file. 00113 00114 rdiff does not currently check that the delta is being applied to the 00115 correct file. If a delta is applied to the wrong basis file, the results 00116 will be garbage. 00117 00118 The basis file must allow random access. This means it must be a regular 00119 file rather than a pipe or socket. 00120 00121 Global Options 00122 -------------- 00123 00124 These options are available for all commands. 00125 00126 `--version` Show program version and copyright. 00127 00128 `--help` Show brief help message. 00129 00130 `--statistics` Show counts of internal operations. 00131 00132 `--debug` Write debugging information to stderr. 00133 00134 Options must be specified before the command name. 00135 00136 Return Value 00137 ============ 00138 00139 0: Successful completion. 00140 00141 1: Environmental problems (file not found, invalid options, IO 00142 error, etc). 00143 00144 2: Corrupt signature or delta file. 00145 00146 3: Internal error or unhandled situation in librsync or rdiff. 00147 00148 Bugs 00149 ==== 00150 00151 Unlike text patches, rdiff deltas can only be usefully applied to the 00152 exact basis file that they were generated from. rdiff does not protect 00153 against trying to apply a delta to the wrong file, though this will 00154 produce garbage output. It may be useful to store a hash of the file to 00155 which the digest is meant to be applied. 00156 00157 Author 00158 ====== 00159 00160 rdiff was written by Martin Pool. The original rsync algorithm was 00161 discovered by Andrew Tridgell. 00162 00163 This program is part of the [librsync](http://librsync.sourcefrog.net/) 00164 package.