+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(--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(--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(--address)) By default rsync will bind to the wildcard address
+when run as a daemon with the --daemon option or when connecting to a
+rsync server. The --address option allows you to specify a specific IP
+address (or hostname) to bind to. This makes virtual hosting possible
+in conjunction with the --config option.
+
+dit(bf(--config=FILE)) This specifies an alternate config file than
+the default. This is only relevant when --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(--port=PORT)) This specifies an alternate TCP port number to use
+rather than the default port 873.
+
+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 --blocking-io, for use when it is the
+default.
+
+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
+--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(--progress)) This option tells rsync to print information
+showing the progress of the transfer. This gives a bored user
+something to watch.
+Implies --verbose without incrementing verbosity.
+
+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 the a file is complete, it 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 -P option is equivalent to --partial --progress. I
+found myself typing that combination quite often so I created an
+option to make it easier.
+
+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(--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=PREFIX)) Generate a set of files that can be
+transferred as a batch update. Each filename in the set starts with
+PREFIX. See the "BATCH MODE" section for details.
+
+dit(bf(--read-batch=PREFIX)) Apply a previously generated change batch,
+using the fileset whose filenames start with PREFIX. 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, or the incoming sockets that an rsync daemon uses 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 --ipv6 or --ipv4 when starting the daemon).
+
+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(), or 32761 if
+bf(--write-batch) or bf(--read-batch) are specified. 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. Note also that bf(--write-batch) and bf(--read-batch)
+set the checksum seed to 32761, so bf(--checksum-seed=NUM) needs to
+follow these options if you want to specify a different checksum
+seed in batch mode.
+
+enddit()
+
+manpagesection(EXCLUDE PATTERNS)
+
+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. Rsync checks each file and directory
+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.
+
+The filenames matched against the exclude/include patterns are relative
+to the "root of the transfer". If you think of the transfer as a
+subtree of names that are being sent from sender to receiver, the root
+is where the tree starts to be duplicated in the destination directory.
+This root governs where patterns that start with a / match (see below).
+
+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
+system). 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 include/exclude 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).
+
+Note that, when using the --recursive (-r) option (which is implied by -a),
+every subcomponent of
+every path is visited from the top down, so include/exclude patterns get
+applied recursively to each subcomponent.
+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.
+
+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.
+ This is the equivalent of a leading ^ in regular expressions.
+ Thus "/foo" would match a file called "foo" at the transfer-root
+ (see above for how this is different from the filesystem-root).
+ 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() 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 filename, including any leading
+ directory. If the pattern doesn't contain a / or 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 below the starting directory.
+
+ 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 prefix 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 prefix 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 a list that was read from a file, allowing
+you to have a single exclude list that contains both include and exclude
+options in the proper order.
+
+Remember that the matching occurs at every step in the traversal of the
+directory hierarchy, so you must be sure that all the parent directories of
+the files you want to include are not excluded. This is particularly
+important when using a trailing '*' rule. For instance, this won't work:
+
+verb(
+ + /some/path/this-file-will-not-be-found
+ + /file-is-included
+ - *
+)
+
+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: --include='*/' (put it somewhere
+before the --exclude='*' 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:
+
+verb(
+ + /some/
+ + /some/path/
+ + /some/path/this-file-is-found
+ + /file-also-included
+ - *
+)
+
+Here are some examples of exclude/include matching:
+
+itemize(
+ it() --exclude "*.o" would exclude all filenames matching *.o
+ it() --exclude "/foo" would exclude a file called foo in the transfer-root directory
+ it() --exclude "foo/" would exclude any directory called foo
+ it() --exclude "/foo/*/bar" would exclude any file called bar two
+ levels below a directory called foo in the transfer-root directory
+ it() --exclude "/foo/**/bar" would exclude any file called bar two
+ or more levels below a directory called foo in the transfer-root directory
+ 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 behavior 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:
+ $ ssh remote rsync --read-batch=pfx -a /bdest/dir/
+ # or alternatively
+ $ ssh 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.