\label{page_rdiff_md_doc_rdiff}%
\Hypertarget{page_rdiff_md_doc_rdiff}%
 \hypertarget{page_rdiff_autotoc_md70}{}\doxysubsection{Introduction}\label{page_rdiff_autotoc_md70}
{\itshape rdiff} is a program to compute and apply network deltas. An {\itshape rdiff delta} is a delta between binary files, describing how a {\itshape basis} (or {\itshape old}) file can be automatically edited to produce a {\itshape result} (or {\itshape new}) file.

Unlike most diff programs, librsync does not require access to both of the files when the diff is computed. Computing a delta requires just a short \char`\"{}signature\char`\"{} of the old file and the complete contents of the new file. The signature contains checksums for blocks of the old file. Using these checksums, rdiff finds matching blocks in the new file, and then computes the delta.

rdiff deltas are usually less compact and also slower to produce than xdeltas or regular text diffs. If it is possible to have both the old and new files present when computing the delta, \href{http://www.xcf.berkeley.edu/~jmacd/xdelta.html}{\texttt{ xdelta}} will generally produce a much smaller file. If the files being compared are plain text, then GNU \href{http://www.gnu.org/software/diffutils/diffutils.html}{\texttt{ diff}} is usually a better choice, as the diffs can be viewed by humans and applied as inexact matches.

rdiff comes into its own when it is not convenient to have both files present at the same time. One example of this is that the two files are on separate machines, and you want to transfer only the differences. Another example is when one of the files has been moved to archive or backup media, leaving only its signature.

Symbolically

\begin{quote}
signature({\itshape basis-\/file}) -\/\texorpdfstring{$>$}{>} {\itshape sig-\/file}

delta({\itshape sig-\/file}, {\itshape new-\/file}) -\/\texorpdfstring{$>$}{>} {\itshape delta-\/file}

patch({\itshape basis-\/file}, {\itshape delta-\/file}) -\/\texorpdfstring{$>$}{>} {\itshape recreated-\/file} \end{quote}
rdiff signatures and deltas are binary files in a format specific to rdiff. Signatures consist of a header, followed by a list of checksums for successive fixed-\/size blocks. Deltas consist of a header followed by an instruction stream, which when executed produces the output file. There are instructions to insert new data specified in the patch, or to copy data from the basis file.

Unlike regular text diffs, rdiff deltas can describe sections of the input file which have been reordered or copied.

Because block checksums are used to find identical sections, rdiff cannot find common sections smaller than one block, and it may not exactly identify common sections near changed sections. Changes that touch every block of the file, such as changing newlines to CRLF, are likely to cause no blocks to match at all.

rdiff does not deal with file metadata or structure, such as filenames, permissions, or directories. To rdiff, a file is just a stream of bytes. Higher-\/level tools, such as \href{http://rdiff-backup.stanford.edu/}{\texttt{ rdiff-\/backup}} can deal with these issues in a way appropriate to their users.\hypertarget{page_rdiff_autotoc_md71}{}\doxysubsection{Use patterns}\label{page_rdiff_autotoc_md71}
A typical application of the rsync algorithm is to transfer a file {\itshape A2} from a machine A to a machine B which has a similar file {\itshape A1}. This can be done as follows\+:


\begin{DoxyEnumerate}
\item B generates the rdiff signature of {\itshape A1}. Call this {\itshape S1}. B sends the signature to A. (The signature is usually much smaller than the file it describes.)
\item A computes the rdiff delta between {\itshape S1} and {\itshape A2}. Call this delta {\itshape D}. A sends the delta to B.
\item B applies the delta to recreate {\itshape A2}.
\end{DoxyEnumerate}

In cases where {\itshape A1} and {\itshape A2} contain runs of identical bytes, rdiff should give a significant space saving.\hypertarget{page_rdiff_autotoc_md72}{}\doxysubsection{Invoking rdiff}\label{page_rdiff_autotoc_md72}
There are three distinct modes of operation\+: {\itshape signature}, {\itshape delta} and {\itshape patch}. The mode is selected by the first command argument.\hypertarget{page_rdiff_autotoc_md73}{}\doxysubsubsection{signature}\label{page_rdiff_autotoc_md73}
\begin{quote}
rdiff \mbox{[}OPTIONS\mbox{]} signature INPUT SIGNATURE \end{quote}
{\bfseries{rdiff signature}} generates a signature file from an input file. The signature can later be used to generate a delta relative to the old file.\hypertarget{page_rdiff_autotoc_md74}{}\doxysubsubsection{delta}\label{page_rdiff_autotoc_md74}
\begin{quote}
rdiff \mbox{[}OPTIONS\mbox{]} delta SIGNATURE NEWFILE DELTA \end{quote}
{\bfseries{rdiff delta}} reads in a delta describing a basis file. It then calculates and writes a delta delta that transforms the basis into the new file.\hypertarget{page_rdiff_autotoc_md75}{}\doxysubsubsection{patch}\label{page_rdiff_autotoc_md75}
\begin{quote}
rdiff \mbox{[}OPTIONS\mbox{]} patch BASIS DELTA OUTPUT \end{quote}
rdiff applies a delta to a basis file and writes out the result.

rdiff cannot update files in place\+: the output file must not be the same as the input file.

rdiff does not currently check that the delta is being applied to the correct file. If a delta is applied to the wrong basis file, the results will be garbage.

The basis file must allow random access. This means it must be a regular file rather than a pipe or socket.\hypertarget{page_rdiff_autotoc_md76}{}\doxysubsubsection{Global Options}\label{page_rdiff_autotoc_md76}
These options are available for all commands.

{\ttfamily -\/-\/version} Show program version and copyright.

{\ttfamily -\/-\/help} Show brief help message.

{\ttfamily -\/-\/statistics} Show counts of internal operations.

{\ttfamily -\/-\/debug} Write debugging information to stderr.

Options must be specified before the command name.\hypertarget{page_rdiff_autotoc_md77}{}\doxysubsection{Return Value}\label{page_rdiff_autotoc_md77}
0\+: Successful completion.

1\+: Environmental problems (file not found, invalid options, IO error, etc).

2\+: Corrupt signature or delta file.

3\+: Internal error or unhandled situation in librsync or rdiff.\hypertarget{page_rdiff_autotoc_md78}{}\doxysubsection{Bugs}\label{page_rdiff_autotoc_md78}
Unlike text patches, rdiff deltas can only be usefully applied to the exact basis file that they were generated from. rdiff does not protect against trying to apply a delta to the wrong file, though this will produce garbage output. It may be useful to store a hash of the file to which the digest is meant to be applied.\hypertarget{page_rdiff_autotoc_md79}{}\doxysubsection{Author}\label{page_rdiff_autotoc_md79}
rdiff was written by Martin Pool. The original rsync algorithm was discovered by Andrew Tridgell.

This program is part of the \href{http://librsync.sourcefrog.net/}{\texttt{ librsync}} package. 