+ it() A "-" specifies that the file should consist of only exclude
+ patterns, with no other rule-parsing except for the list-clearing
+ token ("!").
+
+ it() A "+" specifies that the file should consist of only include
+ patterns, with no other rule-parsing except for the list-clearing
+ token ("!").
+
+ it() A "C" is a shorthand for the modifiers "sn-", which makes the
+ parsing compatible with the way CVS parses their exclude files. If no
+ filename is specified, ".cvsignore" is assumed.
+
+ it() A "e" will exclude the merge-file from the transfer; e.g.
+ ":e_.rules" is like ":_.rules" and "-_.rules".
+
+ it() An "n" specifies that the rules are not inherited by subdirectories.
+
+ it() An "s" specifies that the rules are split on all 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 "-" or "+" was not
+ specified to turn off the parsing of prefixes).
+)
+
+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
+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
+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
+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
+file was found.
+
+Here's an example filter file which you'd specify via --filter=". file":
+
+verb(
+ . /home/user/.global-filter
+ - *.gz
+ : .rules
+ + *.[ch]
+ - *.o
+)
+
+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).
+
+If a per-directory merge-file is specified with a path that is a parent
+directory of the first transfer directory, rsync will scan all the parent
+dirs from that starting point to the transfer directory for the indicated
+per-directory file. For instance, here is a common filter (see -F):
+
+verb(
+ --filter=': /.rsync-filter'
+)
+
+That rule tells rsync to scan for the file .rsync-filter in all
+directories from the root down through the parent directory of the
+transfer prior to the start of the normal directory scan of the file in
+the directories that are sent as a part of the transfer. (Note: for an
+rsync daemon, the root is always the same as the module's "path".)
+
+Some examples of this pre-scanning for per-directory files:
+
+verb(
+ rsync -avF /src/path/ /dest/dir
+ rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir
+ rsync -av --fitler=': .rsync-filter' /src/path/ /dest/dir
+)
+
+The first two commands above will look for ".rsync-filter" in "/" and
+"/src" before the normal scan begins looking for the file in "/src/path"
+and its subdirectories. The last command avoids the parent-dir scan
+and only looks for the ".rsync-filter" files in each directory that is
+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
+":sn-_.cvsignore", and ensures that the .cvsignore file's contents are
+interpreted according to the same parsing rules that CVS uses. You can
+use this to affect where the --cvs-exclude (-C) option's inclusion of the
+per-directory .cvsignore file gets placed into your rules by putting a
+":C" wherever you like in your filter rules. Without this, rsync would
+add the per-dir rule for the .cvignore file at the end of all your other
+rules (giving it a lower priority than your command-line rules). For
+example:
+
+verb(
+ cat <<EOT | rsync -avC --filter='. -' a/ b
+ + foo.o
+ :C
+ - *.old
+ EOT
+
+ rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b
+)
+
+Both of the above rsync commands are identical. Each one will merge all
+the per-directory .cvsignore rules in the middle of the list rather than
+at the end. This allows their dir-specific rules to supersede the rules
+that follow the :C instead of being subservient to all your rules. (The
+global rules taken from the $HOME/.cvsignore file and from $CVSIGNORE are
+not repositioned from their spot at the end of your rules, however -- feel
+free to manually include $HOME/.cvsignore elsewhere in your rules.)
+
+manpagesection(LIST-CLEARING FILTER RULE)
+
+You can clear the current include/exclude list by using the "!" filter
+rule (as introduced in the FILTER RULES section above). The "current"
+list is either the global list of rules (if the rule is encountered while
+parsing the filter options) or a set of per-directory rules (which are
+inherited in their own sub-list, so a subdirectory can use this to clear
+out the parent's rules).
+
+manpagesection(ANCHORING INCLUDE/EXCLUDE PATTERNS)
+
+As mentioned earlier, global include/exclude patterns are anchored at the
+"root of the transfer" (as opposed to per-directory patterns, which are
+anchored at the merge-file's directory). If you think of the transfer as
+a subtree of names that are being sent from sender to receiver, the
+transfer-root is where the tree starts to be duplicated in the destination
+directory. This root governs where patterns that start with a / match.
+
+Because the matching is relative to the transfer-root, changing the
+trailing slash on a source path or changing your use of the --relative
+option affects the path you need to use in your matching (in addition to
+changing how much of the file tree is duplicated on the destination
+host). The following examples demonstrate this.
+
+Let's say that we want to match two source files, one with an absolute
+path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz".
+Here is how the various command choices differ for a 2-source transfer:
+
+verb(
+ Example cmd: rsync -a /home/me /home/you /dest
+ +/- pattern: /me/foo/bar
+ +/- pattern: /you/bar/baz
+ Target file: /dest/me/foo/bar
+ Target file: /dest/you/bar/baz
+
+ Example cmd: rsync -a /home/me/ /home/you/ /dest
+ +/- pattern: /foo/bar (note missing "me")
+ +/- pattern: /bar/baz (note missing "you")
+ Target file: /dest/foo/bar
+ Target file: /dest/bar/baz
+
+ Example cmd: rsync -a --relative /home/me/ /home/you /dest
+ +/- pattern: /home/me/foo/bar (note full path)
+ +/- pattern: /home/you/bar/baz (ditto)
+ Target file: /dest/home/me/foo/bar
+ Target file: /dest/home/you/bar/baz
+
+ Example cmd: cd /home; rsync -a --relative me/foo you/ /dest
+ +/- pattern: /me/foo/bar (starts at specified path)
+ +/- pattern: /you/bar/baz (ditto)
+ Target file: /dest/me/foo/bar
+ Target file: /dest/you/bar/baz
+)
+
+The easiest way to see what name you should filter is to just
+look at the output when using --verbose and put a / in front of the name
+(use the --dry-run option if you're not yet ready to copy any files).
+
+manpagesection(PER-DIRECTORY RULES AND DELETE)
+
+Without a delete option, per-directory rules are only relevant on the
+sending side, so you can feel free to exclude the merge files themselves
+without affecting the transfer. To make this easy, the 'e' modifier adds
+this exclude for you, as seen in these two equivalent commands:
+
+verb(
+ rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest
+ rsync -av --filter=':e .excl' host:src/dir /dest
+)
+
+However, if you want to do a delete on the receiving side AND you want some
+files to be excluded from being deleted, you'll need to be sure that the
+receiving side knows what files to exclude. The easiest way is to include
+the per-directory merge files in the transfer and use --delete-after,
+because this ensures that the receiving side gets all the same exclude
+rules as the sending side before it tries to delete anything:
+
+verb(
+ rsync -avF --delete-after host:src/dir /dest
+)
+
+However, if the merge files are not a part of the transfer, you'll need to
+either specify some global exclude rules (i.e. specified on the command
+line), or you'll need to maintain your own per-directory merge files on
+the receiving side. An example of the first is this (assume that the
+remote .rules files exclude themselves):
+
+verb(
+ rsync -av --filter=': .rules' --filter='. /my/extra.rules'
+ --delete host:src/dir /dest
+)
+
+In the above example the extra.rules file can affect both sides of the
+transfer, but (on the sending side) the rules are subservient to the rules
+merged from the .rules files because they were specified after the
+per-directory merge rule.
+
+In one final example, the remote side is excluding the .rsync-filter
+files from the transfer, but we want to use our own .rsync-filter files
+to control what gets deleted on the receiving side. To do this we must
+specifically exclude the per-directory merge files (so that they don't get
+deleted) and then put rules into the local files to control what else
+should not get deleted. Like one of these commands:
+
+verb(
+ rsync -av --filter=':e /.rsync-filter' --delete host:src/dir /dest
+ rsync -avFF --delete host:src/dir /dest