+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).
+
+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 bf(-F)):
+
+quote(tt(--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:
+
+quote(
+tt(rsync -avF /src/path/ /dest/dir)nl()
+tt(rsync -av --filter=': ../../.rsync-filter' /src/path/ /dest/dir)nl()
+tt(rsync -av --filter=': .rsync-filter' /src/path/ /dest/dir)nl()
+)
+
+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", 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 the
+":C" wherever you like in your filter rules. Without this, rsync would
+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:
+
+quote(
+tt(cat <<EOT | rsync -avC --filter='. -' a/ b)nl()
+tt(+ foo.o)nl()
+tt(:C)nl()
+tt(- *.old)nl()
+tt(EOT)nl()
+tt(rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b)nl()
+)
+
+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. To
+affect the other CVS exclude rules (i.e. the default list of exclusions,
+the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
+omit the bf(-C) command-line option and instead insert a "-C" rule into
+your filter rules; e.g. "--filter=-C".
+
+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 bf(--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:
+
+quote(
+ Example cmd: rsync -a /home/me /home/you /dest nl()
+ +/- pattern: /me/foo/bar nl()
+ +/- pattern: /you/bar/baz nl()
+ Target file: /dest/me/foo/bar nl()
+ Target file: /dest/you/bar/baz nl()
+)
+
+quote(
+ Example cmd: rsync -a /home/me/ /home/you/ /dest nl()
+ +/- pattern: /foo/bar (note missing "me") nl()
+ +/- pattern: /bar/baz (note missing "you") nl()
+ Target file: /dest/foo/bar nl()
+ Target file: /dest/bar/baz nl()
+)
+
+quote(
+ Example cmd: rsync -a --relative /home/me/ /home/you /dest nl()
+ +/- pattern: /home/me/foo/bar (note full path) nl()
+ +/- pattern: /home/you/bar/baz (ditto) nl()
+ Target file: /dest/home/me/foo/bar nl()
+ Target file: /dest/home/you/bar/baz nl()
+)
+
+quote(
+ Example cmd: cd /home; rsync -a --relative me/foo you/ /dest nl()
+ +/- pattern: /me/foo/bar (starts at specified path) nl()
+ +/- pattern: /you/bar/baz (ditto) nl()
+ Target file: /dest/me/foo/bar nl()
+ Target file: /dest/you/bar/baz nl()
+)
+
+The easiest way to see what name you should filter is to just
+look at the output when using bf(--verbose) and put a / in front of the name
+(use the bf(--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:
+
+quote(
+tt(rsync -av --filter=': .excl' --exclude=.excl host:src/dir /dest)nl()
+tt(rsync -av --filter=':e .excl' host:src/dir /dest)nl()
+)
+
+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 bf(--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:
+
+quote(tt(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)
+
+manpagesection(BATCH MODE)
+
+Batch mode can be used to apply the same set of updates to many
+identical systems. Suppose one has a tree which is replicated on a
+number of hosts. Now suppose some changes have been made to this
+source tree and those changes need to be propagated to the other
+hosts. In order to do this using batch mode, rsync is run with the
+write-batch option to apply the changes made to the source tree to one
+of the destination trees. The write-batch option causes the rsync
+client to store in a "batch file" all the information needed to repeat
+this operation against other, identical destination trees.
+
+To apply the recorded changes to another destination tree, run rsync
+with the read-batch option, specifying the name of the same batch
+file, and the destination tree. Rsync updates the destination tree
+using the information stored in the batch file.
+
+For convenience, one additional file is creating when the write-batch
+option is used. This file's name is created by appending
+".sh" to the batch filename. The .sh file contains
+a command-line suitable for updating a destination tree using that
+batch file. It can be executed using a Bourne(-like) shell, optionally
+passing in an alternate destination tree pathname which is then used
+instead of the original path. This is useful when the destination tree
+path differs from the original destination tree path.
+
+Generating the batch file once saves having to perform the file
+status, checksum, and data block generation more than once when
+updating multiple destination trees. Multicast transport protocols can
+be used to transfer the batch update files in parallel to many hosts
+at once, instead of sending the same data to every host individually.
+
+Examples:
+
+quote(
+tt($ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/)nl()
+tt($ scp foo* remote:)nl()
+tt($ ssh remote ./foo.sh /bdest/dir/)nl()
+)
+
+quote(
+tt($ rsync --write-batch=foo -a /source/dir/ /adest/dir/)nl()
+tt($ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo)nl()
+)
+
+In these examples, rsync is used to update /adest/dir/ from /source/dir/
+and the information to repeat this operation is stored in "foo" and
+"foo.sh". The host "remote" is then updated with the batched data going
+into the directory /bdest/dir. The differences between the two examples
+reveals some of the flexibility you have in how you deal with batches:
+
+itemize(
+ it() The first example shows that the initial copy doesn't have to be
+ local -- you can push or pull data to/from a remote host using either the
+ remote-shell syntax or rsync daemon syntax, as desired.
+ it() The first example uses the created "foo.sh" file to get the right
+ rsync options when running the read-batch command on the remote host.
+ it() The second example reads the batch data via standard input so that
+ the batch file doesn't need to be copied to the remote machine first.
+ This example avoids the foo.sh script because it needed to use a modified
+ bf(--read-batch) option, but you could edit the script file if you wished to
+ make use of it (just be sure that no other option is trying to use
+ standard input, such as the "bf(--exclude-from=-)" option).
+)
+
+Caveats:
+
+The read-batch option expects the destination tree that it is updating
+to be identical to the destination tree that was used to create the
+batch update fileset. When a difference between the destination trees
+is encountered the update might be discarded with a warning (if the file
+appears to be up-to-date already) or the file-update may be attempted
+and then, if the file fails to verify, the update discarded with an
+error. This means that it should be safe to re-run a read-batch operation
+if the command got interrupted. If you wish to force the batched-update to
+always be attempted regardless of the file's size and date, use the bf(-I)
+option (when reading the batch).
+If an error occurs, the destination tree will probably be in a
+partially updated state. In that case, rsync can
+be used in its regular (non-batch) mode of operation to fix up the
+destination tree.
+
+The rsync version used on all destinations must be at least as new as the
+one used to generate the batch file. Rsync will die with an error if the
+protocol version in the batch file is too new for the batch-reading rsync
+to handle. See also the bf(--protocol) option for a way to have the
+creating rsync generate a batch file that an older rsync can understand.
+(Note that batch files changed format in version 2.6.3, so mixing versions
+older than that with newer versions will not work.)
+
+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.
+
+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
+shell script file. An advanced user can use this to modify the exclude
+list if a change in what gets deleted by bf(--delete) is desired. A normal
+user can ignore this detail and just use the shell script as an easy way
+to run the appropriate bf(--read-batch) command for the batched data.
+
+The original batch mode in rsync was based on "rsync+", but the latest
+version uses a new implementation.
+
+manpagesection(SYMBOLIC LINKS)
+
+Three basic behaviors are possible when rsync encounters a symbolic
+link in the source directory.
+
+By default, symbolic links are not transferred at all. A message
+"skipping non-regular" file is emitted for any symlinks that exist.
+
+If bf(--links) is specified, then symlinks are recreated with the same
+target on the destination. Note that bf(--archive) implies
+bf(--links).
+
+If bf(--copy-links) is specified, then symlinks are "collapsed" by
+copying their referent, rather than the symlink.
+
+rsync also distinguishes "safe" and "unsafe" symbolic links. An
+example where this might be used is a web site mirror that wishes
+ensure the rsync module they copy does not include symbolic links to
+bf(/etc/passwd) in the public section of the site. Using
+bf(--copy-unsafe-links) will cause any links to be copied as the file
+they point to on the destination. Using bf(--safe-links) will cause
+unsafe links to be omitted altogether. (Note that you must specify
+bf(--links) for bf(--safe-links) to have any effect.)
+
+Symbolic links are considered unsafe if they are absolute symlinks
+(start with bf(/)), empty, or if they contain enough bf("..")
+components to ascend from the directory being copied.
+
+Here's a summary of how the symlink options are interpreted. The list is
+in order of precedence, so if your combination of options isn't mentioned,
+use the first line that is a complete subset of your options:
+
+dit(bf(--copy-links)) Turn all symlinks into normal files (leaving no
+symlinks for any other options to affect).
+
+dit(bf(--links --copy-unsafe-links)) Turn all unsafe symlinks into files
+and duplicate all safe symlinks.
+
+dit(bf(--copy-unsafe-links)) Turn all unsafe symlinks into files, noisily
+skip all safe symlinks.
+
+dit(bf(--links --safe-links)) Duplicate safe symlinks and skip unsafe
+ones.
+
+dit(bf(--links)) Duplicate all symlinks.
+
+manpagediagnostics()