rsync.yo

Rsync 3.0.5 source code

bf(--recursive) option, rsync will skip all directories it encounters (and
output a message to that effect for each one).  If you specify both
bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence.

The bf(--dirs) option is implied by the bf(--files-from) option
or the bf(--list-only) option (including an implied
bf(--list-only) usage) if bf(--recursive) wasn't specified (so that
directories are seen in the listing).  Specify bf(--no-dirs) (or bf(--no-d))
if you want to turn this off.

There is also a backward-compatibility helper option, bf(--old-dirs) (or
bf(--old-d)) that tells rsync to use a hack of "-r --exclude='/*/*'" to get
an older rsync to list a single directory without recursing.

dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.

dit(bf(-L, --copy-links)) 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 bf(--keep-dirlinks) (bf(-K))
to get this extra behavior.  The only exception is when sending files to
an rsync that is too old to understand bf(-K) -- in that case, the bf(-L) option
will still have the side-effect of bf(-K) on that older receiving rsync.

dit(bf(--copy-unsafe-links)) 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 bf(--relative) is used.  This option has no
additional effect if bf(--copy-links) was also specified.

dit(bf(--safe-links)) 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 bf(--relative) may
give unexpected results.

dit(bf(-k, --copy-dirlinks)) 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 bf(--copy-links).

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
bf(--force) or bf(--delete) is in effect).

See also bf(--keep-dirlinks) for an analogous option for the receiving
side.

dit(bf(-K, --keep-dirlinks)) 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.

For example, suppose you transfer a directory "foo" that contains a file
"file", but "foo" is a symlink to directory "bar" on the receiver.  Without
bf(--keep-dirlinks), the receiver deletes symlink "foo", recreates it as a
directory, and receives the file into the new directory.  With
bf(--keep-dirlinks), the receiver keeps the symlink and "file" ends up in
"bar".

One note of caution:  if you use bf(--keep-dirlinks), 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.

See also bf(--copy-dirlinks) for an analogous option for the sending side.

dit(bf(-H, --hard-links)) 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.

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 bf(--inplace) option).

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 bf(--inplace) 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 bf(--inplace) option for more caveats).

If incremental recursion is active (see bf(--recursive)), 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 bf(--no-inc-recursive) option.

dit(bf(-p, --perms)) This option causes the receiving rsync to set the
destination permissions to be the same as the source permissions.  (See
also the bf(--chmod) option for a way to modify what rsync considers to
be the source permissions.)

When this option is em(off), permissions are set as follows:

quote(itemization(
  it() Existing files (including updated files) retain their existing
  permissions, though the bf(--executability) option might change just
  the execute permission for the file.
  it() New files get their "normal" 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.
))

Thus, when bf(--perms) and bf(--executability) are both disabled,
rsync's behavior is the same as that of other file-copy utilities,
such as bf(cp)(1) and bf(tar)(1).

In summary: to give destination files (both old and new) the source
permissions, use bf(--perms).  To give new files the destination-default
permissions (while leaving existing files unchanged), make sure that the
bf(--perms) option is off and use bf(--chmod=ugo=rwX) (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 bf(-Z) option,
and includes --no-g to use the default group of the destination dir):

quote(tt(   rsync alias -Z --no-p --no-g --chmod=ugo=rwX))

You could then use this new option in a command such as this one:

quote(tt(   rsync -avZ src/ dest/))

(Caveat: make sure that bf(-a) does not follow bf(-Z), or it will re-enable
the two "--no-*" options mentioned above.)

The preservation of the destination's setgid bit on newly-created
directories when bf(--perms) is off was added in rsync 2.6.7.  Older rsync
versions erroneously preserved the three special permission bits for
newly-created files when bf(--perms) 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.)

dit(bf(-E, --executability)) This option causes rsync to preserve the
executability (or non-executability) of regular files when bf(--perms) is
not enabled.  A regular file is considered to be executable if at least one
'x' 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:

quote(itemization(
  it() To make a file non-executable, rsync turns off all its 'x'
  permissions.
  it() To make a file executable, rsync turns on each 'x' permission that
  has a corresponding 'r' permission enabled.
))

If bf(--perms) is enabled, this option is ignored.

dit(bf(-A, --acls)) This option causes rsync to update the destination
ACLs to be the same as the source ACLs.
The option also implies bf(--perms).

The source and destination systems must have compatible ACL entries for this
option to work properly.  See the bf(--fake-super) option for a way to backup
and restore ACLs that are not compatible.

dit(bf(-X, --xattrs)) This option causes rsync to update the remote
extended attributes to be the same as the local ones.

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 bf(--fake-super) option.

dit(bf(--chmod)) This option tells rsync to apply one or more
comma-separated "chmod" 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 bf(--perms) is not enabled.

In addition to the normal parsing rules specified in the bf(chmod)(1)
manpage, you can specify an item that should only apply to a directory by
prefixing it with a 'D', or specify an item that should only apply to a
file by prefixing it with a 'F'.  For example:

quote(--chmod=Dg+s,ug+w,Fo-w,+X)

It is also legal to specify multiple bf(--chmod) options, as each
additional option is just appended to the list of changes to make.

See the bf(--perms) and bf(--executability) options for how the resulting
permission value can be applied to the files in the transfer.

dit(bf(-o, --owner)) 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 bf(--super)
and bf(--fake-super) options).
Without this option, the owner of new and/or transferred files are set to
the invoking user on the receiving side.

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
bf(--numeric-ids) option for a full discussion).

dit(bf(-g, --group)) 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 bf(--no-super) 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.

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 bf(--numeric-ids) option for a full discussion).

dit(bf(--devices)) 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 bf(--super) and bf(--fake-super) options).

dit(bf(--specials)) This option causes rsync to transfer special files
such as named sockets and fifos.

dit(bf(-D)) The bf(-D) option is equivalent to bf(--devices) bf(--specials).

dit(bf(-t, --times)) 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 bf(-t) or bf(-a) will
cause the next transfer to behave as if it used bf(-I), 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 bf(-t)).

dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
it is preserving modification times (see bf(--times)).  If NFS is sharing
the directories on the receiving side, it is a good idea to use bf(-O).
This option is inferred if you use bf(--backup) without bf(--backup-dir).

dit(bf(--super)) 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 bf(--owner) option, preserving
all groups (not just the current user's groups) via the bf(--groups)
option, and copying devices via the bf(--devices) option.  This is useful
for systems that allow such activities without being the super-user, and