rsync.1

Rsync 3.0.5 source code

.IP 
It is also legal to specify multiple \fB\-\-chmod\fP options, as each
additional option is just appended to the list of changes to make.
.IP 
See the \fB\-\-perms\fP and \fB\-\-executability\fP options for how the resulting
permission value can be applied to the files in the transfer.
.IP 
.IP "\fB\-o, \-\-owner\fP"
This option causes rsync to set the owner of the
destination file to be the same as the source file, but only if the
receiving rsync is being run as the super-user (see also the \fB\-\-super\fP
and \fB\-\-fake\-super\fP options).
Without this option, the owner of new and/or transferred files are set to
the invoking user on the receiving side.
.IP 
The preservation of ownership will associate matching names by default, but
may fall back to using the ID number in some circumstances (see also the
\fB\-\-numeric\-ids\fP option for a full discussion).
.IP 
.IP "\fB\-g, \-\-group\fP"
This option causes rsync to set the group of the
destination file to be the same as the source file.  If the receiving
program is not running as the super-user (or if \fB\-\-no\-super\fP was
specified), only groups that the invoking user on the receiving side
is a member of will be preserved.
Without this option, the group is set to the default group of the invoking
user on the receiving side.
.IP 
The preservation of group information will associate matching names by
default, but may fall back to using the ID number in some circumstances
(see also the \fB\-\-numeric\-ids\fP option for a full discussion).
.IP 
.IP "\fB\-\-devices\fP"
This option causes rsync to transfer character and
block device files to the remote system to recreate these devices.
This option has no effect if the receiving rsync is not run as the
super-user (see also the \fB\-\-super\fP and \fB\-\-fake\-super\fP options).
.IP 
.IP "\fB\-\-specials\fP"
This option causes rsync to transfer special files
such as named sockets and fifos.
.IP 
.IP "\fB\-D\fP"
The \fB\-D\fP option is equivalent to \fB\-\-devices\fP \fB\-\-specials\fP.
.IP 
.IP "\fB\-t, \-\-times\fP"
This tells rsync to transfer modification times along
with the files and update them on the remote system.  Note that if this
option is not used, the optimization that excludes files that have not been
modified cannot be effective; in other words, a missing \fB\-t\fP or \fB\-a\fP will
cause the next transfer to behave as if it used \fB\-I\fP, causing all files to be
updated (though rsync's delta-transfer algorithm will make the update fairly efficient
if the files haven't actually changed, you're much better off using \fB\-t\fP).
.IP 
.IP "\fB\-O, \-\-omit\-dir\-times\fP"
This tells rsync to omit directories when
it is preserving modification times (see \fB\-\-times\fP).  If NFS is sharing
the directories on the receiving side, it is a good idea to use \fB\-O\fP.
This option is inferred if you use \fB\-\-backup\fP without \fB\-\-backup\-dir\fP.
.IP 
.IP "\fB\-\-super\fP"
This tells the receiving side to attempt super-user
activities even if the receiving rsync wasn't run by the super-user.  These
activities include: preserving users via the \fB\-\-owner\fP option, preserving
all groups (not just the current user's groups) via the \fB\-\-groups\fP
option, and copying devices via the \fB\-\-devices\fP option.  This is useful
for systems that allow such activities without being the super-user, and
also for ensuring that you will get errors if the receiving side isn't
being running as the super-user.  To turn off super-user activities, the
super-user can use \fB\-\-no\-super\fP.
.IP 
.IP "\fB\-\-fake\-super\fP"
When this option is enabled, rsync simulates
super-user activities by saving/restoring the privileged attributes via
special extended attributes that are attached to each file (as needed).  This
includes the file's owner and group (if it is not the default), the file's
device info (device & special files are created as empty text files), and
any permission bits that we won't allow to be set on the real file (e.g.
the real file gets u-s,g-s,o-t for safety) or that would limit the owner's
access (since the real super-user can always access/change a file, the
files we create can always be accessed/changed by the creating user).
This option also handles ACLs (if \fB\-\-acls\fP was specified) and non-user
extended attributes (if \fB\-\-xattrs\fP was specified).
.IP 
This is a good way to backup data without using a super-user, and to store
ACLs from incompatible systems.
.IP 
The \fB\-\-fake\-super\fP option only affects the side where the option is used.
To affect the remote side of a remote-shell connection, specify an rsync
path:
.IP 
.RS 
\f(CW  rsync \-av \-\-rsync\-path="rsync \-\-fake\-super" /src/ host:/dest/\fP
.RE

.IP 
Since there is only one \(lqside\(rq in a local copy, this option affects both
the sending and receiving of files.  You'll need to specify a copy using
\(lqlocalhost\(rq if you need to avoid this, possibly using the \(lqlsh\(rq shell
script (from the support directory) as a substitute for an actual remote
shell (see \fB\-\-rsh\fP).
.IP 
This option is overridden by both \fB\-\-super\fP and \fB\-\-no\-super\fP.
.IP 
See also the \(lqfake super\(rq setting in the daemon's rsyncd.conf file.
.IP 
.IP "\fB\-S, \-\-sparse\fP"
Try to handle sparse files efficiently so they take
up less space on the destination.  Conflicts with \fB\-\-inplace\fP because it's
not possible to overwrite data in a sparse fashion.
.IP 
NOTE: Don't use this option when the destination is a Solaris \(lqtmpfs\(rq
filesystem. It doesn't seem to handle seeks over null regions
correctly and ends up corrupting the files.
.IP 
.IP "\fB\-n, \-\-dry\-run\fP"
This makes rsync perform a trial run that doesn't
make any changes (and produces mostly the same output as a real run).  It
is most commonly used in combination with the \fB\-v, \-\-verbose\fP and/or
\fB\-i, \-\-itemize\-changes\fP options to see what an rsync command is going
to do before one actually runs it.
.IP 
The output of \fB\-\-itemize\-changes\fP is supposed to be exactly the same on a
dry run and a subsequent real run (barring intentional trickery and system
call failures); if it isn't, that's a bug.  Other output is the same to the
extent practical, but may differ in some areas.  Notably, a dry run does not
send the actual data for file transfers, so \fB\-\-progress\fP has no effect,
the \(lqbytes sent\(rq, \(lqbytes received\(rq, \(lqliteral data\(rq, and \(lqmatched data\(rq
statistics are too small, and the \(lqspeedup\(rq value is equivalent to a run
where no file transfers are needed.
.IP 
.IP "\fB\-W, \-\-whole\-file\fP"
With this option rsync's delta-transfer algorithm
is not used and the whole file is sent as-is instead.  The transfer may be
faster if this option is used when the bandwidth between the source and
destination machines is higher than the bandwidth to disk (especially when the
\(lqdisk\(rq is actually a networked filesystem).  This is the default when both
the source and destination are specified as local paths.
.IP 
.IP "\fB\-x, \-\-one\-file\-system\fP"
This tells rsync to avoid crossing a
filesystem boundary when recursing.  This does not limit the user's ability
to specify items to copy from multiple filesystems, just rsync's recursion
through the hierarchy of each directory that the user specified, and also
the analogous recursion on the receiving side during deletion.  Also keep
in mind that rsync treats a \(lqbind\(rq mount to the same device as being on the
same filesystem.
.IP 
If this option is repeated, rsync omits all mount-point directories from
the copy.  Otherwise, it includes an empty directory at each mount-point it
encounters (using the attributes of the mounted directory because those of
the underlying mount-point directory are inaccessible).
.IP 
If rsync has been told to collapse symlinks (via \fB\-\-copy\-links\fP or
\fB\-\-copy\-unsafe\-links\fP), a symlink to a directory on another device is
treated like a mount-point.  Symlinks to non-directories are unaffected
by this option.
.IP 
.IP "\fB\-\-existing, \-\-ignore\-non\-existing\fP"
This tells rsync to skip
creating files (including directories) that do not exist
yet on the destination.  If this option is
combined with the \fB\-\-ignore\-existing\fP option, no files will be updated
(which can be useful if all you want to do is delete extraneous files).
.IP 
.IP "\fB\-\-ignore\-existing\fP"
This tells rsync to skip updating files that
already exist on the destination (this does \fInot\fP ignore existing
directories, or nothing would get done).  See also \fB\-\-existing\fP.
.IP 
This option can be useful for those doing backups using the \fB\-\-link\-dest\fP
option when they need to continue a backup run that got interrupted.  Since
a \fB\-\-link\-dest\fP run is copied into a new directory hierarchy (when it is
used properly), using \fB\-\-ignore existing\fP 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.
.IP 
.IP "\fB\-\-remove\-source\-files\fP"
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.
.IP 
.IP "\fB\-\-delete\fP"
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. \(lqdir\(rq or \(lqdir/\(rq) without using a wildcard
for the directory's contents (e.g. \(lqdir/*\(rq) 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 \fB\-\-delete\-excluded\fP
option or mark the rules as only matching on the sending side (see the
include/exclude modifiers in the FILTER RULES section).
.IP 
Prior to rsync 2.6.7, this option would have no effect unless \fB\-\-recursive\fP
was enabled.  Beginning with 2.6.7, deletions will also occur when \fB\-\-dirs\fP
(\fB\-d\fP) is enabled, but only for directories whose contents are being copied.
.IP 
This option can be dangerous if used incorrectly!  It is a very good idea to
first try a run using the \fB\-\-dry\-run\fP option (\fB\-n\fP) to see what files are
going to be deleted.
.IP 
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 causing a massive deletion of files on the
destination.  You can override this with the \fB\-\-ignore\-errors\fP option.
.IP 
The \fB\-\-delete\fP option may be combined with one of the \-\-delete\-WHEN options
without conflict, as well as \fB\-\-delete\-excluded\fP.  However, if none of the
\-\-delete\-WHEN options are specified, rsync will choose the
\fB\-\-delete\-during\fP algorithm when talking to rsync 3.0.0 or newer, and
the \fB\-\-delete\-before\fP algorithm when talking to an older rsync.  See also
\fB\-\-delete\-delay\fP and \fB\-\-delete\-after\fP.
.IP 
.IP "\fB\-\-delete\-before\fP"
Request that the file-deletions on the receiving
side be done before the transfer starts.
See \fB\-\-delete\fP (which is implied) for more details on file-deletion.
.IP 
Deleting before the transfer is helpful if the filesystem is tight for space
and removing extraneous files would help to make the transfer possible.
However, it does introduce a delay before the start of the transfer,
and this delay might cause the transfer to timeout (if \fB\-\-timeout\fP was
specified).  It also forces rsync to use the old, non-incremental recursion
algorithm that requires rsync to scan all the files in the transfer into
memory at once (see \fB\-\-recursive\fP).
.IP 
.IP "\fB\-\-delete\-during, \-\-del\fP"
Request that the file-deletions on the
receiving side be done incrementally as the transfer happens.  The
per-directory delete scan is done right before each directory is checked
for updates, so it behaves like a more efficient \fB\-\-delete\-before\fP,
including doing the deletions prior to any per-directory filter files
being updated.  This option was first added in rsync version 2.6.4.
See \fB\-\-delete\fP (which is implied) for more details on file-deletion.
.IP 
.IP "\fB\-\-delete\-delay\fP"
Request that the file-deletions on the receiving
side be computed during the transfer (like \fB\-\-delete\-during\fP), and then
removed after the transfer completes.  This is useful when combined with
\fB\-\-delay\-updates\fP and/or \fB\-\-fuzzy\fP, and is more efficient than using
\fB\-\-delete\-after\fP (but can behave differently, since \fB\-\-delete\-after\fP
computes the deletions in a separate pass after all updates are done).
If the number of removed files overflows an internal buffer, a
temporary file will be created on the receiving side to hold the names (it
is removed while open, so you shouldn't see it during the transfer).  If
the creation of the temporary file fails, rsync will try to fall back to
using \fB\-\-delete\-after\fP (which it cannot do if \fB\-\-recursive\fP is doing an
incremental scan).
See \fB\-\-delete\fP (which is implied) for more details on file-deletion.
.IP 
.IP "\fB\-\-delete\-after\fP"
Request that the file-deletions on the receiving
side be done after the transfer has completed.  This is useful if you
are sending new per-directory merge files as a part of the transfer and
you want their exclusions to take effect for the delete phase of the
current transfer.  It also forces rsync to use the old, non-incremental
recursion algorithm that requires rsync to scan all the files in the
transfer into memory at once (see \fB\-\-recursive\fP).
See \fB\-\-delete\fP (which is implied) for more details on file-deletion.
.IP 
.IP "\fB\-\-delete\-excluded\fP"
In addition to deleting the files on the
receiving side that are not on the sending side, this tells rsync to also
delete any files on the receiving side that are excluded (see \fB\-\-exclude\fP).
See the FILTER RULES section for a way to make individual exclusions behave
this way on the receiver, and for a way to protect files from
\fB\-\-delete\-excluded\fP.
See \fB\-