a fast, versatile, remote (and local) file-copying tool
|
-h, --human-readable
Output numbers in a more human-readable format. This makes big numbers output using larger units,
with a K, M, or G suffix. If this option was specified once, these units are K (1000), M
(1000*1000), and G (1000*1000*1000); if the option is repeated, the units are powers of 1024
instead of 1000.
|
-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.
|
-z, --compress
With this option, rsync compresses the file data 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 because it takes advantage of the implicit
information in the matching data blocks that are not explicitly sent over the connection.
See the --skip-compress option for the default list of file suffixes that will not be compressed.
|
-P The -P option is equivalent to --partial --progress. Its purpose is to make it much easier to
specify these two options for a long transfer that may be interrupted.
|
-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.
|
Local: rsync [OPTION...] SRC... [DEST]
Access via remote shell:
Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
Push: rsync [OPTION...] SRC... [USER@]HOST:DEST
Access via rsync daemon:
Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST
|
--remove-source-files
This tells rsync to remove from the sending side the files (meaning non-directories) that are a
part of the transfer and have been successfully duplicated on the receiving side.
Note that you should only use this option on source files that are quiescent. If you are using
this to move files that show up in a particular directory over to another host, make sure that the
finished files get renamed into the source directory, not directly written into it, so that rsync
can’t possibly transfer a file that is not yet fully written. If you can’t first write the files
into a different directory, you should use a naming idiom that lets rsync avoid transferring files
that are not yet finished (e.g. name the file "foo.new" when it is written, rename it to "foo"
when it is done, and then use the option --exclude='*.new' for the rsync transfer).
|
--exclude=PATTERN
This option is a simplified form of the --filter option that defaults to an exclude rule and does
not allow the full rule-parsing syntax of normal filter rules.
See the FILTER RULES section for detailed information on this option.
|
--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.
The current statistics are as follows:
o Number of files is the count of all "files" (in the generic sense), which includes
directories, symlinks, etc.
o Number of files transferred is the count of normal files that were updated via rsync’s
delta-transfer algorithm, which does not include created dirs, symlinks, etc.
o Total file size is the total sum of all file sizes in the transfer. This does not count
any size for directories or special files, but does include the size of symlinks.
o Total transferred file size is the total sum of all files sizes for just the transferred
files.
o Literal data is how much unmatched file-update data we had to send to the receiver for it
to recreate the updated files.
o Matched data is how much data the receiver got locally when recreating the updated files.
o File list size is how big the file-list data was when the sender sent it to the receiver.
This is smaller than the in-memory size for the file list due to some compressing of
duplicated data when rsync sends the list.
o File list generation time is the number of seconds that the sender spent creating the file
list. This requires a modern rsync on the sending side for this to be present.
o File list transfer time is the number of seconds that the sender spent sending the file
list to the receiver.
o Total bytes sent is the count of all the bytes that rsync sent from the client side to the
server side.
o Total bytes received is the count of all non-message bytes that rsync received by the
client side from the server side. "Non-message" bytes means that we don’t count the bytes
for a verbose message that the server sent to us, which makes the stats more consistent.
|
Pipelines
A pipeline is a sequence of one or more commands separated by one of the control operators | or |&. The
format for a pipeline is:
[time [-p]] [ ! ] command [ [|⎪|&] command2 ... ]
The standard output of command is connected via a pipe to the standard input of command2. This
connection is performed before any redirections specified by the command (see REDIRECTION below). If |&
is used, the standard error of command is connected to command2's standard input through the pipe; it is
shorthand for 2>&1 |. This implicit redirection of the standard error is performed after any
redirections specified by the command.
The return status of a pipeline is the exit status of the last command, unless the pipefail option is
enabled. If pipefail is enabled, the pipeline's return status is the value of the last (rightmost)
command to exit with a non-zero status, or zero if all commands exit successfully. If the reserved word
! precedes a pipeline, the exit status of that pipeline is the logical negation of the exit status as
described above. The shell waits for all commands in the pipeline to terminate before returning a value.
If the time reserved word precedes a pipeline, the elapsed as well as user and system time consumed by
its execution are reported when the pipeline terminates. The -p option changes the output format to that
specified by POSIX. When the shell is in posix mode, it does not recognize time as a reserved word if
the next token begins with a `-'. The TIMEFORMAT variable may be set to a format string that specifies
how the timing information should be displayed; see the description of TIMEFORMAT under Shell Variables
below.
When the shell is in posix mode, time may be followed by a newline. In this case, the shell displays the
total user and system time consumed by the shell and its children. The TIMEFORMAT variable may be used
to specify the format of the time information.
Each command in a pipeline is executed as a separate process (i.e., in a subshell).
|
process mail messages
|
-s, --subject=SUBJ
send a message with the given SUBJECT
|