+The exclude and include patterns specified to rsync allow for flexible
+selection of which files to transfer and which files to skip.
+
+rsync builds an ordered list of include/exclude options as specified on
+the command line. When a filename is encountered, rsync checks the
+name against each exclude/include pattern in turn. The first matching
+pattern is acted on. If it is an exclude pattern, then that file is
+skipped. If it is an include pattern then that filename is not
+skipped. If no matching include/exclude pattern is found then the
+filename is not skipped.
+
+Note that when used with -r (which is implied by -a), every subcomponent of
+every path is visited from top down, so include/exclude patterns get
+applied recursively to each subcomponent.
+
+Note also that the --include and --exclude options take one pattern
+each. To add multiple patterns use the --include-from and
+--exclude-from options or multiple --include and --exclude options.
+
+The patterns can take several forms. The rules are:
+
+itemize(
+ it() if the pattern starts with a / then it is matched against the
+ start of the filename, otherwise it is matched against the end of
+ the filename. Thus "/foo" would match a file called "foo" at the base of
+ the tree. On the other hand, "foo" would match any file called "foo"
+ anywhere in the tree because the algorithm is applied recursively from
+ top down; it behaves as if each path component gets a turn at being the
+ end of the file name.
+
+ it() if the pattern ends with a / then it will only match a
+ directory, not a file, link or device.
+
+ it() if the pattern contains a wildcard character from the set
+ *?[ then expression matching is applied using the shell filename
+ matching rules. Otherwise a simple string match is used.
+
+ it() if the pattern includes a double asterisk "**" then all wildcards in
+ the pattern will match slashes, otherwise they will stop at slashes.
+
+ it() if the pattern contains a / (not counting a trailing /) then it
+ is matched against the full filename, including any leading
+ directory. If the pattern doesn't contain a / then it is matched
+ only against the final component of the filename. Again, remember
+ that the algorithm is applied recursively so "full filename" can
+ actually be any portion of a path.
+
+ it() if the pattern starts with "+ " (a plus followed by a space)
+ then it is always considered an include pattern, even if specified as
+ part of an exclude option. The "+ " part is discarded before matching.
+
+ it() if the pattern starts with "- " (a minus followed by a space)
+ then it is always considered an exclude pattern, even if specified as
+ part of an include option. The "- " part is discarded before matching.
+
+ it() if the pattern is a single exclamation mark ! then the current
+ include/exclude list is reset, removing all previously defined patterns.
+)
+
+The +/- rules are most useful in exclude lists, allowing you to have a
+single exclude list that contains both include and exclude options.
+
+If you end an exclude list with --exclude '*', note that since the
+algorithm is applied recursively that unless you explicitly include
+parent directories of files you want to include then the algorithm
+will stop at the parent directories and never see the files below
+them. To include all directories, use --include '*/' before the
+--exclude '*'.
+
+Here are some exclude/include examples:
+
+itemize(
+ it() --exclude "*.o" would exclude all filenames matching *.o
+ it() --exclude "/foo" would exclude a file in the base directory called foo
+ it() --exclude "foo/" would exclude any directory called foo
+ it() --exclude "/foo/*/bar" would exclude any file called bar two
+ levels below a base directory called foo
+ it() --exclude "/foo/**/bar" would exclude any file called bar two
+ or more levels below a base directory called foo
+ it() --include "*/" --include "*.c" --exclude "*" would include all
+ directories and C source files
+ it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
+ only foo/bar.c (the foo/ directory must be explicitly included or
+ it would be excluded by the "*")
+)
+
+manpagesection(BATCH MODE)
+
+bf(Note:) Batch mode should be considered experimental in this version
+of rsync. The interface or behaviour may change before it stabilizes.
+
+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 the information needed to repeat this operation against
+other destination trees in a batch update fileset (see below). The
+filename of each file in the fileset starts with a prefix specified by
+the user as an argument to the write-batch option. This fileset is
+then copied to each remote host, where rsync is run with the read-batch
+option, again specifying the same prefix, and the destination tree.
+Rsync updates the destination tree using the information stored in the
+batch update fileset.
+
+The fileset consists of 4 files:
+
+itemize(
+it() bf(<prefix>.rsync_argvs) command-line arguments
+it() bf(<prefix>.rsync_flist) rsync internal file metadata
+it() bf(<prefix>.rsync_csums) rsync checksums
+it() bf(<prefix>.rsync_delta) data blocks for file update & change
+)
+
+The .rsync_argvs file contains a command-line suitable for updating a
+destination tree using that batch update fileset. 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 update fileset 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.
+
+Example:
+
+verb(
+$ rsync --write_batch=pfx -a /source/dir/ /adest/dir/
+$ rcp pfx.rsync_* remote:
+$ rsh remote rsync --read_batch=pfx -a /bdest/dir/
+# or alternatively
+$ rsh remote ./pfx.rsync_argvs /bdest/dir/
+)
+
+In this example, rsync is used to update /adest/dir/ with /source/dir/
+and the information to repeat this operation is stored in the files
+pfx.rsync_*. These files are then copied to the machine named "remote".
+Rsync is then invoked on "remote" to update /bdest/dir/ the same way as
+/adest/dir/. The last line shows the rsync_argvs file being used to
+invoke rsync.
+
+Caveats:
+
+The read-batch option expects the destination tree it is meant to update
+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 will fail at that point, leaving the
+destination tree 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 should be identical to the
+one used on the original destination.
+
+The -z/--compress option does not work in batch mode and yields a usage
+error. A separate compression tool can be used instead to reduce the
+size of the batch update files for transport to the destination.
+
+The -n/--dryrun option does not work in batch mode and yields a runtime
+error.
+
+See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
+reports.
+
+manpagesection(SYMBOLIC LINKS)
+
+Three basic behaviours 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 ommitted altogether.