+ *?[ then expression matching is applied using the shell filename
+ matching rules. Otherwise a simple string match is used.
+ it() the double asterisk pattern "**" will match slashes while a
+ single asterisk pattern "*" will stop at slashes.
+ it() 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.)
+)
+
+Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by
+bf(-a)), every subcomponent of every path is visited from the top down, so
+include/exclude patterns get applied recursively to each subcomponent's
+full name (e.g. to include "/foo/bar/baz" the subcomponents "/foo" and
+"/foo/bar" must not be excluded).
+The exclude patterns actually short-circuit the directory traversal stage
+when rsync finds the files to send. If a pattern excludes a particular
+parent directory, it can render a deeper include pattern ineffectual
+because rsync did not descend through that excluded section of the
+hierarchy. This is particularly important when using a trailing '*' rule.
+For instance, this won't work:
+
+quote(
+tt(+ /some/path/this-file-will-not-be-found)nl()
+tt(+ /file-is-included)nl()
+tt(- *)nl()
+)
+
+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
+the parent dirs that need to be visited. For instance, this set of rules
+works fine:
+
+quote(
+tt(+ /some/)nl()
+tt(+ /some/path/)nl()
+tt(+ /some/path/this-file-is-found)nl()
+tt(+ /file-also-included)nl()
+tt(- *)nl()
+)
+
+Here are some examples of exclude/include matching:
+
+itemize(
+ it() "- *.o" would exclude all filenames matching *.o
+ it() "- /foo" would exclude a file called foo in the transfer-root directory
+ it() "- foo/" would exclude any directory called foo
+ it() "- /foo/*/bar" would exclude any file called bar two
+ levels below a directory called foo in the transfer-root directory
+ it() "- /foo/**/bar" would exclude any file called bar two
+ or more levels below a directory called foo in the transfer-root directory
+ it() The combination of "+ */", "+ *.c", and "- *" would include all
+ directories and C source files but nothing else.
+ it() 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 "*")
+)
+
+manpagesection(MERGE-FILE FILTER RULES)
+
+You can merge whole files into your filter rules by specifying either a
+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
+its rules are incorporated into the filter list in the place of the "."
+rule. For per-directory merge files, rsync will scan every directory that
+it traverses for the named file, merging its contents when the file exists
+into the current list of inherited rules. These per-directory rule files
+must be created on the sending side because it is the sending side that is
+being scanned for the available files to transfer. These rule files may
+also need to be transferred to the receiving side if you want them to
+affect what files don't get deleted (see PER-DIRECTORY RULES AND DELETE
+below).
+
+Some examples:
+
+quote(
+tt(merge /etc/rsync/default.rules)nl()
+tt(. /etc/rsync/default.rules)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 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 in-file comments.
+ it() A bf(+) specifies that the file should consist of only include
+ 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 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 sending 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
+ 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 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.
+)
+
+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 dir-merge rules are grouped together in
+the spot where the merge-file was specified, so it is possible to override
+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 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 dir-merge filter
+file was found.
+
+Here's an example filter file which you'd specify via bf(--filter=". file":)
+
+quote(
+tt(merge /home/user/.global-filter)nl()
+tt(- *.gz)nl()
+tt(dir-merge .rules)nl()
+tt(+ *.[ch])nl()
+tt(- *.o)nl()
+)
+
+This will merge the contents of the /home/user/.global-filter file at the
+start of the list and also turns the ".rules" filename into a per-directory
+filter file. All rules read-in prior to the start of the directory scan
+follow the global anchoring rules (i.e. a leading slash matches at the root
+of the transfer).