X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/716e73d483d33a1457be8f4b0e72bb39c11ca171..2c713fcdfa04eb7d58c67a4a51d4cbdc37f78536:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 4805c010..d18267a9 100644 --- a/rsync.yo +++ b/rsync.yo @@ -32,7 +32,7 @@ report that accompanies this package. Some of the additional features of rsync are: itemize( - it() support for copying links, devices, owners, groups and permissions + it() support for copying links, devices, owners, groups, and permissions it() exclude and exclude-from options similar to GNU tar it() a CVS exclude mode for ignoring the same files that CVS would ignore it() can use any transparent remote shell, including ssh or rsh @@ -347,8 +347,8 @@ verb( --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 @@ -512,9 +512,9 @@ This option can be quite slow, so only use it if you need it. dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm is not used and the whole file is sent as-is instead. The transfer may be faster if this option is used when the bandwidth between the source and -target machines is higher than the bandwidth to disk (especially when the +destination machines is higher than the bandwidth to disk (especially when the "disk" is actually a networked filesystem). This is the default when both -the source and target are on the local machine. +the source and destination are specified as local paths. dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the default. @@ -686,11 +686,11 @@ See the EXCLUDE PATTERNS section for detailed information on this option. dit(bf(--include-from=FILE)) This specifies a list of include patterns from a file. -If em(FILE) is bf(-) the list will be read from standard input. +If em(FILE) is "-" the list will be read from standard input. dit(bf(--files-from=FILE)) Using this option allows you to specify the exact list of files to transfer (as read from the specified FILE or "-" -for stdin). It also tweaks the default behavior of rsync to make +for standard input). It also tweaks the default behavior of rsync to make transferring just the specified files and directories easier. For instance, the --relative option is enabled by default when this option is used (use --no-relative if you want to turn that off), all @@ -897,13 +897,14 @@ transfer was too fast, it will wait before sending the next data block. The 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(--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=PREFIX)) Apply a previously generated change batch, -using the fileset whose filenames start with PREFIX. 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. +If em(FILE) is "-" the list will be read from standard input. +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 +918,12 @@ try specifying --ipv6 or --ipv4 when starting the daemon). 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 +1104,55 @@ source tree and those changes need to be propagated to the other 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. + +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. + +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. -The fileset consists of 4 files: +Examples: -itemize( -it() bf(.rsync_argvs) command-line arguments -it() bf(.rsync_flist) rsync internal file metadata -it() bf(.rsync_csums) rsync checksums -it() bf(.rsync_delta) data blocks for file update & change +verb( + $ rsync --write-batch=batch -a /source/dir/ /adest/dir/ + $ ssh remote rsync --read-batch=- -a /bdest/dir/