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
option, and copying devices via the bf(--devices) option. This is useful
for systems that allow such activities without being the super-user, and
also for ensuring that you will get errors if the receiving side isn't
-being running as the super-user. To turn off super-user activities, the
+being run as the super-user. To turn off super-user activities, the
super-user can use bf(--no-super).
dit(bf(--fake-super)) When this option is enabled, rsync simulates
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. This option is equivalent to bf(--info=stats2)
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
explicitly included or it would be excluded by the "*")
)
+The following modifiers are accepted after a "+" or "-":
+
+itemization(
+ it() A bf(/) specifies that the include/exclude rule should be matched
+ against the absolute pathname of the current item. For example,
+ "-/ /etc/passwd" would exclude the passwd file any time the transfer
+ was sending files from the "/etc" directory, and "-/ subdir/foo"
+ would always exclude "foo" when it is in a dir named "subdir", even
+ if "foo" is at the root of the current transfer.
+ it() A bf(!) specifies that the include/exclude should take effect if
+ the pattern fails to match. For instance, "-! */" would exclude all
+ non-directories.
+ it() A bf(C) is used to indicate that all the global CVS-exclude rules
+ should be inserted as excludes in place of the "-C". No arg should
+ follow.
+ it() An bf(s) is used to indicate that the rule applies to the sending
+ side. When a rule affects the sending side, it prevents files from
+ being transferred. The default is for a rule to affect both sides
+ unless bf(--delete-excluded) was specified, in which case default rules
+ become sender-side only. See also the hide (H) and show (S) rules,
+ which are an alternate way to specify sending-side includes/excludes.
+ it() An bf(r) is used to indicate that the rule applies to the receiving
+ side. When a rule affects the receiving side, it prevents files from
+ being deleted. See the bf(s) modifier for more info. See also the
+ protect (P) and risk (R) rules, which are an alternate way to
+ specify receiver-side includes/excludes.
+ it() A bf(p) indicates that a rule is perishable, meaning that it is
+ ignored in directories that are being deleted. For instance, the bf(-C)
+ option's default rules that exclude things like "CVS" and "*.o" are
+ marked as perishable, and will not prevent a directory that was removed
+ on the source from being deleted on the destination.
+)
+
manpagesection(MERGE-FILE FILTER RULES)
You can merge whole files into your filter rules by specifying either a
"- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't
also disabled).
it() You may also specify any of the modifiers for the "+" or "-" rules
- (below) in order to have the rules that are read in from the file
+ (above) in order to have the rules that are read in from the file
default to having that modifier set. For instance, "merge,-/ .excl" would
treat the contents of .excl as absolute-path excludes,
while "dir-merge,s .filt" and ":sC" would each make all their
per-directory rules apply only on the sending side.
)
-The following modifiers are accepted after a "+" or "-":
-
-itemization(
- it() A bf(/) specifies that the include/exclude rule should be matched
- against the absolute pathname of the current item. For example,
- "-/ /etc/passwd" would exclude the passwd file any time the transfer
- was sending files from the "/etc" directory, and "-/ subdir/foo"
- would always exclude "foo" when it is in a dir named "subdir", even
- if "foo" is at the root of the current transfer.
- it() A bf(!) specifies that the include/exclude should take effect if
- the pattern fails to match. For instance, "-! */" would exclude all
- non-directories.
- it() A bf(C) is used to indicate that all the global CVS-exclude rules
- should be inserted as excludes in place of the "-C". No arg should
- follow.
- it() An bf(s) is used to indicate that the rule applies to the sending
- side. When a rule affects the sending side, it prevents files from
- being transferred. The default is for a rule to affect both sides
- unless bf(--delete-excluded) was specified, in which case default rules
- become sender-side only. See also the hide (H) and show (S) rules,
- which are an alternate way to specify sending-side includes/excludes.
- it() An bf(r) is used to indicate that the rule applies to the receiving
- side. When a rule affects the receiving side, it prevents files from
- being deleted. See the bf(s) modifier for more info. See also the
- protect (P) and risk (R) rules, which are an alternate way to
- specify receiver-side includes/excludes.
- it() A bf(p) indicates that a rule is perishable, meaning that it is
- ignored in directories that are being deleted. For instance, the bf(-C)
- option's default rules that exclude things like "CVS" and "*.o" are
- marked as perishable, and will not prevent a directory that was removed
- on the source from being deleted on the destination.
-)
-
Per-directory rules are inherited in all subdirectories of the directory
where the merge-file was found unless the 'n' modifier was used. Each
subdirectory's rules are prefixed to the inherited per-directory rules
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff