--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:
command-line. Filter rules have the following syntax:
quote(
-tt(x [RULE])nl()
-tt(xMODIFIERS [RULE])nl()
+tt(RULE [PATTERN_OR_FILENAME])nl()
+tt(RULE,MODIFIERS [PATTERN_OR_FILENAME])nl()
)
-The 'x' is a single-letter that specifies the kind of rule to create. It
-can have trailing modifiers, and is separated from the RULE by either a
-single space or an underscore (_). Here are the available rule prefixes:
+You have your choice of using either short or long RULE names, as described
+below. If you use a short-named rule, the ',' separating the RULE from the
+MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
+must come after either a single space or an underscore (_).
+Here are the available rule prefixes:
quote(
-bf(-) specifies an exclude pattern. nl()
-bf(+) specifies an include pattern. nl()
-bf(.) specifies a merge-file to read for more rules. nl()
-bf(:) specifies a per-directory merge-file. nl()
-bf(!) clears the current include/exclude list (takes no RULE) nl()
+bf(exclude, -) specifies an exclude pattern. nl()
+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()
)
+When rules are being read from a file, empty lines are ignored, as are
+comment lines that start with a "#".
+
Note that the bf(--include)/bf(--exclude) command-line options do not allow the
full range of rule parsing as described above -- they only allow the
-specification of include/exclude patterns and the "!" token (not to
-mention the comment lines when reading rules from a file). If a pattern
+specification of include/exclude patterns plus a "!" token to clear the
+list (and the normal comment parsing when rules are read from a file).
+If a pattern
does not begin with "- " (dash, space) or "+ " (plus, space), then the
rule will be interpreted as if "+ " (for an include option) or "- " (for
an exclude option) were prefixed to the string. A bf(--filter) option, on
-the other hand, must always contain one of the prefixes above.
+the other hand, must always contain either a short or long rule name at the
+start of the rule.
Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one
rule/pattern each. To add multiple ones, you can repeat the options on
the command-line, use the merge-file syntax of the bf(--filter) option, or
the bf(--include-from)/bf(--exclude-from) options.
-When rules are being read from a file, empty lines are ignored, as are
-comment lines that start with a "#".
-
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). These
-rules specify a pattern that is matched against the names of the files
-that are going to be transferred. These patterns can take several forms:
+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:
itemize(
it() if the pattern starts with a / then it is anchored to a
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:
manpagesection(MERGE-FILE FILTER RULES)
You can merge whole files into your filter rules by specifying either a
-"." or a ":" filter rule (as introduced in the FILTER RULES section
-above).
+merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES
+section above).
There are two kinds of merged files -- single-instance ('.') and
per-directory (':'). A single-instance merge file is read one time, and
Some examples:
quote(
+tt(merge /etc/rsync/default.rules)nl()
tt(. /etc/rsync/default.rules)nl()
-tt(: .per-dir-filter)nl()
+tt(dir-merge .per-dir-filter)nl()
+tt(dir-merge,n- .non-inherited-per-dir-excludes)nl()
tt(:n- .non-inherited-per-dir-excludes)nl()
)
-The following modifiers are accepted after a "." or ":":
+The following modifiers are accepted after a merge or dir-merge rule:
itemize(
it() A bf(-) specifies that the file should consist of only exclude
- patterns, with no other rule-parsing except for the list-clearing
- token ("!").
+ patterns, with no other rule-parsing except for in-file comments.
it() A bf(+) specifies that the file should consist of only include
- patterns, with no other rule-parsing except for the list-clearing
- token ("!").
- it() A bf(C) is a shorthand for the modifiers bf(nw-), which makes the
- parsing compatible with the way CVS parses their exclude files. If no
- filename is specified, ".cvsignore" is assumed.
- it() A bf(e) will exclude the merge-file from the transfer; e.g.
- ":e_.rules" is like ":_.rules" and "-_.rules".
+ patterns, with no other rule-parsing except for in-file comments.
+ it() A bf(C) is a way to specify that the file should be read in a
+ CVS-compatible manner. This turns on 'n', 'w', and '-', but also
+ 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".
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
space that separates the prefix from the rule is treated specially, so
- "- foo + bar" is parsed as two rules (assuming that bf(-) or bf(+) was not
- specified to turn off the parsing of prefixes).
+ "- 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
+ 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
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 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
where the merge-file was found unless the 'n' modifier was used. Each
subdirectory's rules are prefixed to the inherited per-directory rules
from its parents, which gives the newest rules a higher priority than the
-inherited rules. The entire set of per-dir rules is grouped together in
+inherited rules. The entire set of dir-merge rules are grouped together in
the spot where the merge-file was specified, so it is possible to override
-per-dir rules via a rule that got specified earlier in the list of global
+dir-merge rules via a rule that got specified earlier in the list of global
rules. When the list-clearing rule ("!") is read from a per-directory
file, it only clears the inherited rules for the current merge file.
-Another way to prevent a single per-dir rule from being inherited is to
+Another way to prevent a single rule from a dir-merge file from being inherited is to
anchor it with a leading slash. Anchored rules in a per-directory
merge-file are relative to the merge-file's directory, so a pattern "/foo"
-would only match the file "foo" in the directory where the per-dir filter
+would only match the file "foo" in the directory where the dir-merge filter
file was found.
Here's an example filter file which you'd specify via bf(--filter=". file":)
quote(
-tt(. /home/user/.global-filter)nl()
+tt(merge /home/user/.global-filter)nl()
tt(- *.gz)nl()
-tt(: .rules)nl()
+tt(dir-merge .rules)nl()
tt(+ *.[ch])nl()
tt(- *.o)nl()
)
a part of the transfer.
If you want to include the contents of a ".cvsignore" in your patterns,
-you should use the rule ":C" -- this is a short-hand for the rule
-":nw-_.cvsignore", and ensures that the .cvsignore file's contents are
-interpreted according to the same parsing rules that CVS uses. You can
+you should use the rule ":C", which creates a dir-merge of the .cvsignore
+file, but parsed in a CVS-compatible manner. You can
use this to affect where the bf(--cvs-exclude) (bf(-C)) option's inclusion of the
-per-directory .cvsignore file gets placed into your rules by putting a
+per-directory .cvsignore file gets placed into your rules by putting the
":C" wherever you like in your filter rules. Without this, rsync would
-add the per-dir rule for the .cvsignore file at the end of all your other
+add the dir-merge rule for the .cvsignore file at the end of all your other
rules (giving it a lower priority than your command-line rules). For
example:
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
-bf(--write-batch) changes to bf(--read-batch), bf(--files-from) is dropped, and the
-bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless one of the
-bf(--delete) options is specified without bf(--delete-excluded).
+For instance bf(--write-batch) changes to bf(--read-batch),
+bf(--files-from) is dropped, and the
+bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless
+one of the bf(--delete) options is specified.
The code that creates the BATCH.sh file transforms any filter/include/exclude
options into a single list that is appended as a "here" document to the
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff