--compare-dest=DIR also compare received files relative to DIR
--copy-dest=DIR ... and include copies of unchanged files
--link-dest=DIR hardlink to files in DIR when unchanged
- -z, --compress compress file data
+ -z, --compress compress file data during the transfer
-C, --cvs-exclude auto-ignore files in the same way CVS does
-f, --filter=RULE add a file-filtering RULE
- -F same as --filter=': /.rsync-filter'
+ -F same as --filter='dir-merge /.rsync-filter'
repeated: --filter='- .rsync-filter'
--exclude=PATTERN exclude files matching PATTERN
--exclude-from=FILE read exclude patterns from FILE
after using another mirroring system which may not preserve timestamps
exactly.
-dit(bf(--modify-window)) When comparing two timestamps rsync treats
-the timestamps as being equal if they are within the value of
-modify_window. This is normally zero, but you may find it useful to
-set this to a larger value in some situations. In particular, when
-transferring to Windows FAT filesystems which cannot represent times
-with a 1 second resolution bf(--modify-window=1) is useful.
+dit(bf(--modify-window)) When comparing two timestamps, rsync treats the
+timestamps as being equal if they differ by no more than the modify-window
+value. This is normally 0 (for an exact match), but you may find it useful
+to set this to a larger value in some situations. In particular, when
+transferring to or from an MS Windows FAT filesystem (which represents
+times with a 2-second resolution), bf(--modify-window=1) is useful
+(allowing times to differ by up to 1 second).
dit(bf(-c, --checksum)) This forces the sender to checksum all files using
a 128-bit MD4 checksum before transfer. The checksum is then
for the directory's contents (e.g. "dir/*") since the wildcard is expanded
by the shell and rsync thus gets a request to transfer individual files, not
the files' parent directory. Files that are excluded from transfer are
-excluded from being deleted unless you use bf(--delete-excluded).
+also excluded from being deleted unless you use the bf(--delete-excluded)
+option or mark the rules as only matching on the sending side (see the
+include/exclude modifiers in the FILTER RULES section).
This option has no effect unless directory recursion is enabled.
dit(bf(--delete-excluded)) In addition to deleting the files on the
receiving side that are not on the sending side, this tells rsync to also
delete any files on the receiving side that are excluded (see bf(--exclude)).
+See the FILTER RULES section for a way to make individual exclusions behave
+this way on the receiver, and for a way to protect files from
+bf(--delete-excluded).
See bf(--delete) (which is implied) for more details on file-deletion.
dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
(or implied by bf(-a)). You can work-around this bug by avoiding the bf(-o) option
when sending to an old rsync.
-dit(bf(-z, --compress)) With this option, rsync compresses any data from
-the files that it sends to the destination machine. This
-option is useful on slow connections. The compression method used is the
-same method that gzip uses.
+dit(bf(-z, --compress)) With this option, rsync compresses the file data
+as it is sent to the destination machine, which reduces the amount of data
+being transmitted -- something that is useful over a slow connection.
-Note this this option typically achieves better compression ratios
-that can be achieved by using a compressing remote shell, or a
-compressing transport, as it takes advantage of the implicit
-information sent for matching data blocks.
+Note this this option typically achieves better compression ratios that can
+be achieved by using a compressing remote shell or a compressing transport
+because it takes advantage of the implicit information in the matching data
+blocks that are not explicitly sent over the connection.
dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
and user IDs rather than using user and group names and mapping them
bf(--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 bf(--partial) mode, but tells rsync to
-put a partially transferred file into em(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. Note that if bf(--whole-file) is specified (or implied) that an
-existing partial-dir file will not be used to speedup the transfer (since
+dit(bf(--partial-dir=DIR)) A better way to keep partial files than the
+bf(--partial) option is to specify a em(DIR) that will be used to hold the
+partial data (instead of writing it out to the destination file).
+On the next transfer, rsync will use a file found in this
+dir as data to speed up the resumption of the transfer and then deletes it
+after it has served its purpose.
+Note that if bf(--whole-file) is specified (or implied), any partial-dir
+file that is found for a file that is being updated will simply be removed
+(since
rsync is sending files without using the incremental rsync algorithm).
-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
-"bf(--partial-dir=.rsync-partial)") to have rsync create the partial-directory
-in the destination file's directory (rsync will also try to remove the em(DIR)
-if a partial file was found to exist at the start of the transfer and the
-DIR was specified as a relative path).
+Rsync will create the em(DIR) if it is missing (just the last dir -- not
+the whole path). This makes it easy to use a relative path (such as
+"bf(--partial-dir=.rsync-partial)") to have rsync create the
+partial-directory in the destination file's directory when needed, and then
+remove it again when the partial file is deleted.
-If the partial-dir value is not an absolute path, rsync will also add an
+If the partial-dir value is not an absolute path, rsync will also add a directory
bf(--exclude) of this value at the end of all your existing excludes. This
will prevent partial-dir files from being transferred and also prevent the
untimely deletion of partial-dir items on the receiving side. An example:
supplying your own filter rules, you may need to manually insert a
rule for this directory exclusion somewhere higher up in the list so that
it has a high enough priority to be effective (e.g., if your rules specify
-a trailing bf(--exclude='*') rule, the auto-added rule will be ineffective).
+a trailing bf(--exclude='*') rule, the auto-added rule would never be
+reached).
IMPORTANT: the bf(--partial-dir) should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when
bf(--delay-updates) was specified (see below).
+For the purposes of the server-config's "refuse options" setting,
+bf(--partial-dir) does em(not) imply bf(--partial). This is so that a
+refusal of the bf(--partial) option can be used to disallow the overwriting
+of destination files with a partial transfer, while still allowing the
+safer idiom provided by bf(--partial-dir).
+
dit(bf(--delay-updates)) This option puts the temporary file from each
-updated file into the file's partial-dir (see above) until the end of the
+updated file into a holding directory until the end of the
transfer, at which time all the files are renamed into place in rapid
succession. This attempts to make the updating of the files a little more
-atomic. If you don't specify the bf(--partial-dir) option, this option will
-cause it to default to ".~tmp~" (RSYNC_PARTIAL_DIR is not consulted for
-this value). Conflicts with bf(--inplace).
+atomic. By default the files are placed into a directory named ".~tmp~" in
+each file's destination directory, but you can override this by specifying
+the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect
+on this value, nor is bf(--partial-dir) considered to be implied for the
+purposes of the server-config's "refuse options" setting.)
+Conflicts with bf(--inplace).
This option uses more memory on the receiving side (one bit per file
transferred) and also requires enough free disk space on the receiving
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
something to watch.
-Implies bf(--verbose) without incrementing verbosity.
+Implies bf(--verbose) if it wasn't already specified.
When the file is transferring, the data looks like this:
bf(include, +) specifies an include pattern. nl()
bf(merge, .) specifies a merge-file to read for more rules. nl()
bf(dir-merge, :) specifies a per-directory merge-file. nl()
+bf(hide, H) specifies a pattern for hiding files from the transfer. nl()
+bf(show, S) files that match the pattern are not hidden. nl()
+bf(protect, P) specifies a pattern for protecting files from deletion. nl()
+bf(risk, R) files that match the pattern are not protected. nl()
bf(clear, !) clears the current include/exclude list (takes no arg) nl()
)
manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
-You can include and exclude files by specifying patterns using the "+" and
-"-" filter rules (as introduced in the FILTER RULES section above).
+You can include and exclude files by specifying patterns using the "+",
+"-", etc. filter rules (as introduced in the FILTER RULES section above).
The include/exclude rules each specify a pattern that is matched against
the names of the files that are going to be transferred. These patterns
can take several forms:
This fails because the parent directory "some" is excluded by the '*'
rule, so rsync never visits any of the files in the "some" or "some/path"
directories. One solution is to ask for all directories in the hierarchy
-to be included by using a single rule: "+_*/" (put it somewhere before the
-"-_*" rule). Another solution is to add specific include rules for all
+to be included by using a single rule: "+ */" (put it somewhere before the
+"- *" rule). Another solution is to add specific include rules for all
the parent dirs that need to be visited. For instance, this set of rules
works fine:
allows the list-clearing token (!) to be specified. If no filename is
provided, ".cvsignore" is assumed.
it() A bf(e) will exclude the merge-file name from the transfer; e.g.
- "dir-merge,e_.rules" is like "dir-merge,_.rules" and "-_.rules".
+ "dir-merge,e .rules" is like "dir-merge .rules" and "- .rules".
it() An bf(n) specifies that the rules are not inherited by subdirectories.
it() A bf(w) specifies that the rules are word-split on whitespace instead
of the normal line-splitting. This also turns off comments. Note: the
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
- default to having that modifier set. For instance, "merge,-/_.excl" would
- treat the contents of .excl as absolute-path excludes.
+ 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 server side.
)
The following modifiers are accepted after a "+" or "-":
itemize(
it() A "/" specifies that the include/exclude should be treated as an
absolute path, relative to the root of the filesystem. For example,
- "-/_/etc/passwd" would exclude the passwd file any time the transfer
+ "-/ /etc/passwd" would exclude the passwd file any time the transfer
was sending files from the "/etc" directory.
it() A "!" specifies that the include/exclude should take effect if
the pattern fails to match. For instance, "-! */" would exclude all
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 server-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.
)
Per-directory rules are inherited in all subdirectories of the directory
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff