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.
|
-i, --itemize-changes
Requests a simple itemized list of the changes that are being made to each file, including
attribute changes. This is exactly the same as specifying --out-format='%i %n%L'. If you repeat
the option, unchanged files will also be output, but only if the receiving rsync is at least
version 2.6.7 (you can use -vv with older versions of rsync, but that also turns on the output of
other verbose messages).
The "%i" escape has a cryptic output that is 11 letters long. The general format is like the
string YXcstpoguax, where Y is replaced by the type of update being done, X is replaced by the
file-type, and the other letters represent attributes that may be output if they are being
modified.
The update types that replace the Y are as follows:
o A < means that a file is being transferred to the remote host (sent).
o A > means that a file is being transferred to the local host (received).
o A c means that a local change/creation is occurring for the item (such as the creation of a
directory or the changing of a symlink, etc.).
o A h means that the item is a hard link to another item (requires --hard-links).
o A . means that the item is not being updated (though it might have attributes that are
being modified).
o A * means that the rest of the itemized-output area contains a message (e.g. "deleting").
The file-types that replace the X are: f for a file, a d for a directory, an L for a symlink, a D
for a device, and a S for a special file (e.g. named sockets and fifos).
The other letters in the string above are the actual letters that will be output if the associated
attribute for the item is being updated or a "." for no change. Three exceptions to this are: (1)
a newly created item replaces each letter with a "+", (2) an identical item replaces the dots with
spaces, and (3) an unknown attribute replaces each letter with a "?" (this can happen when talking
to an older rsync).
The attribute that is associated with each letter is as follows:
o A c means either that a regular file has a different checksum (requires --checksum) or that
a symlink, device, or special file has a changed value. Note that if you are sending files
to an rsync prior to 3.0.1, this change flag will be present only for checksum-differing
regular files.
o A s means the size of a regular file is different and will be updated by the file transfer.
o A t means the modification time is different and is being updated to the sender’s value
(requires --times). An alternate value of T means that the modification time will be set
to the transfer time, which happens when a file/symlink/device is updated without --times
and when a symlink is changed and the receiver can’t set its time. (Note: when using an
rsync 3.0.0 client, you might see the s flag combined with t instead of the proper T flag
for this time-setting failure.)
o A p means the permissions are different and are being updated to the sender’s value
(requires --perms).
o An o means the owner is different and is being updated to the sender’s value (requires
--owner and super-user privileges).
o A g means the group is different and is being updated to the sender’s value (requires
--group and the authority to set the group).
o The u slot is reserved for future use.
o The a means that the ACL information changed.
o The x means that the extended attribute information changed.
One other output is possible: when deleting files, the "%i" will output the string "*deleting"
for each item that is being removed (assuming that you are talking to a recent enough rsync that
it logs deletions instead of outputting them as a verbose message).
|
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).
|
--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.
|
-s, --protect-args
This option sends all filenames and most options to the remote rsync without allowing the remote
shell to interpret them. This means that spaces are not split in names, and any non-wildcard
special characters are not translated (such as ~, $, ;, &, etc.). Wildcards are expanded on the
remote host by rsync (instead of the shell doing it).
If you use this option with --iconv, the args related to the remote side will also be translated
from the local to the remote character-set. The translation happens before wild-cards are
expanded. See also the --files-from option.
|