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:
o if the pattern starts with a / then it is anchored to a
particular spot in the hierarchy of files, otherwise it is
matched against the end of the pathname. This is similar
to a leading ^ in regular expressions. Thus /foo would
match a name of "foo" at either the "root of the transfer"
(for a global rule) or in the merge-file's directory (for
a per-directory rule). An unqualified foo would match a
name of "foo" anywhere in the tree because the algorithm
is applied recursively from the top down; it behaves as if
each path component gets a turn at being the end of the
filename. Even the unanchored "sub/foo" would match at
any point in the hierarchy where a "foo" was found within
a directory named "sub". See the section on ANCHORING
INCLUDE/EXCLUDE PATTERNS for a full discussion of how to
specify a pattern that matches at the root of the
transfer.
o if the pattern ends with a / then it will only match a
directory, not a regular file, symlink, or device.
o rsync chooses between doing a simple string match and
wildcard matching by checking if the pattern contains one
of these three wildcard characters: '*', '?', and '[' .
o a '*' matches any path component, but it stops at slashes.
o use '**' to match anything, including slashes.
o a '?' matches any character except a slash (/).
o a '[' introduces a character class, such as [a-z] or
[[:alpha:]].
o in a wildcard pattern, a backslash can be used to escape a
wildcard character, but it is matched literally when no
wildcards are present. This means that there is an extra
level of backslash removal when a pattern contains
wildcard characters compared to a pattern that has none.
e.g. if you add a wildcard to "foo\bar" (which matches the
backslash) you would need to use "foo\\bar*" to avoid the
"\b" becoming just "b".
o if the pattern contains a / (not counting a trailing /) or
a "**", then it is matched against the full pathname,
including any leading directories. If the pattern doesn't
contain a / or a "**", then it is matched only against the
final component of the filename. (Remember that the
algorithm is applied recursively so "full filename" can
actually be any portion of a path from the starting
directory on down.)
o a trailing "dir_name/***" will match both the directory
(as if "dir_name/" had been specified) and everything in
the directory (as if "dir_name/**" had been specified).
This behavior was added in version 2.6.7.
Note that, when using the --recursive (-r) option (which is
implied by -a), every subdir component of every path is visited
left to right, with each directory having a chance for exclusion
before its content. In this way include/exclude patterns are
applied recursively to the pathname of each node in the
filesystem's tree (those inside the transfer). The exclude
patterns short-circuit the directory traversal stage as rsync
finds the files to send.
For instance, to include "/foo/bar/baz", the directories "/foo"
and "/foo/bar" must not be excluded. Excluding one of those
parent directories prevents the examination of its content,
cutting off rsync's recursion into those paths and rendering the
include for "/foo/bar/baz" ineffectual (since rsync can't match
something it never sees in the cut-off section of the directory
hierarchy).
The concept path exclusion is particularly important when using a
trailing '*' rule. For instance, this won't work:
+ /some/path/this-file-will-not-be-found
+ /file-is-included
- *
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), and
perhaps use the --prune-empty-dirs option. 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:
+ /some/
+ /some/path/
+ /some/path/this-file-is-found
+ /file-also-included
- *
Here are some examples of exclude/include matching:
o "- *.o" would exclude all names matching *.o
o "- /foo" would exclude a file (or directory) named foo in
the transfer-root directory
o "- foo/" would exclude any directory named foo
o "- /foo/*/bar" would exclude any file named bar which is
at two levels below a directory named foo in the transfer-
root directory
o "- /foo/**/bar" would exclude any file named bar two or
more levels below a directory named foo in the transfer-
root directory
o The combination of "+ */", "+ *.c", and "- *" would
include all directories and C source files but nothing
else (see also the --prune-empty-dirs option)
o The combination of "+ foo/", "+ foo/bar.c", and "- *"
would include only the foo directory and foo/bar.c (the
foo directory must be explicitly included or it would be
excluded by the "*")
The following modifiers are accepted after a "+" or "-":
o A / 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.
o A ! specifies that the include/exclude should take effect
if the pattern fails to match. For instance, "-! */"
would exclude all non-directories.
o A 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.
o An 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 --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.
o An 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 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.
o A p indicates that a rule is perishable, meaning that it
is ignored in directories that are being deleted. For
instance, the -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.
o An x indicates that a rule affects xattr names in xattr
copy/delete operations (and is thus ignored when matching
file/dir names). If no xattr-matching rules are
specified, a default xattr filtering rule is used (see the
--xattrs option).
