Fix for batch mode (was Re: batch mode maintainability)
Jos Backus
josb at cncdsl.com
Fri Feb 1 09:43:47 EST 2002
Thanks to Alberto Accomazzi and Dave Dykstra for their comments. Please have a
look at the updated version below.
On Thu, Jan 31, 2002 at 11:28:46AM -0600, Dave Dykstra wrote:
> Refer people to the BATCH MODE section for more details.
Done.
> The opening description should be easily understandable by somebody who
> approaches it for the first time, and I don't think this fits the bill.
Yes it was rather dense and cryptic, hopefully this new version is more
readable.
> I think it should describe why somebody would want to use it, then it can
> jump into the details about how it does it.
Not sure whether I have specied enough details yet but it should be better.
> I think "also performs the operations on the target" would be more accurate
> than saying it makes the target identical to the source; it depends on the
> other parameters.
Yes, fixed.
Index: rsync.1
===================================================================
RCS file: /cvsroot/rsync/rsync.1,v
retrieving revision 1.108
diff -u -r1.108 rsync.1
--- rsync.1 29 Jan 2002 21:52:56 -0000 1.108
+++ rsync.1 31 Jan 2002 22:45:49 -0000
@@ -306,8 +306,8 @@
--log-format=FORMAT log file transfers using specified format
--password-file=FILE get password from FILE
--bwlimit=KBPS limit I/O bandwidth, KBytes per second
- --read-batch=FILE read batch file
- --write-batch write batch file
+ --write-batch=PREFIX write batch fileset starting with PREFIX
+ --read-batch=PREFIX read batch fileset starting with PREFIX
-h, --help show this help screen
@@ -801,12 +801,14 @@
result is an average transfer rate equalling the specified limit\&. A value
of zero specifies no limit\&.
.IP
-.IP "\fB--read-batch\fP"
-Apply a previously generated change batch\&.
-.IP
-.IP "\fB--write-batch\fP"
-Generate a set of files that can be transferred
-as a batch update\&.
+.IP "\fB--write-batch=PREFIX\fP"
+Generate a set of files that can be transferred as a batch update\&. Each
+filename in the set starts with \fBPREFIX\fP. See the "BATCH MODE" section
+for details.
+.IP
+.IP "\fB--read-batch=PREFIX\fP"
+Apply a previously generated change batch, using the fileset whose filenames
+start with \fBPREFIX\fP\&. See the "BATCH MODE" section for details.
.IP
.PP
.SH "EXCLUDE PATTERNS"
@@ -913,29 +915,77 @@
\fBNote:\fP Batch mode should be considered experimental in this version
of rsync\&. The interface or behaviour may change before it stabilizes\&.
.PP
-The following call generates 4 files that encapsulate the information
-for synchronizing the contents of \fBtarget_dir\fP with the updates found in
-\fBsrc_dir\fP
-.PP
+Batch mode can be used to apply the same set of updates to many identical
+systems\&. Suppose one has a directory tree which is replicated on a number of
+hosts\&. Now suppose some changes have to be made to this source directory tree
+and those changes need to be propagated to the other hosts\&. In order to do
+this using batch mode, the first step is to make a copy of the source
+directory tree before the changes are applied; this is called the original
+source directory tree\&. The changes are then applied to the new source
+directory tree\&. Next, rsync is run with the write-batch option to apply the
+changes made to the new source directory tree to the original source directory
+tree\&. The write-batch option causes the information needed to repeat this
+operation against another original source directory tree to be stored in a
+batch update fileset (see below) by the rsync client\&. The filename of each
+file in the fileset starts with a prefix specified by the user as an argument
+to the write-batch option\&. This fileset is then copied to each remote host,
+where rsync is run with the read-batch option, again specifying the same
+prefix, and the source directory tree\&. Rsync updates the source directory
+tree using the information stored in the batch update fileset\&.
+.PP
+The fileset consists of 4 files:
+.IP o
+<prefix>\fB.rsync_argvs\fP command-line arguments
+.IP o
+<prefix>\fB.rsync_flist\fP rsync internal file metadata
+.IP o
+<prefix>\fB.rsync_csums\fP rsync checksums
+.IP o
+<prefix>\fB.rsync_delta\fP data blocks for file update & change
+.PP
+The .rsync_argvs file contains a command-line suitable for updating a source
+directory tree using that batch update fileset\&. It can be executed using a
+Bourne(-like) shell, optionally passing in an alternate source directory tree
+pathname\& which is then used instead of the original path\&. This is useful
+when the source directory tree path differs from the original source directory
+tree path\&.
+.PP
+Generating the batch update fileset once saves having to perform the file
+status, checksum and data block generation more than once when updating
+multiple source directory trees\&. Multicast transport protocols can be used
+to transfer the batch update files in parallel to many hosts at once, instead
+of sending the same data to every host individually\&.
+.PP
+Example:
+.PP
.RS
-$ rsync --write-batch [other rsync options here] \e
+$ rsync --write-batch=some_update [other rsync options] \e
.br
-/somewhere/src_dir /somewhere/target_dir
+/this/source/dir /this/original/dir
.RE
+.RS
+$ rsync --read-batch=some_update [other rsync options] \e
+.br
+/that/original/dir
+.RE
+.PP
+\fBCaveats\fP:
+.IP o
+The read-batch option expects the source directory tree it is meant to update
+to be identical to the source directory tree that was used to create the batch
+update fileset\&. When a difference between the source directory trees is
+encountered the update will fail at that point, leaving the source directory
+tree in a partially updated state\&. In that case, rsync can be used in its
+regular (non-batch) mode of operation to fix up the source directory tree\&.
+.IP o
+The -z/--compress option does not work in batch mode and yields a usage
+error\&.
+.IP o
+The -n/--dryrun option does not work in batch mode and yields a runtime
+error\&.
.PP
-The generated files are labeled with a common timestamp:
-.PP
-.IP o
-\fBrsync_argvs\&.<timestamp>\fP command-line arguments
-.IP o
-\fBrsync_flist\&.<timestamp>\fP rsync internal file metadata
-.IP o
-\fBrsync_csums\&.<timestamp>\fP rsync checksums
-.IP o
-\fBrsync_delta\&.<timestamp>\fP data blocks for file update & change
-.PP
-See \fBhttp://www\&.ils\&.unc\&.edu/i2dsi/unc_rsync+\&.html\fP for papers and technical
-reports\&.
+See \fBhttp://www\&.ils\&.unc\&.edu/i2dsi/unc_rsync+\&.html\fP for papers and
+technical reports\&.
.PP
.SH "SYMBOLIC LINKS"
.PP
--
Jos Backus _/ _/_/_/ Santa Clara, CA
_/ _/ _/
_/ _/_/_/
_/ _/ _/ _/
josb at cncdsl.com _/_/ _/_/_/ use Std::Disclaimer;
More information about the rsync
mailing list