rsync.1

Rsync 3.0.5 source code

This has several effects: (1) in-use binaries cannot be updated (either the
OS will prevent this from happening, or binaries that attempt to swap-in
their data will misbehave or crash), (2) the file's data will be in an
inconsistent state during the transfer, (3) a file's data may be left in an
inconsistent state after the transfer if the transfer is interrupted or if
an update fails, (4) a file that does not have write permissions can not be
updated, and (5) the efficiency of rsync's delta-transfer algorithm may be
reduced if some data in the destination file is overwritten before it can
be copied to a position later in the file (one exception to this is if you
combine this option with \fB\-\-backup\fP, since rsync is smart enough to use
the backup file as the basis file for the transfer).
.IP 
WARNING: you should not use this option to update files that are being
accessed by others, so be careful when choosing to use this for a copy.
.IP 
This option is useful for transfer of large files with block-based changes
or appended data, and also on systems that are disk bound, not network
bound.
.IP 
The option implies \fB\-\-partial\fP (since an interrupted transfer does not delete
the file), but conflicts with \fB\-\-partial\-dir\fP and \fB\-\-delay\-updates\fP.
Prior to rsync 2.6.4 \fB\-\-inplace\fP was also incompatible with \fB\-\-compare\-dest\fP
and \fB\-\-link\-dest\fP.
.IP 
.IP "\fB\-\-append\fP"
This causes rsync to update a file by appending data onto
the end of the file, which presumes that the data that already exists on
the receiving side is identical with the start of the file on the sending
side.  If a file needs to be transferred and its size on the receiver is
the same or longer than the size on the sender, the file is skipped.  This
does not interfere with the updating of a file's non-content attributes
(e.g. permissions, ownership, etc.) when the file does not need to be
transferred, nor does it affect the updating of any non-regular files.
Implies \fB\-\-inplace\fP,
but does not conflict with \fB\-\-sparse\fP (since it is always extending a
file's length).
.IP 
.IP "\fB\-\-append\-verify\fP"
This works just like the \fB\-\-append\fP option, but
the existing data on the receiving side is included in the full-file
checksum verification step, which will cause a file to be resent if the
final verification step fails (rsync uses a normal, non-appending
\fB\-\-inplace\fP transfer for the resend).
.IP 
Note: prior to rsync 3.0.0, the \fB\-\-append\fP option worked like
\fB\-\-append\-verify\fP, so if you are interacting with an older rsync (or the
transfer is using a protocol prior to 30), specifying either append option
will initiate an \fB\-\-append\-verify\fP transfer.
.IP 
.IP "\fB\-d, \-\-dirs\fP"
Tell the sending side to include any directories that
are encountered.  Unlike \fB\-\-recursive\fP, a directory's contents are not copied
unless the directory name specified is \(lq.\(rq or ends with a trailing slash
(e.g. \(lq.\(rq, \(lqdir/.\(rq, \(lqdir/\(rq, etc.).  Without this option or the
\fB\-\-recursive\fP option, rsync will skip all directories it encounters (and
output a message to that effect for each one).  If you specify both
\fB\-\-dirs\fP and \fB\-\-recursive\fP, \fB\-\-recursive\fP takes precedence.
.IP 
The \fB\-\-dirs\fP option is implied by the \fB\-\-files\-from\fP option
or the \fB\-\-list\-only\fP option (including an implied
\fB\-\-list\-only\fP usage) if \fB\-\-recursive\fP wasn't specified (so that
directories are seen in the listing).  Specify \fB\-\-no\-dirs\fP (or \fB\-\-no\-d\fP)
if you want to turn this off.
.IP 
There is also a backward-compatibility helper option, \fB\-\-old\-dirs\fP (or
\fB\-\-old\-d\fP) that tells rsync to use a hack of \(lq\-r \-\-exclude='/*/*'\(rq to get
an older rsync to list a single directory without recursing.
.IP 
.IP "\fB\-l, \-\-links\fP"
When symlinks are encountered, recreate the
symlink on the destination.
.IP 
.IP "\fB\-L, \-\-copy\-links\fP"
When symlinks are encountered, the item that
they point to (the referent) is copied, rather than the symlink.  In older
versions of rsync, this option also had the side-effect of telling the
receiving side to follow symlinks, such as symlinks to directories.  In a
modern rsync such as this one, you'll need to specify \fB\-\-keep\-dirlinks\fP (\fB\-K\fP)
to get this extra behavior.  The only exception is when sending files to
an rsync that is too old to understand \fB\-K\fP \(em in that case, the \fB\-L\fP option
will still have the side-effect of \fB\-K\fP on that older receiving rsync.
.IP 
.IP "\fB\-\-copy\-unsafe\-links\fP"
This tells rsync to copy the referent of
symbolic links that point outside the copied tree.  Absolute symlinks
are also treated like ordinary files, and so are any symlinks in the
source path itself when \fB\-\-relative\fP is used.  This option has no
additional effect if \fB\-\-copy\-links\fP was also specified.
.IP 
.IP "\fB\-\-safe\-links\fP"
This tells rsync to ignore any symbolic links
which point outside the copied tree. All absolute symlinks are
also ignored. Using this option in conjunction with \fB\-\-relative\fP may
give unexpected results.
.IP 
.IP "\fB\-k, \-\-copy\-dirlinks\fP"
This option causes the sending side to treat
a symlink to a directory as though it were a real directory.  This is
useful if you don't want symlinks to non-directories to be affected, as
they would be using \fB\-\-copy\-links\fP.
.IP 
Without this option, if the sending side has replaced a directory with a
symlink to a directory, the receiving side will delete anything that is in
the way of the new symlink, including a directory hierarchy (as long as
\fB\-\-force\fP or \fB\-\-delete\fP is in effect).
.IP 
See also \fB\-\-keep\-dirlinks\fP for an analogous option for the receiving
side.
.IP 
.IP "\fB\-K, \-\-keep\-dirlinks\fP"
This option causes the receiving side to treat
a symlink to a directory as though it were a real directory, but only if it
matches a real directory from the sender.  Without this option, the
receiver's symlink would be deleted and replaced with a real directory.
.IP 
For example, suppose you transfer a directory \(lqfoo\(rq that contains a file
\(lqfile\(rq, but \(lqfoo\(rq is a symlink to directory \(lqbar\(rq on the receiver.  Without
\fB\-\-keep\-dirlinks\fP, the receiver deletes symlink \(lqfoo\(rq, recreates it as a
directory, and receives the file into the new directory.  With
\fB\-\-keep\-dirlinks\fP, the receiver keeps the symlink and \(lqfile\(rq ends up in
\(lqbar\(rq.
.IP 
One note of caution:  if you use \fB\-\-keep\-dirlinks\fP, you must trust all
the symlinks in the copy!  If it is possible for an untrusted user to
create their own symlink to any directory, the user could then (on a
subsequent copy) replace the symlink with a real directory and affect the
content of whatever directory the symlink references.  For backup copies,
you are better off using something like a bind mount instead of a symlink
to modify your receiving hierarchy.
.IP 
See also \fB\-\-copy\-dirlinks\fP for an analogous option for the sending side.
.IP 
.IP "\fB\-H, \-\-hard\-links\fP"
This tells rsync to look for hard-linked files in
the transfer and link together the corresponding files on the receiving
side.  Without this option, hard-linked files in the transfer are treated
as though they were separate files.
.IP 
When you are updating a non-empty destination, this option only ensures
that files that are hard-linked together on the source are hard-linked
together on the destination.  It does NOT currently endeavor to break
already existing hard links on the destination that do not exist between
the source files.  Note, however, that if one or more extra-linked files
have content changes, they will become unlinked when updated (assuming you
are not using the \fB\-\-inplace\fP option).
.IP 
Note that rsync can only detect hard links between files that are inside
the transfer set.  If rsync updates a file that has extra hard-link
connections to files outside the transfer, that linkage will be broken.  If
you are tempted to use the \fB\-\-inplace\fP option to avoid this breakage, be
very careful that you know how your files are being updated so that you are
certain that no unintended changes happen due to lingering hard links (and
see the \fB\-\-inplace\fP option for more caveats).
.IP 
If incremental recursion is active (see \fB\-\-recursive\fP), rsync may transfer
a missing hard-linked file before it finds that another link for that contents
exists elsewhere in the hierarchy.  This does not affect the accuracy of
the transfer, just its efficiency.  One way to avoid this is to disable
incremental recursion using the \fB\-\-no\-inc\-recursive\fP option.
.IP 
.IP "\fB\-p, \-\-perms\fP"
This option causes the receiving rsync to set the
destination permissions to be the same as the source permissions.  (See
also the \fB\-\-chmod\fP option for a way to modify what rsync considers to
be the source permissions.)
.IP 
When this option is \fIoff\fP, permissions are set as follows:
.IP 
.RS 
.IP o 
Existing files (including updated files) retain their existing
permissions, though the \fB\-\-executability\fP option might change just
the execute permission for the file.
.IP o 
New files get their \(lqnormal\(rq permission bits set to the source
file's permissions masked with the receiving directory's default
permissions (either the receiving process's umask, or the permissions
specified via the destination directory's default ACL), and
their special permission bits disabled except in the case where a new
directory inherits a setgid bit from its parent directory.
.RE

.IP 
Thus, when \fB\-\-perms\fP and \fB\-\-executability\fP are both disabled,
rsync's behavior is the same as that of other file-copy utilities,
such as \fBcp\fP(1) and \fBtar\fP(1).
.IP 
In summary: to give destination files (both old and new) the source
permissions, use \fB\-\-perms\fP.  To give new files the destination-default
permissions (while leaving existing files unchanged), make sure that the
\fB\-\-perms\fP option is off and use \fB\-\-chmod=ugo=rwX\fP (which ensures that
all non-masked bits get enabled).  If you'd care to make this latter
behavior easier to type, you could define a popt alias for it, such as
putting this line in the file ~/.popt (the following defines the \fB\-Z\fP option,
and includes \-\-no\-g to use the default group of the destination dir):
.IP 
.RS 
\f(CW   rsync alias \-Z \-\-no\-p \-\-no\-g \-\-chmod=ugo=rwX\fP
.RE

.IP 
You could then use this new option in a command such as this one:
.IP 
.RS 
\f(CW   rsync \-avZ src/ dest/\fP
.RE

.IP 
(Caveat: make sure that \fB\-a\fP does not follow \fB\-Z\fP, or it will re-enable
the two \(lq\-\-no\-*\(rq options mentioned above.)
.IP 
The preservation of the destination's setgid bit on newly-created
directories when \fB\-\-perms\fP is off was added in rsync 2.6.7.  Older rsync
versions erroneously preserved the three special permission bits for
newly-created files when \fB\-\-perms\fP was off, while overriding the
destination's setgid bit setting on a newly-created directory.  Default ACL
observance was added to the ACL patch for rsync 2.6.7, so older (or
non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
(Keep in mind that it is the version of the receiving rsync that affects
these behaviors.)
.IP 
.IP "\fB\-E, \-\-executability\fP"
This option causes rsync to preserve the
executability (or non-executability) of regular files when \fB\-\-perms\fP is
not enabled.  A regular file is considered to be executable if at least one
\(oqx\(cq is turned on in its permissions.  When an existing destination file's
executability differs from that of the corresponding source file, rsync
modifies the destination file's permissions as follows:
.IP 
.RS 
.IP o 
To make a file non-executable, rsync turns off all its \(oqx\(cq
permissions.
.IP o 
To make a file executable, rsync turns on each \(oqx\(cq permission that
has a corresponding \(oqr\(cq permission enabled.
.RE

.IP 
If \fB\-\-perms\fP is enabled, this option is ignored.
.IP 
.IP "\fB\-A, \-\-acls\fP"
This option causes rsync to update the destination
ACLs to be the same as the source ACLs.
The option also implies \fB\-\-perms\fP.
.IP 
The source and destination systems must have compatible ACL entries for this
option to work properly.  See the \fB\-\-fake\-super\fP option for a way to backup
and restore ACLs that are not compatible.
.IP 
.IP "\fB\-X, \-\-xattrs\fP"
This option causes rsync to update the remote
extended attributes to be the same as the local ones.
.IP 
For systems that support extended-attribute namespaces, a copy being done by a
super-user copies all namespaces except system.*.  A normal user only copies
the user.* namespace.  To be able to backup and restore non-user namespaces as
a normal user, see the \fB\-\-fake\-super\fP option.
.IP 
.IP "\fB\-\-chmod\fP"
This option tells rsync to apply one or more
comma-separated \(lqchmod\(rq strings to the permission of the files in the
transfer.  The resulting value is treated as though it was the permissions
that the sending side supplied for the file, which means that this option
can seem to have no effect on existing files if \fB\-\-perms\fP is not enabled.
.IP 
In addition to the normal parsing rules specified in the \fBchmod\fP(1)
manpage, you can specify an item that should only apply to a directory by
prefixing it with a \(oqD\(cq, or specify an item that should only apply to a
file by prefixing it with a \(oqF\(cq.  For example:
.IP 
.RS 
\-\-chmod=Dg+s,ug+w,Fo-w,+X
.RE