a fast, versatile, remote (and local) file-copying tool
|
--progress
This option tells rsync to print information showing the progress of the transfer. This gives a
bored user something to watch. Implies --verbose if it wasn’t already specified.
While rsync is transferring a regular file, it updates a progress line that looks like this:
782448 63% 110.64kB/s 0:00:04
In this example, the receiver has reconstructed 782448 bytes or 63% of the sender’s file, which is
being reconstructed at a rate of 110.64 kilobytes per second, and the transfer will finish in 4
seconds if the current rate is maintained until the end.
These statistics can be misleading if rsync’s delta-transfer algorithm is in use. For example, if
the sender’s file consists of the basis file followed by additional data, the reported rate will
probably drop dramatically when the receiver gets to the literal data, and the transfer will
probably take much longer to finish than the receiver estimated as it was finishing the matched
part of the file.
When the file transfer finishes, rsync replaces the progress line with a summary line that looks
like this:
1238099 100% 146.38kB/s 0:00:08 (xfer#5, to-check=169/396)
In this example, the file was 1238099 bytes long in total, the average rate of transfer for the
whole file was 146.38 kilobytes per second over the 8 seconds that it took to complete, it was the
5th transfer of a regular file during the current rsync session, and there are 169 more files for
the receiver to check (to see if they are up-to-date or not) remaining out of the 396 total files
in the file-list.
|
-a, --archive
This is equivalent to -rlptgoD. It is a quick way of saying you want recursion and want to
preserve almost everything (with -H being a notable omission). The only exception to the above
equivalence is when --files-from is specified, in which case -r is not implied.
Note that -a does not preserve hardlinks, because finding multiply-linked files is expensive. You
must separately specify -H.
|
-v, --verbose
This option increases the amount of information you are given during the transfer. By default,
rsync works silently. A single -v will give you information about what files are being transferred
and a brief summary at the end. Two -v options will give you information on what files are being
skipped and slightly more information at the end. More than two -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 --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 -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 --itemize-changes or
adding "%i" to the --out-format setting), the output (on the client) increases to mention all
items that are changed in any way. See the --out-format option for more details.
|
-r, --recursive
This tells rsync to copy directories recursively. See also --dirs (-d).
Beginning with rsync 3.0.0, the recursive algorithm used is now an incremental scan that uses much
less memory than before and begins the transfer after the scanning of the first few directories
have been completed. This incremental scan only affects our recursion algorithm, and does not
change a non-recursive transfer. It is also only possible when both ends of the transfer are at
least version 3.0.0.
Some options require rsync to know the full file list, so these options disable the incremental
recursion mode. These include: --delete-before, --delete-after, --prune-empty-dirs, and
--delay-updates. Because of this, the default delete mode when you specify --delete is now
--delete-during when both ends of the connection are at least 3.0.0 (use --del or --delete-during
to request this improved deletion mode explicitly). See also the --delete-delay option that is a
better choice than using --delete-after.
Incremental recursion can be disabled using the --no-inc-recursive option or its shorter --no-i-r
alias.
|
-e, --rsh=COMMAND
This option allows you to choose an alternative remote shell program to use for communication
between the local and remote copies of rsync. Typically, rsync is configured to use ssh by
default, but you may prefer to use rsh on a local network.
If this option is used with [user@]host::module/path, then the remote shell COMMAND will be used
to run an rsync daemon on the remote host, and all data will be transmitted through that remote
shell connection, rather than through a direct socket connection to a running rsync daemon on the
remote host. See the section "USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" above.
Command-line arguments are permitted in COMMAND provided that COMMAND is presented to rsync as a
single argument. You must use spaces (not tabs or other whitespace) to separate the command and
args from each other, and you can use single- and/or double-quotes to preserve spaces in an
argument (but not backslashes). Note that doubling a single-quote inside a single-quoted string
gives you a single-quote; likewise for double-quotes (though you need to pay attention to which
quotes your shell is parsing and which quotes rsync is parsing). Some examples:
-e 'ssh -p 2234'
-e 'ssh -o "ProxyCommand nohup ssh firewall nc -w1 %h %p"'
(Note that ssh users can alternately customize site-specific connect options in their .ssh/config
file.)
You can also choose the remote shell program using the RSYNC_RSH environment variable, which
accepts the same range of values as -e.
See also the --blocking-io option which is affected by this option.
|