manpagesection(SETUP)
-See the file README for installation instructions.
+See the file README.md for installation instructions.
Once installed, you can use rsync to any machine that you can access via
a remote shell (as well as some that you can access using the rsync
Note that some debug messages will only be output when bf(--msgs2stderr) is
specified, especially those pertaining to I/O and buffer debugging.
-This option was added to 3.1.0, so an older rsync on the server side might
-reject your attempts at fine-grained control (if one or more flags needed
-to be send to the server and the server was too old to understand them).
-See also the "max verbosity" caveat above when dealing with a daemon.
+Beginning in 3.2.0, this option is no longer auto-forwared to the server side
+in order to allow you to specify different debug values for each side of the
+transfer, as well as to specify a new debug option that is only present in one
+of the rsync versions. If you want to duplicate the same option on both sides,
+using brace expansion is an easy way to save you some typing. This works in
+zsh and bash:
+
+verb( rsync -aiv {-M,}--debug=del2 src/ dest/ )
dit(bf(--msgs2stderr)) This option changes rsync to send all its output
directly to stderr rather than to send messages to the client side via the
automatic after-the-transfer verification has nothing to do with this
option's before-the-transfer "Does this file need to be updated?" check.
-For protocol 30 and beyond (first supported in 3.0.0), the checksum used is
-MD5. For older protocols, the checksum used is MD4.
+The checksum used is auto-negotiated between the client and the server, but
+can be overridden using either the bf(--checksum-choice) option or an
+environment variable that is discussed in that option's section.
dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
way of saying you want recursion and want to preserve almost
the source and destination are specified as local paths, but only if no
batch-writing option is in effect.
-dit(bf(--checksum-choice=STR)) This option overrides the checksum algorithms.
+dit(bf(--checksum-choice=STR, --cc=STR)) This option overrides the checksum algorithms.
If one algorithm name is specified, it is used for both the transfer checksums
-and (assuming bf(--checksum) is specified) the pre-transfer checksumming. If two
+and (assuming bf(--checksum) is specified) the pre-transfer checksums. If two
comma-separated names are supplied, the first name affects the transfer
-checksums, and the second name affects the pre-transfer checksumming.
-
-The algorithm choices are "auto", "md4", "md5", and "none". If "none" is
-specified for the first name, the bf(--whole-file) option is forced on and no
-checksum verification is performed on the transferred data. If "none" is
-specified for the second name, the bf(--checksum) option cannot be used. The
-"auto" option is the default, where rsync bases its algorithm choice on the
-protocol version (for backward compatibility with older rsync versions).
+checksums, and the second name affects the pre-transfer checksums (bf(-c)).
+
+The algorithm choices are "auto", "xxh64" (aka "xxhash"), "MD5", "MD4", and "none".
+
+If "none" is specified for the first (or only) name, the bf(--whole-file) option
+is forced on and no checksum verification is performed on the transferred data.
+If "none" is specified for the second (or only) name, the bf(--checksum) option
+cannot be used.
+
+The "auto" option is the default, where rsync bases its algorithm choice on a
+negotation between the client and the server as follows:
+
+If both the client and the server are at least version 3.2.0, they will
+exchange a list of checksum names and choose the first one in the list that
+they have in common.
+This typically means that they will choose xxh64 if they both support it
+and fall back to MD5.
+If one side of the transfer is not new enough to support this checksum
+negotation, then a value is chosen based on the protocol version (which
+chooses between MD5 and various flavors of MD4 based on protocol age).
+
+You can also override the checksum using the RSYNC_CHECKSUM_LIST environment
+variable by setting it to a space-separated list of checksum names that you
+consider acceptable. If no common checksum is found, the client exits with an
+error. This method does not allow you to specify the transfer checksum
+separately from the pre-transfer checksum, and it ignores "auto" and all
+unknown checksum names. If the remote rsync is not new enough to handle a
+checksum negotiation list, the list is silently ignored unless it contains the
+string "FAIL".
+
+The use of the bf(--checksum-choice) option overrides this environment list.
dit(bf(-x, --one-file-system)) This tells rsync to avoid crossing a
filesystem boundary when recursing. This does not limit the user's ability
The option only affects one side of the transfer unless the transfer is local,
in which case it affects both sides. Use the bf(--remote-option) to affect the
-remote side, such as bf(-M--copy-as=joe). For a local transfer, see the "lsh"
+remote side, such as bf(-M--copy-as=joe). For a local transfer, the "lsh"
support file provides a local-shell helper script that can be used to allow a
"localhost:" host-spec to be specified without needing to setup any remote
shells (allowing you to specify remote options that affect the side of the
This makes all files owned by user "joe", limits the groups to those that are
available to that user, and makes it impossible for the joe user to do a timed
-exploit of the path to induce a change to a file that the joe use has no
+exploit of the path to induce a change to a file that the joe user has no
permissions to change.
dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
as it is sent to the destination machine, which reduces the amount of data
being transmitted -- something that is useful over a slow connection.
-Note that this option typically achieves better compression ratios than can
-be achieved by using a compressing remote shell or a compressing transport
+The "zlib" compression method typically achieves better compression ratios than
+can be achieved by using a compressing remote shell or a compressing transport
because it takes advantage of the implicit information in the matching data
blocks that are not explicitly sent over the connection. This matching-data
-compression comes at a cost of CPU, though, and can be disabled by repeating
-the bf(-z) option, but only if both sides are at least version 3.1.1.
-
-Note that if your version of rsync was compiled with an external zlib (instead
-of the zlib that comes packaged with rsync) then it will not support the
-old-style compression, only the new-style (repeated-option) compression. In
-the future this new-style compression will likely become the default.
+compression comes at a cost of CPU, though, and can be disabled by using the
+"zlibx" compresson method instead. This can be selected by repeating the
+bf(-z) option or specifying bf(--compress-choice=zlibx), but it only works if
+both sides of the transfer are at least version 3.1.1.
-The client rsync requests new-style compression on the server via the
-bf(--new-compress) option, so if you see that option rejected it means that
-the server is not new enough to support bf(-zz). Rsync also accepts the
-bf(--old-compress) option for a future time when new-style compression
-becomes the default.
+Note that if you see an error about an option named bf(--old-compress) or
+bf(--new-compress), this is rsync trying to send the bf(--compress-choice=zlib)
+or bf(--compress-choice=zlibx) option in a backward-compatible manner that more
+rsync versions understand. This error indicates that the older rsync version
+will not allow you to force the compression type.
See the bf(--skip-compress) option for the default list of file suffixes
that will not be compressed.
+dit(bf(--compress-choice=STR, --zc=STR)) This option can be used to override the
+automatic selection of the compression algorithm that is the default when
+bf(--compress) is used.
+
+Currently the STR can be "zlibx", "zlib", or "none".
+
+The "zlibx" algorithm is given preference over "zlib" if both sides of the
+transfer are at least version 3.2.0, otherwise it will choose "zlib" unless you
+override it via something like bf(-zz). These 2 algorithms are the stame
+except that "zlibx" does not try to include matched data that was not
+transferred in the compression computations.
+
+If "none" is specified, that is equivalent to using bf(--no-compress).
+
+This option implies bf(--compress) unless "none" was specified.
+
+You can also override the compression negotation using the RSYNC_COMPRESS_LIST
+environment variable by setting it to a space-separated list of compression
+names that you consider acceptable. If no common compress choice is found, the
+client exits with an error. It ignores "auto" and all unknown compression
+names. If the remote rsync is not new enough to handle a compression
+negotiation list, the list is silently ignored unless it contains the string
+"FAIL".
+
dit(bf(--compress-level=NUM)) Explicitly set the compression level to use
(see bf(--compress)) instead of letting it default. If NUM is non-zero,
the bf(--compress) option is implied.
order to use bf(--info=progress2).)
Finally, you can get an instant progress report by sending rsync a signal of
-either SIGINFO or SIGVTALRM On BSD systems a SIGINFO is often generated just by
-typing a Ctrl+T (Linux doesn't currently support a SIGINFO signal). When the
-client-side process receives one of those signals, it will output a single
-progress report when the current file being transferred finishes (so it may
-take a little time if a big file is being handled when the signal arrives).
+either SIGINFO or SIGVTALRM. On BSD systems, a SIGINFO is generated by typing a
+Ctrl+T (Linux doesn't currently support a SIGINFO signal). When the client-side
+process receives one of those signals, it sets a flag to output a single
+progress report which is output when the current file transfer finishes (so it
+may take a little time if a big file is being handled when the signal arrives).
A filename is output (if needed) followed by the --info=progress2 format of
-progress info. You can send the SIGVTALRM signal to all of the rsync processes
-but just the client-side process will respond. Be careful not to send that
-signal to an older rsync, though, or it will die.
+progress info. If you don't know which of the 3 rsync processes is the client
+process, it's OK to signal all of them (since the non-client processes ignore
+the signal).
+
+CAUTION: sending SIGVTALRM to an older rsync (pre-3.2.0) will kill it.
dit(bf(--password-file=FILE)) This option allows you to provide a password for
accessing an rsync daemon via a file or via standard input if bf(FILE) is
git.samba.org / rsync.git / blobdiff