a fast, versatile, remote (and local) file-copying tool
|
--ignore-existing
This tells rsync to skip updating files that already exist on the destination (this does not
ignore existing directories, or nothing would get done). See also --existing.
This option is a transfer rule, not an exclude, so it doesn’t affect the data that goes into the
file-lists, and thus it doesn’t affect deletions. It just limits the files that the receiver
requests to be transferred.
This option can be useful for those doing backups using the --link-dest option when they need to
continue a backup run that got interrupted. Since a --link-dest run is copied into a new
directory hierarchy (when it is used properly), using --ignore existing will ensure that the
already-handled files don’t get tweaked (which avoids a change in permissions on the hard-linked
files). This does mean that this option is only looking at the existing files in the destination
hierarchy itself.
|
-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.
|
-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.
|
--delete
This tells rsync to delete extraneous files from the receiving side (ones that aren’t on the
sending side), but only for the directories that are being synchronized. You must have asked
rsync to send the whole directory (e.g. "dir" or "dir/") without using a wildcard for the
directory’s contents (e.g. "dir/*") since the wildcard is expanded by the shell and rsync thus
gets a request to transfer individual files, not the files’ parent directory. Files that are
excluded from the transfer are also excluded from being deleted unless you use the
--delete-excluded option or mark the rules as only matching on the sending side (see the
include/exclude modifiers in the FILTER RULES section).
Prior to rsync 2.6.7, this option would have no effect unless --recursive was enabled. Beginning
with 2.6.7, deletions will also occur when --dirs (-d) is enabled, but only for directories whose
contents are being copied.
This option can be dangerous if used incorrectly! It is a very good idea to first try a run using
the --dry-run option (-n) to see what files are going to be deleted.
If the sending side detects any I/O errors, then the deletion of any files at the destination will
be automatically disabled. This is to prevent temporary filesystem failures (such as NFS errors)
on the sending side from causing a massive deletion of files on the destination. You can override
this with the --ignore-errors option.
The --delete option may be combined with one of the --delete-WHEN options without conflict, as
well as --delete-excluded. However, if none of the --delete-WHEN options are specified, rsync
will choose the --delete-during algorithm when talking to rsync 3.0.0 or newer, and the
--delete-before algorithm when talking to an older rsync. See also --delete-delay and
--delete-after.
|
--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.
|
-f, --filter=RULE
This option allows you to add rules to selectively exclude certain files from the list of files to
be transferred. This is most useful in combination with a recursive transfer.
You may use as many --filter options on the command line as you like to build up the list of files
to exclude. If the filter contains whitespace, be sure to quote it so that the shell gives the
rule to rsync as a single argument. The text below also mentions that you can use an underscore
to replace the space that separates a rule from its arg.
See the FILTER RULES section for detailed information on 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
|