--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)
+ --inplace update the destination files inplace
-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
pointing to a directory, it will be treated as matching a directory
from the sender.
+dit(bf(--inplace)) This causes rsync not to create a new copy of the file
+and then move it into place. Instead rsync will overwrite the existing
+file, meaning that the rsync algorithm can't extract the full amount of
+network reduction it might otherwise.
+
+This option is useful for transfer of large files with block-based change
+or appended data, and also on systems that are disk bound not network bound.
+
+WARNING: The file's data will be in an inconsistent state during the
+transfer (and possibly afterward if the transfer gets interrupted), so you
+should not use this option to update files that are in use. Also note that
+rsync will be unable to update a file inplace that is not writable by the
+receiving user.
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
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.
of zero specifies no limit.
dit(bf(--write-batch=FILE)) Record a file that can later be applied to
-anonther identical destination with --read-batch. See the "BATCH MODE"
+another 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.
-If em(FILE) is "-" the list will be read from standard input.
+If em(FILE) is "-" the batch data 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
manpagesection(BATCH MODE)
bf(Note:) Batch mode should be considered experimental in this version
-of rsync. The interface or behavior may change before it stabilizes.
+of rsync. The interface and behavior have now stabilized, though, so
+feel free to try this out.
Batch mode can be used to apply the same set of updates to many
identical systems. Suppose one has a tree which is replicated on a
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
+".sh" to the batch filename. The .sh 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
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:
+Examples:
verb(
- $ 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 ./batch.rsync_argvs /bdest/dir/
+ $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
+ $ scp foo* remote:
+ $ ssh remote ./foo.sh /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 "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.
+verb(
+ $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
+ $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
+)
+
+In these examples, rsync is used to update /adest/dir/ from /source/dir/
+and the information to repeat this operation is stored in "foo" and
+"foo.sh". The host "remote" is then updated with the batched data going
+into the directory /bdest/dir. The differences between the two examples
+reveals some of the flexibility you have in how you deal with batches:
+
+itemize(
+
+ it() The first example shows that the initial copy doesn't have to be
+ local -- you can push or pull data to/from a remote host using either the
+ remote-shell syntax or rsync daemon syntax, as desired.
+
+ it() The first example uses the created "foo.sh" file to get the right
+ rsync options when running the read-batch command on the remote host.
+
+ it() The second example reads the batch data via standard input so that
+ the batch file doesn't need to be copied to the remote machine first.
+ This example avoids the foo.sh script because it needed to use a modified
+ --read-batch option, but you could edit the script file if you wished to
+ make use of it (just be sure that no other option is trying to use
+ standard input, such as the "--exclude-from=-" option).
+
+)
Caveats:
-The read-batch option expects the destination tree it is meant to update
+The read-batch option expects the destination tree that it is updating
to be identical to the destination tree that was used to create the
batch update fileset. When a difference between the destination trees
-is encountered the update will fail at that point, leaving the
-destination tree in a partially updated state. In that case, rsync can
+is encountered the update might be discarded with no error (if the file
+appears to be up-to-date already) or the file-update may be attempted
+and then, if the file fails to verify, the update discarded with an
+error. This means that it should be safe to re-run a read-batch operation
+if the command got updated. If you wish to force the batched-update to
+always be attempted regardless of the file's size and date, use the -I
+option. If an error occurs, the destination tree will probably be 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 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
+The --dry-run (-n) 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
+When reading a batch file, rsync will force the value of certain options
+to match the data in the batch file if you didn't set them to the same
+as the batch-writing command. Other options can (and should) be changed.
+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.
+without --delete-excluded.
+
+The code that creates the BATCH.sh file transforms any include/exclude
+options into a single list that is appended as a "here" document to the
+shell script file. An advanced user can use this to modify the exclude
+list if a change in what gets deleted by --delete is desired. A normal
+user can ignore this detail and just use the shell script as an easy way
+to run the appropriate --read-batch command for the batched data.
See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
reports.
I've probably missed some people, my apologies if I have.
Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
-Martin Pool, Wayne Davison.
+Martin Pool, Wayne Davison, J.W. Schultz.
manpageauthor()
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff