Here is a short summary of the options available in rsync. Please refer
to the detailed description below for a complete description. verb(
-v, --verbose increase verbosity
+ --info=FLAGS fine-grained informational verbosity
+ --debug=FLAGS fine-grained debug verbosity
-q, --quiet suppress non-error messages
--no-motd suppress daemon-mode MOTD (see caveat)
-c, --checksum skip based on checksum, not mod-time & size
-L, --copy-links transform symlink into referent file/dir
--copy-unsafe-links only "unsafe" symlinks are transformed
--safe-links ignore symlinks that point outside the tree
+ --munge-links munge symlinks to make them safer
-k, --copy-dirlinks transform symlink to dir into referent dir
-K, --keep-dirlinks treat symlinked dir on receiver as dir
-H, --hard-links preserve hard links
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
+ -M, --remote-option=OPTION send OPTION to the remote side only
--out-format=FORMAT output updates using the specified FORMAT
--log-file=FILE log what we're doing to the specified FILE
--log-file-format=FMT log updates using the specified FMT
--address=ADDRESS bind to the specified address
--bwlimit=KBPS limit I/O bandwidth; KBytes per second
--config=FILE specify alternate rsyncd.conf file
+ -M, --dparam=OVERRIDE override global daemon config parameter
--no-detach do not detach from the parent
--port=PORT listen on alternate port number
--log-file=FILE override the "log file" setting
dit(bf(-v, --verbose)) This option increases the amount of information you
are given during the transfer. By default, rsync works silently. A
single bf(-v) will give you information about what files are being
-transferred and a brief summary at the end. Two bf(-v) flags will give you
+transferred and a brief summary at the end. Two bf(-v) options will give you
information on what files are being skipped and slightly more
-information at the end. More than two bf(-v) flags should only be used if
+information at the end. More than two bf(-v) options should only be used if
you are debugging rsync.
-Note that the names of the transferred files that are output are done using
-a default bf(--out-format) of "%n%L", which tells you just the name of the
-file and, if the item is a link, where it points. At the single bf(-v)
-level of verbosity, this does not mention when a file gets its attributes
-changed. If you ask for an itemized list of changed attributes (either
-bf(--itemize-changes) or adding "%i" to the bf(--out-format) setting), the
-output (on the client) increases to mention all items that are changed in
-any way. See the bf(--out-format) option for more details.
+In a modern rsync, the bf(-v) option is equivalent to the setting of groups
+of bf(--info) and bf(--debug) options. You can choose to use these newer
+options in addition to, or in place of using bf(--verbose), as any
+fine-grained settings override the implied settings of bf(-v). Both
+bf(--info) and bf(--debug) have a way to ask for help that tells you
+exactly what flags are set for each increase in verbosity.
+
+dit(bf(--info=FLAGS))
+This option lets you have fine-grained control over the
+information
+output you want to see. An individual flag name may be followed by a level
+number, with 0 meaning to silence that output, 1 being the default output
+level, and higher numbers increasing the output of that flag (for those
+that support higher levels). Use
+bf(--info=help)
+to see all the available flag names, what they output, and what flag names
+are added for each increase in the verbose level. Some examples:
+
+verb( rsync -a --info=progress2 src/ dest/
+ rsync -avv --info=stats2,misc1,flist0 src/ dest/ )
+
+Note that bf(--info=name)'s output is affected by the bf(--out-format) and
+bf(--itemize-changes) (bf(-i)) options. See those options for more
+information on what is output and when.
+
+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).
+
+dit(bf(--debug=FLAGS))
+This option lets you have fine-grained control over the
+debug
+output you want to see. An individual flag name may be followed by a level
+number, with 0 meaning to silence that output, 1 being the default output
+level, and higher numbers increasing the output of that flag (for those
+that support higher levels). Use
+bf(--debug=help)
+to see all the available flag names, what they output, and what flag names
+are added for each increase in the verbose level. Some examples:
+
+verb( rsync -avvv --debug=none src/ dest/
+ rsync -avA --del --debug=del2,acl src/ dest/ )
+
+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).
dit(bf(-q, --quiet)) This option decreases the amount of information you
are given during the transfer, notably suppressing information messages
-from the remote server. This flag is useful when invoking rsync from
+from the remote server. This option name is useful when invoking rsync from
cron.
dit(bf(--no-motd)) This option affects the information that is output
also ignored. Using this option in conjunction with bf(--relative) may
give unexpected results.
+dit(bf(--munge-links)) This option tells rsync to (1) modify all symlinks on
+the receiving side in a way that makes them unusable but recoverable (see
+below), or (2) to unmunge symlinks on the sending side that had been stored in
+a munged state. This is useful if you don't quite trust the source of the data
+to not try to slip in a symlink to a unexpected place.
+
+The way rsync disables the use of symlinks is to prefix each one with the
+string "/rsyncd-munged/". This prevents the links from being used as long as
+that directory does not exist. When this option is enabled, rsync will refuse
+to run if that path is a directory or a symlink to a directory.
+
+The option only affects the client side of the transfer, so if you need it to
+affect the server, specify it via bf(--remote-option). (Note that in a local
+transfer, the client side is the sender.)
+
+This option has no affect on a daemon, since the daemon configures whether it
+wants munged symlinks via its "munge symlinks" parameter. See also the
+"munge-symlinks" perl script in the support directory of the source code.
+
dit(bf(-k, --copy-dirlinks)) This option causes the sending side to treat
a symlink to a directory as though it were a real directory. This is
useful if you don't want symlinks to non-directories to be affected, as
ACLs from incompatible systems.
The bf(--fake-super) option only affects the side where the option is used.
-To affect the remote side of a remote-shell connection, specify an rsync
-path:
+To affect the remote side of a remote-shell connection, use the
+bf(--remote-option) (bf(-M)) option:
-quote(tt( rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
+quote(tt( rsync -av -M--fake-super /src/ host:/dest/))
-Since there is only one "side" in a local copy, this option affects both
-the sending and receiving of files. You'll need to specify a copy using
-"localhost" if you need to avoid this, possibly using the "lsh" shell
-script (from the support directory) as a substitute for an actual remote
-shell (see bf(--rsh)).
+For a local copy, this option affects both the source and the destination.
+If you wish a local copy to enable this option just for the destination
+files, specify bf(-M--fake-super). If you wish a local copy to enable
+this option just for the source files, combine bf(--fake-super) with
+bf(-M--super).
This option is overridden by both bf(--super) and bf(--no-super).
quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/))
+dit(bf(-M, --remote-option=OPTION)) This option is used for more advanced
+situations where you want certain effects to be limited to one side of the
+transfer only. For instance, if you want to pass bf(--log-file=FILE) and
+bf(--fake-super) to the remote system, specify it like this:
+
+quote(tt( rsync -av -M --log-file=foo -M--fake-super src/ dest/))
+
+If you want to have an option affect only the local side of a transfer when
+it normally affects both sides, send its negation to the remote side. Like
+this:
+
+quote(tt( rsync -av -x -M--no-x src/ dest/))
+
+Be cautious using this, as it is possible to toggle an option that will cause
+rsync to have a different idea about what data to expect next over the socket,
+and that will make it fail in a cryptic fashion.
+
+Note that it is best to use a separate bf(--remote-option) for each option you
+want to pass. This makes your useage compatible with the bf(--protect-args)
+option. If that option is off, any spaces in your remote options will be split
+by the remote shell unless you take steps to protect them.
+
+When performing a local transfer, the "local" side is the sender and the
+"remote" side is the receiver.
+
+Note some versions of the popt option-parsing library have a bug in them that
+prevents you from using an adjacent arg with an equal in it next to a short
+option letter (e.g. tt(-M--log-file=/tmp/foo). If this bug affects your
+version of popt, you can use the version of popt that is included with rsync.
+
dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
broad range of files that you often don't want to transfer between
systems. It uses a similar algorithm to CVS to determine if
quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
+If file's aren't linking, double-check their attributes. Also check if some
+attributes are getting forced outside of rsync's control, such a mount option
+that squishes root to a single user, or mounts a removable drive with generic
+ownership (such as OS X's "Ignore ownership on this volume" option).
+
Beginning in version 2.6.4, multiple bf(--link-dest) directories may be
provided, which will cause rsync to search the list in the order specified
for an exact match.
outputting them as a verbose message).
dit(bf(--out-format=FORMAT)) This allows you to specify exactly what the
-rsync client outputs to the user on a per-update basis. The format is a text
-string containing embedded single-character escape sequences prefixed with
-a percent (%) character. For a list of the possible escape characters, see
-the "log format" setting in the rsyncd.conf manpage.
-
-Specifying this option will mention each file, dir, etc. that gets updated
-in a significant way (a transferred file, a recreated symlink/device, or a
-touched directory). In addition, if the itemize-changes escape (%i) is
-included in the string, the logging of names increases to mention any
-item that is changed in any way (as long as the receiving side is at least
-2.6.4). See the bf(--itemize-changes) option for a description of the
-output of "%i".
-
-The bf(--verbose) option implies a format of "%n%L", but you can use
-bf(--out-format) without bf(--verbose) if you like, or you can override
-the format of its per-file output using this option.
+rsync client outputs to the user on a per-update basis. The format is a
+text string containing embedded single-character escape sequences prefixed
+with a percent (%) character. A default format of "%n%L" is assumed if
+either bf(--info=name) or bf(-v) is specified (this tells you just the name
+of the file and, if the item is a link, where it points). For a full list
+of the possible escape characters, see the "log format" setting in the
+rsyncd.conf manpage.
+
+Specifying the bf(--out-format) option implies the bf(--info=name) option,
+which will mention each file, dir, etc. that gets updated in a significant
+way (a transferred file, a recreated symlink/device, or a touched
+directory). In addition, if the itemize-changes escape (%i) is included in
+the string (e.g. if the bf(--itemize-changes) option was used), the logging
+of names increases to mention any item that is changed in any way (as long
+as the receiving side is at least 2.6.4). See the bf(--itemize-changes)
+option for a description of the output of "%i".
Rsync will output the out-format string prior to a file's transfer unless
one of the transfer-statistic escapes is requested, in which case the
Here's a example command that requests the remote side to log what is
happening:
-verb( rsync -av --rsync-path="rsync --log-file=/tmp/rlog" src/ dest/)
+verb( rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/)
This is very useful if you need to debug why a connection is closing
unexpectedly.
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
on the file transfer, allowing you to tell how effective rsync's delta-transfer
-algorithm is for your data.
+algorithm is for your data. This option is equivalent to bf(--info=stats2)
+if combined with 0 or 1 bf(-v) options, or bf(--info=stats3) if combined
+with 2 or more bf(-v) options.
The current statistics are as follows: quote(itemization(
it() bf(Number of files) is the count of all "files" (in the generic
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.
+With a modern rsync this is the same as specifying
+bf(--info=flist2,name,progress), but any user-supplied settings for those
+info flags takes precedence (e.g. "--info=flist0 --progress").
While rsync is transferring a regular file, it updates a progress line that
looks like this:
purpose is to make it much easier to specify these two options for a long
transfer that may be interrupted.
+There is also a bf(--info=progress2) option that outputs statistics based
+on the whole transfer, rather than individual files. Use this flag without
+outputting a filename (e.g. avoid bf(-v) or specify bf(--info=name0) if you
+want to see how the transfer is doing without scrolling the screen with a
+lot of names. (You don't need to specify the bf(--progress) option in
+order to use bf(--info=progress2).)
+
dit(bf(--password-file)) This option allows you to provide a password in a
file for accessing an rsync daemon. The file must not be world readable.
It should contain just the password as a single line.
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 code(time())
+Setting NUM to 0 causes rsync to use the default of code(time())
for checksum seed.
enddit()
a remote shell program and the remote user is not the super-user; in that case
the default is rsyncd.conf in the current directory (typically $HOME).
+dit(bf(-M, --dparam=OVERRIDE)) This option can be used to set a daemon-config
+parameter when starting up rsync in daemon mode. It is equivalent to adding
+the parameter at the end of the global settings prior to the first module's
+definition. The parameter names can be specified without spaces, if you so
+desire. For instance:
+
+verb( rsync --daemon -M pidfile=/path/rsync.pid )
+
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