[PATCH] Batch-mode rewrite, update to man page

[Chris Shoemaker]

I've attached an update to the man page regarding batch mode.  I didn't
change the statement about batch mode being experimental, but maybe we
should consider modifying it.
	It did serve well to manage my expectations when I first tried batch
mode and found that it didn't work at all for use with remote servers.
Unfortunately, I think "experimental" was a euphemism for "easily broken".
	After my re-write, I'm hoping batch-mode will be more stable and
easier to maintain.  (But, maybe it just has new bugs. ;-)  Of course, it is
still "experimental" in that it hasn't been widely tested.
	I'd probably be in favor of adding some encouraging statement to
the "experimental" warning, so that people aren't scared away from it.
Maybe something like:  "However, the existing behavior and interface
is a candidate for stable functionality."

	The reason I think this may be in order is that I think the
concept of operation has been well-defined for quite a while.  It was
only the implementation that was "experimental".  The new implementation
really is simpler, and hopefully more robust.

	Any thoughts?

-chris
-------------- next part --------------
Index: rsync.yo
===================================================================
RCS file: /cvsroot/rsync/rsync.yo,v
retrieving revision 1.171
diff -u -r1.171 rsync.yo
--- rsync.yo	5 Jun 2004 16:16:30 -0000	1.171
+++ rsync.yo	14 Jul 2004 22:33:48 -0000
@@ -347,8 +347,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
-     --write-batch=PREFIX    write batch fileset starting with PREFIX
-     --read-batch=PREFIX     read batch fileset starting with PREFIX
+     --write-batch=FILE      write a batch to FILE 
+     --read-batch=FILE       read a batch from FILE
      --checksum-seed=NUM     set block/file checksum seed
  -4  --ipv4                  prefer IPv4
  -6  --ipv6                  prefer IPv6
@@ -897,13 +897,13 @@
 result is an average transfer rate equaling the specified limit. A value
 of zero specifies no limit.
 
-dit(bf(--write-batch=PREFIX)) Generate a set of files that can be
-transferred as a batch update. Each filename in the set starts with
-PREFIX. See the "BATCH MODE" section for details.
-
-dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch,
-using the fileset whose filenames start with PREFIX. See the "BATCH
-MODE" section for details.
+dit(bf(--write-batch=FILE)) Record a file that can later be applied to
+anonther identical destination with --read-batch. See the "BATCH MODE"
+section for details.
+
+dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
+file previously generated by --write-batch. See the "BATCH MODE"
+section for details.
 
 dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
 when creating sockets.  This only affects sockets that rsync has direct
@@ -917,16 +917,12 @@
 dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
 NUM.  This 4 byte checksum seed is included in each block and file
 MD4 checksum calculation.  By default the checksum seed is generated
-by the server and defaults to the current time(), or 32761 if
-bf(--write-batch) or bf(--read-batch) are specified.  This option
+by the server and defaults to the current time().  This option
 is used to set a specific checksum seed, which is useful for
 applications that want repeatable block and file checksums, or
 in the case where the user wants a more random checksum seed.
 Note that setting NUM to 0 causes rsync to use the default of time()
-for checksum seed.  Note also that bf(--write-batch) and bf(--read-batch)
-set the checksum seed to 32761, so bf(--checksum-seed=NUM) needs to
-follow these options if you want to specify a different checksum
-seed in batch mode.
+for checksum seed.
 
 enddit()
 
@@ -1107,53 +1103,45 @@
 hosts. In order to do this using batch mode, rsync is run with the
 write-batch option to apply the changes made to the source tree to one
 of the destination trees.  The write-batch option causes the rsync
-client to store the information needed to repeat this operation against
-other destination trees in a batch update fileset (see below).  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 destination tree.
-Rsync updates the destination tree using the information stored in the
-batch update fileset.
+client to store in a "batch file" all the information needed to repeat
+this operation against other, identical destination trees.
 
-The fileset consists of 4 files:
+To apply the recorded changes to another destination tree, run rsync
+with the read-batch option, specifying the name of the same batch
+file, and the destination tree.  Rsync updates the destination tree
+using the information stored in the batch file.
+
+For convenience, one additional file is creating when the write-batch
+option is used.  This file's name is created by appending
+".rsync_argvs" to the batch filename.  The .rsync_argvs file contains
+a command-line suitable for updating a destination tree using that
+batch file. It can be executed using a Bourne(-like) shell, optionally
+passing in an alternate destination tree pathname which is then used
+instead of the original path. This is useful when the destination tree
+path differs from the original destination tree path.
 
-itemize(
-it() bf(<prefix>.rsync_argvs) command-line arguments
-it() bf(<prefix>.rsync_flist) rsync internal file metadata
-it() bf(<prefix>.rsync_csums) rsync checksums
-it() bf(<prefix>.rsync_delta) data blocks for file update & change
-)
-
-The .rsync_argvs file contains a command-line suitable for updating a
-destination tree using that batch update fileset. It can be executed
-using a Bourne(-like) shell, optionally passing in an alternate
-destination tree pathname which is then used instead of the original
-path. This is useful when the destination tree path differs from the
-original destination tree path.
-
-Generating the batch update fileset once saves having to perform the
-file status, checksum and data block generation more than once when
+Generating the batch file once saves having to perform the file
+status, checksum and data block generation more than once when
 updating multiple destination 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.
+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.
 
 Example:
 
 verb(
-   $ rsync --write-batch=pfx -a /source/dir/ /adest/dir/
-   $ rcp pfx.rsync_* remote:
-   $ ssh remote rsync --read-batch=pfx -a /bdest/dir/
+   $ rsync --write-batch=batch -a /source/dir/ /adest/dir/
+   $ rcp batch* remote:
+   $ ssh remote rsync --read-batch=batch -a /bdest/dir/
    # or alternatively
-   $ ssh remote ./pfx.rsync_argvs /bdest/dir/
+   $ ssh remote ./batch.rsync_argvs /bdest/dir/
 )
 
 In this example, rsync is used to update /adest/dir/ with /source/dir/
-and the information to repeat this operation is stored in the files
-pfx.rsync_*. These files are then copied to the machine named "remote".
-Rsync is then invoked on "remote" to update /bdest/dir/ the same way as
-/adest/dir/. The last line shows the rsync_argvs file being used to
-invoke rsync.
+and the information to repeat this operation is stored in "batch" and
+"batch.rsync_argvs". These files are then copied to the machine named
+"remote".  Rsync is then invoked on "remote" to update /bdest/dir/ the
+same way as /adest/dir/. The last line shows the rsync_argvs file
+being used to invoke rsync.
 
 Caveats:
 
@@ -1168,10 +1156,6 @@
 The rsync version used on all destinations should be identical to the
 one used on the original destination.
 
-The -z/--compress option does not work in batch mode and yields a usage
-error. A separate compression tool can be used instead to reduce the
-size of the batch update files for transport to the destination.
-
 The -n/--dryrun option does not work in batch mode and yields a runtime
 error.