mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(15 Nov 2008)()()
+manpage(rsync)(1)(12 Apr 2009)()()
manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
manpagesynopsis()
been changed and are in need of a transfer. Without this option, rsync
uses a "quick check" that (by default) checks if each file's size and time
of last modification match between the sender and receiver. This option
-changes this to compare a 128-bit MD4 checksum for each file that has a
+changes this to compare a 128-bit checksum for each file that has a
matching size. Generating the checksums means that both sides will expend
a lot of disk I/O reading all the data in the files in the transfer (and
this is prior to any reading that will be done to transfer changed files),
automatic after-the-transfer verification has nothing to do with this
option's before-the-transfer "Does this file need to be updated?" check.
+For protocol 30 and beyond (first supported in 3.0.0), the checksum used is
+MD5. For older protocols, the checksum used is MD4.
+
dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
way of saying you want recursion and want to preserve almost
everything (with -H being a notable omission).
where the destination has a file, the transfer would occur regardless of
the timestamps.
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
dit(bf(--inplace)) This option changes how rsync transfers a file when the
file's data needs to be updated: instead of the default method of creating
a new copy of the file and moving it into place when it is complete, rsync
combined with the bf(--ignore-existing) option, no files will be updated
(which can be useful if all you want to do is delete extraneous files).
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
dit(bf(--ignore-existing)) This tells rsync to skip updating files that
already exist on the destination (this does em(not) ignore existing
directories, or nothing would get done). See also bf(--existing).
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
This option can be useful for those doing backups using the bf(--link-dest)
option when they need to continue a backup run that got interrupted. Since
a bf(--link-dest) run is copied into a new directory hierarchy (when it is
suffixed with a string to indicate a size multiplier, and
may be a fractional value (e.g. "bf(--max-size=1.5m)").
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024),
"M" (or "MiB") is a mebibyte (1024*1024), and "G" (or "GiB") is a
gibibyte (1024*1024*1024).
dit(bf(--min-size=SIZE)) This tells rsync to avoid transferring any
file that is smaller than the specified SIZE, which can help in not
transferring small, junk files.
-See the bf(--max-size) option for a description of SIZE.
+See the bf(--max-size) option for a description of SIZE and other information.
dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
rsync's delta-transfer algorithm to a fixed value. It is normally selected based on
For a list of the possible escape characters, see the "log format" setting
in the rsyncd.conf manpage.
+The default FORMAT used if bf(--log-file) is specified and this option is not
+is '%i %n%L'.
+
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
on the file transfer, allowing you to tell how effective rsync's delta-transfer
algorithm is for your data.
recursively scanning a hierarchy of files using include/exclude/filter
rules.
+Note that the use of transfer rules, such as the bf(--min-size) option, does
+not affect what goes into the file list, and thus does not leave directories
+empty, even if none of the files in a directory match the transfer rule.
+
Because the file-list is actually being pruned, this option also affects
what directories get deleted when a delete is active. However, keep in
mind that excluded files and directories can prevent existing items from
-being deleted (because an exclude hides source files and protects
-destination files).
+being deleted due to an exclude both hiding source files and protecting
+destination files. See the perishable filter-rule option for how to avoid
+this.
You can prevent the pruning of certain empty directories from the file-list
by using a global "protect" filter. For instance, this option would ensure
will have no effect. The bf(--version) output will tell you if this
is the case.
-dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
+dit(bf(--checksum-seed=NUM)) Set the 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
+checksum calculation. By default the checksum seed is generated
by the server and defaults to the current code(time()). This option
is used to set a specific checksum seed, which is useful for
applications that want repeatable block and file checksums, or
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
-".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 (or 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.
+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 your convenience, a script file is also created when the write-batch
+option is used: it will be named the same as the batch file with ".sh"
+appended. This script file contains a command-line suitable for updating a
+destination tree using the associated batch file. It can be executed using
+a Bourne (or Bourne-like) shell, optionally passing in an alternate
+destination tree pathname which is then used instead of the original
+destination path. This is useful when the destination tree path on the
+current host differs from the one used to create the batch file.
+
Examples:
quote(
manpagesection(VERSION)
-This man page is current for version 3.0.5pre2 of rsync.
+This man page is current for version 3.0.6pre1 of rsync.
manpagesection(INTERNAL OPTIONS)