+If a user or group has no name on the source system or it has no match
+on the destination system, then the numeric ID
+from the source system is used instead. See also the comments on the
+"use chroot" setting in the rsyncd.conf manpage for information on how
+the chroot setting affects rsync's ability to look up the names of the
+users and groups and what you can do about it.
+
+dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
+timeout in seconds. If no data is transferred for the specified time
+then rsync will exit. The default is 0, which means no timeout.
+
+dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
+rather than the default of 873. This is only needed if you are using the
+double-colon (::) syntax to connect with an rsync daemon (since the URL
+syntax has a way to specify the port as a part of the URL). See also this
+option in the bf(--daemon) mode section.
+
+dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching
+a remote shell transport. If the remote shell is either rsh or remsh,
+rsync defaults to using
+blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
+ssh prefers non-blocking I/O.)
+
+dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the
+default.
+
+dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
+changes that are being made to each file. It is equivalent to specifying
+bf(--log-format='%i %n%L'). See the description of these items in the
+rsyncd.conf manpage.
+
+dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
+rsync client logs to stdout on a per-file basis. The log format is
+specified using the same format conventions as the log format option in
+rsyncd.conf.
+
+dit(bf(--stats)) This tells rsync to print a verbose set of statistics
+on the file transfer, allowing you to tell how effective the rsync
+algorithm is for your data.
+
+dit(bf(--partial)) By default, rsync will delete any partially
+transferred file if the transfer is interrupted. In some circumstances
+it is more desirable to keep partially transferred files. Using the
+bf(--partial) option tells rsync to keep the partial file which should
+make a subsequent transfer of the rest of the file much faster.
+
+dit(bf(--partial-dir=DIR)) A better way to keep partial files than the
+bf(--partial) option is to specify a em(DIR) that will be used to hold the
+partial data (instead of writing it out to the destination file).
+On the next transfer, rsync will use a file found in this
+dir as data to speed up the resumption of the transfer and then deletes it
+after it has served its purpose.
+Note that if bf(--whole-file) is specified (or implied), any partial-dir
+file that is found for a file that is being updated will simply be removed
+(since
+rsync is sending files without using the incremental rsync algorithm).
+
+Rsync will create the em(DIR) if it is missing (just the last dir -- not
+the whole path). This makes it easy to use a relative path (such as
+"bf(--partial-dir=.rsync-partial)") to have rsync create the
+partial-directory in the destination file's directory when needed, and then
+remove it again when the partial file is deleted.
+
+If the partial-dir value is not an absolute path, rsync will also add a directory
+bf(--exclude) of this value at the end of all your existing excludes. This
+will prevent partial-dir files from being transferred and also prevent the
+untimely deletion of partial-dir items on the receiving side. An example:
+the above bf(--partial-dir) option would add an "bf(--exclude=.rsync-partial/)"
+rule at the end of any other filter rules. Note that if you are
+supplying your own filter rules, you may need to manually insert a
+rule for this directory exclusion somewhere higher up in the list so that
+it has a high enough priority to be effective (e.g., if your rules specify
+a trailing bf(--exclude='*') rule, the auto-added rule would never be
+reached).
+
+IMPORTANT: the bf(--partial-dir) should not be writable by other users or it
+is a security risk. E.g. AVOID "/tmp".
+
+You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
+variable. Setting this in the environment does not force bf(--partial) to be
+enabled, but rather it effects where partial files go when bf(--partial) is
+specified. For instance, instead of using bf(--partial-dir=.rsync-tmp)
+along with bf(--progress), you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
+environment and then just use the bf(-P) option to turn on the use of the
+.rsync-tmp dir for partial transfers. The only time that the bf(--partial)
+option does not look for this environment value is (1) when bf(--inplace) was
+specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when
+bf(--delay-updates) was specified (see below).
+
+For the purposes of the server-config's "refuse options" setting,
+bf(--partial-dir) does em(not) imply bf(--partial). This is so that a
+refusal of the bf(--partial) option can be used to disallow the overwriting
+of destination files with a partial transfer, while still allowing the
+safer idiom provided by bf(--partial-dir).
+
+dit(bf(--delay-updates)) This option puts the temporary file from each
+updated file into a holding directory until the end of the
+transfer, at which time all the files are renamed into place in rapid
+succession. This attempts to make the updating of the files a little more
+atomic. By default the files are placed into a directory named ".~tmp~" in
+each file's destination directory, but you can override this by specifying
+the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect
+on this value, nor is bf(--partial-dir) considered to be implied for the
+purposes of the server-config's "refuse options" setting.)
+Conflicts with bf(--inplace).
+
+This option uses more memory on the receiving side (one bit per file
+transferred) and also requires enough free disk space on the receiving
+side to hold an additional copy of all the updated files. Note also that
+you should not use an absolute path to bf(--partial-dir) unless there is no
+chance of any of the files in the transfer having the same name (since all
+the updated files will be put into a single directory if the path is
+absolute).
+
+See also the "atomic-rsync" perl script in the "support" subdir for an
+update algorithm that is even more atomic (it uses bf(--link-dest) and a
+parallel hierarchy of files).
+
+dit(bf(--progress)) This option tells rsync to print information
+showing the progress of the transfer. This gives a bored user
+something to watch.
+Implies bf(--verbose) if it wasn't already specified.
+
+When the file is transferring, the data looks like this:
+
+verb( 782448 63% 110.64kB/s 0:00:04)
+
+This tells you the current file size, the percentage of the transfer that
+is complete, the current calculated file-completion rate (including both
+data over the wire and data being matched locally), and the estimated time
+remaining in this transfer.
+
+After a file is complete, the data looks like this:
+
+verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396))
+
+This tells you the final file size, that it's 100% complete, the final
+transfer rate for the file, the amount of elapsed time it took to transfer
+the file, and the addition of a total-transfer summary in parentheses.
+These additional numbers tell you how many files have been updated, and
+what percent of the total number of files has been scanned.
+
+dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). Its
+purpose is to make it much easier to specify these two options for a long
+transfer that may be interrupted.
+
+dit(bf(--password-file)) This option allows you to provide a password
+in a file for accessing a remote rsync server. Note that this option
+is only useful when accessing an rsync server using the built in
+transport, not when using a remote shell as the transport. The file
+must not be world readable. It should contain just the password as a
+single line.
+
+dit(bf(--list-only)) This option will cause the source files to be listed
+instead of transferred. This option is inferred if there is no destination
+specified, so you don't usually need to use it explicitly. However, it can
+come in handy for a power user that wants to avoid the "bf(-r --exclude='/*/*')"
+options that rsync might use as a compatibility kluge when generating a
+non-recursive listing.
+
+dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
+transfer rate in kilobytes per second. This option is most effective when
+using rsync with large files (several megabytes and up). Due to the nature
+of rsync transfers, blocks of data are sent, then if rsync determines the
+transfer was too fast, it will wait before sending the next data block. The
+result is an average transfer rate equaling the specified limit. A value
+of zero specifies no limit.
+
+dit(bf(--write-batch=FILE)) Record a file that can later be applied to
+another identical destination with bf(--read-batch). See the "BATCH MODE"
+section for details.
+
+dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
+file previously generated by bf(--write-batch).
+If em(FILE) is "-" the batch data will be read from standard input.
+See the "BATCH MODE" section for details.
+
+dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
+when creating sockets. This only affects sockets that rsync has direct
+control over, such as the outgoing socket when directly contacting an
+rsync daemon. See also these options in the bf(--daemon) mode section.
+
+dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
+NUM. This 4 byte checksum seed is included in each block and file
+MD4 checksum calculation. By default the checksum seed is generated
+by the server and defaults to the current time(). This option
+is used to set a specific checksum seed, which is useful for
+applications that want repeatable block and file checksums, or
+in the case where the user wants a more random checksum seed.
+Note that setting NUM to 0 causes rsync to use the default of time()
+for checksum seed.
+enddit()
+
+manpagesection(DAEMON OPTIONS)
+
+The options allowed when starting an rsync daemon are as follows:
+
+startdit()
+dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
+daemon may be accessed using the bf(host::module) or
+bf(rsync://host/module/) syntax.
+
+If standard input is a socket then rsync will assume that it is being
+run via inetd, otherwise it will detach from the current terminal and
+become a background daemon. The daemon will read the config file
+(rsyncd.conf) on each connect made by a client and respond to
+requests accordingly. See the rsyncd.conf(5) man page for more
+details.
+
+dit(bf(--address)) By default rsync will bind to the wildcard address
+when run as a daemon with the bf(--daemon) option or when connecting to a
+rsync server. The bf(--address) option allows you to specify a specific IP
+address (or hostname) to bind to. This makes virtual hosting possible
+in conjunction with the bf(--config) option. See also the "address" global
+option in the rsyncd.conf manpage.
+
+dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
+transfer rate in kilobytes per second for the data the daemon sends.
+The client can still specify a smaller bf(--bwlimit) value, but their
+requested value will be rounded down if they try to exceed it. See the
+client version of this option (above) for some extra details.
+
+dit(bf(--config=FILE)) This specifies an alternate config file than
+the default. This is only relevant when bf(--daemon) is specified.
+The default is /etc/rsyncd.conf unless the daemon is running over
+a remote shell program and the remote user is not root; in that case
+the default is rsyncd.conf in the current directory (typically $HOME).
+
+dit(bf(--no-detach)) When running as a daemon, this option instructs
+rsync to not detach itself and become a background process. This
+option is required when running as a service on Cygwin, and may also
+be useful when rsync is supervised by a program such as
+bf(daemontools) or AIX's bf(System Resource Controller).
+bf(--no-detach) is also recommended when rsync is run under a
+debugger. This option has no effect if rsync is run from inetd or
+sshd.
+
+dit(bf(--port=PORT)) This specifies an alternate TCP port number for the
+daemon to listen on rather than the default of 873. See also the "port"
+global option in the rsyncd.conf manpage.
+
+dit(bf(-v, --verbose)) This option increases the amount of information the
+daemon logs during its startup phase. After the client connects, the
+daemon's verbosity level will be controlled by the options that the client
+used and the "max verbosity" setting in the module's config section.
+
+dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
+when creating the incoming sockets that the rsync daemon will use to
+listen for connections. One of these options may be required in older
+versions of Linux to work around an IPv6 bug in the kernel (if you see
+an "address already in use" error when nothing else is using the port,
+try specifying bf(--ipv6) or bf(--ipv4) when starting the daemon).
+
+dit(bf(-h, --help)) When specified after bf(--daemon), print a short help
+page describing the options available for starting an rsync daemon.
+enddit()
+
+manpagesection(FILTER RULES)
+
+The filter rules allow for flexible selection of which files to transfer
+(include) and which files to skip (exclude). The rules either directly
+specify include/exclude patterns or they specify a way to acquire more
+include/exclude patterns (e.g. to read them from a file).
+
+As the list of files/directories to transfer is built, rsync checks each
+name to be transferred against the list of include/exclude patterns in
+turn, and 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 pattern is found, then the
+filename is not skipped.
+
+Rsync builds an ordered list of filter rules as specified on the
+command-line. Filter rules have the following syntax:
+
+quote(
+tt(RULE [PATTERN_OR_FILENAME])nl()
+tt(RULE,MODIFIERS [PATTERN_OR_FILENAME])nl()
+)
+
+You have your choice of using either short or long RULE names, as described
+below. If you use a short-named rule, the ',' separating the RULE from the
+MODIFIERS is optional. The PATTERN or FILENAME that follows (when present)
+must come after either a single space or an underscore (_).
+Here are the available rule prefixes:
+
+quote(
+bf(exclude, -) specifies an exclude pattern. nl()
+bf(include, +) specifies an include pattern. nl()
+bf(merge, .) specifies a merge-file to read for more rules. nl()
+bf(dir-merge, :) specifies a per-directory merge-file. nl()
+bf(hide, H) specifies a pattern for hiding files from the transfer. nl()
+bf(show, S) files that match the pattern are not hidden. nl()
+bf(protect, P) specifies a pattern for protecting files from deletion. nl()
+bf(risk, R) files that match the pattern are not protected. nl()
+bf(clear, !) clears the current include/exclude list (takes no arg) nl()
+)
+
+When rules are being read from a file, empty lines are ignored, as are
+comment lines that start with a "#".
+
+Note that the bf(--include)/bf(--exclude) command-line options do not allow the
+full range of rule parsing as described above -- they only allow the
+specification of include/exclude patterns plus a "!" token to clear the
+list (and the normal comment parsing when rules are read from a file).
+If a pattern
+does not begin with "- " (dash, space) or "+ " (plus, space), then the
+rule will be interpreted as if "+ " (for an include option) or "- " (for
+an exclude option) were prefixed to the string. A bf(--filter) option, on
+the other hand, must always contain either a short or long rule name at the
+start of the rule.
+
+Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one
+rule/pattern each. To add multiple ones, you can repeat the options on
+the command-line, use the merge-file syntax of the bf(--filter) option, or
+the bf(--include-from)/bf(--exclude-from) options.
+
+manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
+
+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:
+
+itemize(
+ it() 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 file called "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 any file or directory named "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 file name. 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.
+ 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() 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 server 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 server-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 no error (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.
+
+The bf(--dry-run) (bf(-n)) option does not work in batch mode and yields a runtime
+error.
+
+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.
+
+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.
+
+manpagediagnostics()