--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 file inplace
+ --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
-W, --whole-file copy whole files, no incremental checks
--no-whole-file turn off --whole-file
-x, --one-file-system don't cross filesystem boundaries
- -B, --block-size=SIZE checksum blocking size (default 700)
+ -B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell
--rsync-path=PATH specify path to rsync on the remote machine
--existing only update files that already exist
--ignore-errors delete even if there are I/O errors
--max-delete=NUM don't delete more than NUM files
--partial keep partially transferred files
+ --partial-dir=DIR put a partially transferred file into DIR
--force force deletion of dirs even if not empty
--numeric-ids don't map uid/gid values by user/group name
--timeout=TIME set I/O timeout in seconds
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 ammount of
+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 changes
-and also on systems that are disk bound not network bound.
+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: If the transfer is interrupted, you will have an inconsistent file
-and the transfer should be run again.
+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(-L, --copy-links)) When symlinks are encountered, the file that
-they point to (the referent) is copied, rather than the symlink.
+they point to (the referent) is copied, rather than the symlink. In older
+versions of rsync, this option also had the side-effect of telling the
+receiving side to follow symlinks, such as symlinks to directories. In a
+modern rsync such as this one, you'll need to specify --keep-dirlinks (-K)
+to get this extra behavior. The only exception is when sending files to
+an rsync that is too old to understand -K -- in that case, the -L option
+will still have the side-effect of -K on that older receiving rsync.
dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
symbolic links that point outside the copied tree. Absolute symlinks
with the files and update them on the remote system. Note that if this
option is not used, the optimization that excludes files that have not been
modified cannot be effective; in other words, a missing -t or -a will
-cause the next transfer to behave as if it used -I, and all files will have
-their checksums compared and show up in log messages even if they haven't
-changed.
+cause the next transfer to behave as if it used -I, causing all files to be
+updated (though the rsync algorithm will make the update fairly efficient
+if the files haven't actually changed, you're much better off using -t).
dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
instead it will just report the actions it would have taken.
is only relevant without --delete because deletions are now done depth-first.
Requires the --recursive option (which is implied by -a) to have any effect.
-dit(bf(-B, --block-size=BLOCKSIZE)) This controls the block size used in
-the rsync algorithm. See the technical report for details.
+dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
+the rsync algorithm to a fixed value. It is normally selected based on
+the size of each file being updated. See the technical report for details.
dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
remote shell program to use for communication between the local and
--partial option tells rsync to keep the partial file which should
make a subsequent transfer of the rest of the file much faster.
+dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to
+put a partially transferred file into DIR instead of writing out the
+file to the destination dir. Rsync will also use a file found in this
+dir as data to speed up the transfer (i.e. when you redo the send after
+rsync creates a partial file) and delete such a file after it has served
+its purpose.
+
+Rsync will create the dir if it is missing (just the last dir -- not the
+whole path). This makes it easy to use a relative path (such as
+"--partial-dir=.rsync-partial") to have rsync create the partial-directory
+in the destination file's directory (rsync will also try to remove the DIR
+if a partial file was found to exist at the start of the transfer and the
+DIR was specified as a relative path).
+
+If you are deleting files on the destination and your partial-dir is
+inside the destination hierarchy, make sure you specify an exclude to
+prevent the partial file from being deleted (it could get deleted at the
+end of the transfer when using --delete-after, or at the beginning of the
+transfer when using --delete). E.g. "--exclude=.rsync-partial/".
+
+IMPORTANT: the --partial-dir should not be writable by other users to
+avoid a security risk. E.g. AVOID "/tmp".
+
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
something to watch.
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
Examples:
verb(
- $ rsync --write-batch=batch -a /source/dir/ /adest/dir/
- $ ssh remote rsync --read-batch=- -a /bdest/dir/ <batch
+ $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
+ $ scp foo* remote:
+ $ ssh remote ./foo.sh /bdest/dir/
)
verb(
- $ rsync --write-batch=batch -a host:/source/dir/ /adest/dir/
- $ scp batch remote:
- $ ssh remote rsync --read-batch=batch -a /bdest/dir/
+ $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
+ $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
)
-verb(
- $ rsync --write-batch=batch -a /source/dir/ host:/adest/dir/
- $ scp batch* remote:
- $ ssh remote ./batch.rsync_argvs /bdest/dir/
-)
+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(
-In these examples, 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". The host "remote" is then updated with the batched
-update going into the directory /bdest/dir. The differences between the
-three examples is in how the batch gets to the remote machine (via remote
-stdin or by being copied first), whether the initial transfer was local or
-remote, and in how the batch-reading rsync command is invoked.
+ 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