rsync.1

Rsync 3.0.5 source code

print the rsync version number and exit.
.IP 
.IP "\fB\-v, \-\-verbose\fP"
This option increases the amount of information you
are given during the transfer.  By default, rsync works silently. A
single \fB\-v\fP will give you information about what files are being
transferred and a brief summary at the end. Two \fB\-v\fP options will give you
information on what files are being skipped and slightly more
information at the end. More than two \fB\-v\fP options should only be used if
you are debugging rsync.
.IP 
Note that the names of the transferred files that are output are done using
a default \fB\-\-out\-format\fP of \(lq%n%L\(rq, which tells you just the name of the
file and, if the item is a link, where it points.  At the single \fB\-v\fP
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
\fB\-\-itemize\-changes\fP or adding \(lq%i\(rq to the \fB\-\-out\-format\fP setting), the
output (on the client) increases to mention all items that are changed in
any way.  See the \fB\-\-out\-format\fP option for more details.
.IP 
.IP "\fB\-q, \-\-quiet\fP"
This option decreases the amount of information you
are given during the transfer, notably suppressing information messages
from the remote server. This option is useful when invoking rsync from
cron.
.IP 
.IP "\fB\-\-no\-motd\fP"
This option affects the information that is output
by the client at the start of a daemon transfer.  This suppresses the
message-of-the-day (MOTD) text, but it also affects the list of modules
that the daemon sends in response to the \(lqrsync host::\(rq request (due to
a limitation in the rsync protocol), so omit this option if you want to
request the list of modules from the daemon.
.IP 
.IP "\fB\-I, \-\-ignore\-times\fP"
Normally rsync will skip any files that are
already the same size and have the same modification timestamp.
This option turns off this \(lqquick check\(rq behavior, causing all files to
be updated.
.IP 
.IP "\fB\-\-size\-only\fP"
This modifies rsync's \(lqquick check\(rq algorithm for
finding files that need to be transferred, changing it from the default of
transferring files with either a changed size or a changed last-modified
time to just looking for files that have changed in size.  This is useful
when starting to use rsync after using another mirroring system which may
not preserve timestamps exactly.
.IP 
.IP "\fB\-\-modify\-window\fP"
When comparing two timestamps, rsync treats the
timestamps as being equal if they differ by no more than the modify-window
value.  This is normally 0 (for an exact match), but you may find it useful
to set this to a larger value in some situations.  In particular, when
transferring to or from an MS Windows FAT filesystem (which represents
times with a 2-second resolution), \fB\-\-modify\-window=1\fP is useful
(allowing times to differ by up to 1 second).
.IP 
.IP "\fB\-c, \-\-checksum\fP"
This changes the way rsync checks if the files have
been changed and are in need of a transfer.  Without this option, rsync
uses a \(lqquick check\(rq that (by default) checks if each file's size and time
of last modification match between the sender and receiver.  This option
changes this to compare a 128-bit MD4 checksum for each file that has a
matching size.  Generating the checksums means that both sides will expend
a lot of disk I/O reading all the data in the files in the transfer (and
this is prior to any reading that will be done to transfer changed files),
so this can slow things down significantly.
.IP 
The sending side generates its checksums while it is doing the file-system
scan that builds the list of the available files.  The receiver generates
its checksums when it is scanning for changed files, and will checksum any
file that has the same size as the corresponding sender's file:  files with
either a changed size or a changed checksum are selected for transfer.
.IP 
Note that rsync always verifies that each \fItransferred\fP file was
correctly reconstructed on the receiving side by checking a whole-file
checksum that is generated as the file is transferred, but that
automatic after-the-transfer verification has nothing to do with this
option's before-the-transfer \(lqDoes this file need to be updated?\(rq check.
.IP 
.IP "\fB\-a, \-\-archive\fP"
This is equivalent to \fB\-rlptgoD\fP. 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 \fB\-\-files\-from\fP is
specified, in which case \fB\-r\fP is not implied.
.IP 
Note that \fB\-a\fP \fBdoes not preserve hardlinks\fP, because
finding multiply-linked files is expensive.  You must separately
specify \fB\-H\fP.
.IP 
.IP "\-\-no\-OPTION"
You may turn off one or more implied options by prefixing
the option name with \(lqno\-\(rq.  Not all options may be prefixed with a \(lqno\-\(rq:
only options that are implied by other options (e.g. \fB\-\-no\-D\fP,
\fB\-\-no\-perms\fP) or have different defaults in various circumstances
(e.g. \fB\-\-no\-whole\-file\fP, \fB\-\-no\-blocking\-io\fP, \fB\-\-no\-dirs\fP).  You may
specify either the short or the long option name after the \(lqno\-\(rq prefix
(e.g. \fB\-\-no\-R\fP is the same as \fB\-\-no\-relative\fP).
.IP 
For example: if you want to use \fB\-a\fP (\fB\-\-archive\fP) but don't want
\fB\-o\fP (\fB\-\-owner\fP), instead of converting \fB\-a\fP into \fB\-rlptgD\fP, you
could specify \fB\-a \-\-no\-o\fP (or \fB\-a \-\-no\-owner\fP).
.IP 
The order of the options is important:  if you specify \fB\-\-no\-r \-a\fP, the
\fB\-r\fP option would end up being turned on, the opposite of \fB\-a \-\-no\-r\fP.
Note also that the side-effects of the \fB\-\-files\-from\fP option are NOT
positional, as it affects the default state of several options and slightly
changes the meaning of \fB\-a\fP (see the \fB\-\-files\-from\fP option for more
details).
.IP 
.IP "\fB\-r, \-\-recursive\fP"
This tells rsync to copy directories
recursively.  See also \fB\-\-dirs\fP (\fB\-d\fP).
.IP 
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.
.IP 
Some options require rsync to know the full file list, so these options
disable the incremental recursion mode.  These include: \fB\-\-delete\-before\fP,
\fB\-\-delete\-after\fP, \fB\-\-prune\-empty\-dirs\fP, and \fB\-\-delay\-updates\fP.
Because of this, the default delete mode when you specify \fB\-\-delete\fP is now
\fB\-\-delete\-during\fP when both ends of the connection are at least 3.0.0
(use \fB\-\-del\fP or \fB\-\-delete\-during\fP to request this improved deletion mode
explicitly).  See also the \fB\-\-delete\-delay\fP option that is a better choice
than using \fB\-\-delete\-after\fP.
.IP 
Incremental recursion can be disabled using the \fB\-\-no\-inc\-recursive\fP
option or its shorter \fB\-\-no\-i\-r\fP alias.
.IP 
.IP "\fB\-R, \-\-relative\fP"
Use relative paths. This means that the full path
names specified on the command line are sent to the server rather than
just the last parts of the filenames. This is particularly useful when
you want to send several different directories at the same time. For
example, if you used this command:
.IP 
.RS 
\f(CW   rsync \-av /foo/bar/baz.c remote:/tmp/\fP
.RE

.IP 
\&... this would create a file named baz.c in /tmp/ on the remote
machine. If instead you used
.IP 
.RS 
\f(CW   rsync \-avR /foo/bar/baz.c remote:/tmp/\fP
.RE

.IP 
then a file named /tmp/foo/bar/baz.c would be created on the remote
machine, preserving its full path.  These extra path elements are called
\(lqimplied directories\(rq (i.e. the \(lqfoo\(rq and the \(lqfoo/bar\(rq directories in the
above example).
.IP 
Beginning with rsync 3.0.0, rsync always sends these implied directories as
real directories in the file list, even if a path element is really a
symlink on the sending side.  This prevents some really unexpected
behaviors when copying the full path of a file that you didn't realize had
a symlink in its path.  If you want to duplicate a server-side symlink,
include both the symlink via its path, and referent directory via its real
path.  If you're dealing with an older rsync on the sending side, you may
need to use the \fB\-\-no\-implied\-dirs\fP option.
.IP 
It is also possible to limit the amount of path information that is sent as
implied directories for each path you specify.  With a modern rsync on the
sending side (beginning with 2.6.7), you can insert a dot and a slash into
the source path, like this:
.IP 
.RS 
\f(CW   rsync \-avR /foo/./bar/baz.c remote:/tmp/\fP
.RE

.IP 
That would create /tmp/bar/baz.c on the remote machine.  (Note that the
dot must be followed by a slash, so \(lq/foo/.\(rq would not be abbreviated.)
(2) For older rsync versions, you would need to use a chdir to limit the
source path.  For example, when pushing files:
.IP 
.RS 
\f(CW   (cd /foo; rsync \-avR bar/baz.c remote:/tmp/) \fP
.RE

.IP 
(Note that the parens put the two commands into a sub-shell, so that the
\(lqcd\(rq command doesn't remain in effect for future commands.)
If you're pulling files from an older rsync, use this idiom (but only
for a non-daemon transfer):
.IP 
.RS 
\f(CW   rsync \-avR \-\-rsync\-path="cd /foo; rsync" \e \fP
.br 
\f(CW       remote:bar/baz.c /tmp/\fP
.RE

.IP 
.IP "\fB\-\-no\-implied\-dirs\fP"
This option affects the default behavior of the
\fB\-\-relative\fP option.  When it is specified, the attributes of the implied
directories from the source names are not included in the transfer.  This
means that the corresponding path elements on the destination system are
left unchanged if they exist, and any missing implied directories are
created with default attributes.  This even allows these implied path
elements to have big differences, such as being a symlink to a directory on
the receiving side.
.IP 
For instance, if a command-line arg or a files-from entry told rsync to
transfer the file \(lqpath/foo/file\(rq, the directories \(lqpath\(rq and \(lqpath/foo\(rq
are implied when \fB\-\-relative\fP is used.  If \(lqpath/foo\(rq is a symlink to
\(lqbar\(rq on the destination system, the receiving rsync would ordinarily
delete \(lqpath/foo\(rq, recreate it as a directory, and receive the file into
the new directory.  With \fB\-\-no\-implied\-dirs\fP, the receiving rsync updates
\(lqpath/foo/file\(rq using the existing path elements, which means that the file
ends up being created in \(lqpath/bar\(rq.  Another way to accomplish this link
preservation is to use the \fB\-\-keep\-dirlinks\fP option (which will also
affect symlinks to directories in the rest of the transfer).
.IP 
When pulling files from an rsync older than 3.0.0, you may need to use this
option if the sending side has a symlink in the path you request and you
wish the implied directories to be transferred as normal directories.
.IP 
.IP "\fB\-b, \-\-backup\fP"
With this option, preexisting destination files are
renamed as each file is transferred or deleted.  You can control where the
backup file goes and what (if any) suffix gets appended using the
\fB\-\-backup\-dir\fP and \fB\-\-suffix\fP options.
.IP 
Note that if you don't specify \fB\-\-backup\-dir\fP, (1) the
\fB\-\-omit\-dir\-times\fP option will be implied, and (2) if \fB\-\-delete\fP is
also in effect (without \fB\-\-delete\-excluded\fP), rsync will add a \(lqprotect\(rq
filter-rule for the backup suffix to the end of all your existing excludes
(e.g. \fB\-f "P *~"\fP).  This will prevent previously backed-up files from being
deleted.  Note that if you are supplying your own filter rules, you may
need to manually insert your own exclude/protect rule somewhere higher up
in the list so that it has a high enough priority to be effective (e.g., if
your rules specify a trailing inclusion/exclusion of \(oq*\(cq, the auto-added
rule would never be reached).
.IP 
.IP "\fB\-\-backup\-dir=DIR\fP"
In combination with the \fB\-\-backup\fP option, this
tells rsync to store all backups in the specified directory on the receiving
side.  This can be used for incremental backups.  You can additionally
specify a backup suffix using the \fB\-\-suffix\fP option
(otherwise the files backed up in the specified directory
will keep their original filenames).
.IP 
.IP "\fB\-\-suffix=SUFFIX\fP"
This option allows you to override the default
backup suffix used with the \fB\-\-backup\fP (\fB\-b\fP) option. The default suffix is a ~
if no \-\fB\-backup-dir\fP was specified, otherwise it is an empty string.
.IP 
.IP "\fB\-u, \-\-update\fP"
This forces rsync to skip any files which exist on
the destination and have a modified time that is newer than the source
file.  (If an existing destination file has a modification time equal to the
source file's, it will be updated if the sizes are different.)
.IP 
Note that this does not affect the copying of symlinks or other special
files.  Also, a difference of file format between the sender and receiver
is always considered to be important enough for an update, no matter what
date is on the objects.  In other words, if the source has a directory
where the destination has a file, the transfer would occur regardless of
the timestamps.
.IP 
.IP "\fB\-\-inplace\fP"
This option changes how rsync transfers a file when the
file's data needs to be updated: instead of the default method of creating
a new copy of the file and moving it into place when it is complete, rsync
instead writes the updated data directly to the destination file.
.IP