X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/e40a46de71e09d753160cc503b005d11208b22ab..dbbab0c4d2d185e0493c0185e9332e2247ff4df2:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 0e7b3009..0f07c46b 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 @@ -289,6 +289,7 @@ verb( --backup-dir make backups into this directory --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) + -K, --keep-dirlinks treat symlinked dir on receiver as dir -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of all symlinks --copy-unsafe-links copy the referent of "unsafe" symlinks @@ -346,8 +347,9 @@ 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 -h, --help show this help screen @@ -478,6 +480,10 @@ symlink where the destination has a file, the transfer would occur regardless of the timestamps. This might change in the future (feel free to comment on this on the mailing list if you have an opinion). +dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is +pointing to a directory, it will be treated as matching a directory +from the sender. + dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. @@ -891,13 +897,13 @@ 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. 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 @@ -908,6 +914,16 @@ versions of Linux to work around an IPv6 bug in the kernel (if you see an "address already in use" error when nothing else is using the port, 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(). 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. + enddit() manpagesection(EXCLUDE PATTERNS) @@ -1087,53 +1103,45 @@ 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. - -The fileset consists of 4 files: - -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 -) - -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 +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. +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: @@ -1145,16 +1153,23 @@ destination 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 destination tree. -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 rsync version used on all destinations must be at least as new as the +one used to generate the batch file. The -n/--dryrun option does not work in batch mode and yields a runtime error. +You should use an equivalent set of options when reading a batch file that +you used when generating it with a few exceptions. For instance +--write-batch changes to --read-batch, --files-from is dropped, and the +--include/--exclude options are not needed unless --delete is specified +without --delete-excluded. Other options that affect how the update +happens should generally remain the same as it is possible to confuse rsync +into expecting a different data stream than the one that is contained in +the batch file. For example, it would not work to change the setting of +the -H or -c option, but it would work to add or remove the --delete +option. + See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical reports.