a fast, versatile, remote (and local) file-copying tool
|
-r, --recursive
This tells rsync to copy directories recursively. See also --dirs (-d).
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.
Some options require rsync to know the full file list, so these options disable the incremental
recursion mode. These include: --delete-before, --delete-after, --prune-empty-dirs, and
--delay-updates. Because of this, the default delete mode when you specify --delete is now
--delete-during when both ends of the connection are at least 3.0.0 (use --del or --delete-during
to request this improved deletion mode explicitly). See also the --delete-delay option that is a
better choice than using --delete-after.
Incremental recursion can be disabled using the --no-inc-recursive option or its shorter --no-i-r
alias.
|
-l, --links
When symlinks are encountered, recreate the symlink on the destination.
|
-p, --perms
This option causes the receiving rsync to set the destination permissions to be the same as the
source permissions. (See also the --chmod option for a way to modify what rsync considers to be
the source permissions.)
When this option is off, permissions are set as follows:
o Existing files (including updated files) retain their existing permissions, though the
--executability option might change just the execute permission for the file.
o 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 --perms and --executability are both disabled, rsync’s behavior is the same as that of
other file-copy utilities, such as cp(1) and tar(1).
In summary: to give destination files (both old and new) the source permissions, use --perms. To
give new files the destination-default permissions (while leaving existing files unchanged), make
sure that the --perms option is off and use --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 -Z
option, and includes --no-g to use the default group of the destination dir):
rsync alias -Z --no-p --no-g --chmod=ugo=rwX
You could then use this new option in a command such as this one:
rsync -avZ src/ dest/
(Caveat: make sure that -a does not follow -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 --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 --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.)
|
-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 -t or -a will cause the next transfer
to behave as if it used -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 -t).
|
-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 --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 --numeric-ids option for a full
discussion).
|
-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 --super and
--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 --numeric-ids option for a full discussion).
|
-D The -D option is equivalent to --devices --specials.
|
-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.
|
-i, --itemize-changes
Requests a simple itemized list of the changes that are being made to each file, including
attribute changes. This is exactly the same as specifying --out-format='%i %n%L'. If you repeat
the option, unchanged files will also be output, but only if the receiving rsync is at least
version 2.6.7 (you can use -vv with older versions of rsync, but that also turns on the output of
other verbose messages).
The "%i" escape has a cryptic output that is 11 letters long. The general format is like the
string YXcstpoguax, where Y is replaced by the type of update being done, X is replaced by the
file-type, and the other letters represent attributes that may be output if they are being
modified.
The update types that replace the Y are as follows:
o A < means that a file is being transferred to the remote host (sent).
o A > means that a file is being transferred to the local host (received).
o A c means that a local change/creation is occurring for the item (such as the creation of a
directory or the changing of a symlink, etc.).
o A h means that the item is a hard link to another item (requires --hard-links).
o A . means that the item is not being updated (though it might have attributes that are
being modified).
o A * means that the rest of the itemized-output area contains a message (e.g. "deleting").
The file-types that replace the X are: f for a file, a d for a directory, an L for a symlink, a D
for a device, and a S for a special file (e.g. named sockets and fifos).
The other letters in the string above are the actual letters that will be output if the associated
attribute for the item is being updated or a "." for no change. Three exceptions to this are: (1)
a newly created item replaces each letter with a "+", (2) an identical item replaces the dots with
spaces, and (3) an unknown attribute replaces each letter with a "?" (this can happen when talking
to an older rsync).
The attribute that is associated with each letter is as follows:
o A c means either that a regular file has a different checksum (requires --checksum) or that
a symlink, device, or special file has a changed value. Note that if you are sending files
to an rsync prior to 3.0.1, this change flag will be present only for checksum-differing
regular files.
o A s means the size of a regular file is different and will be updated by the file transfer.
o A t means the modification time is different and is being updated to the sender’s value
(requires --times). An alternate value of T means that the modification time will be set
to the transfer time, which happens when a file/symlink/device is updated without --times
and when a symlink is changed and the receiver can’t set its time. (Note: when using an
rsync 3.0.0 client, you might see the s flag combined with t instead of the proper T flag
for this time-setting failure.)
o A p means the permissions are different and are being updated to the sender’s value
(requires --perms).
o An o means the owner is different and is being updated to the sender’s value (requires
--owner and super-user privileges).
o A g means the group is different and is being updated to the sender’s value (requires
--group and the authority to set the group).
o The u slot is reserved for future use.
o The a means that the ACL information changed.
o The x means that the extended attribute information changed.
One other output is possible: when deleting files, the "%i" will output the string "*deleting"
for each item that is being removed (assuming that you are talking to a recent enough rsync that
it logs deletions instead of outputting them as a verbose message).
|
-x, --one-file-system
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 "bind" mount to the same
device as being on the same filesystem.
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).
If rsync has been told to collapse symlinks (via --copy-links or --copy-unsafe-links), a symlink
to a directory on another device is treated like a mount-point. Symlinks to non-directories are
unaffected by this option.
|
-X, --xattrs
This option causes rsync to update the destination extended attributes to be the same as the
source 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 --fake-super option.
Note that this option does not copy rsyncs special xattr values (e.g. those used by --fake-super)
unless you repeat the option (e.g. -XX). This "copy all xattrs" mode cannot be used with
--fake-super.
|
-E, --executability
This option causes rsync to preserve the executability (or non-executability) of regular files
when --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:
o To make a file non-executable, rsync turns off all its ’x’ permissions.
o To make a file executable, rsync turns on each ’x’ permission that has a corresponding ’r’
permission enabled.
If --perms is enabled, this option is ignored.
|
-H, --hard-links
This tells rsync to look for hard-linked files in the source and link together the corresponding
files on the destination. Without this option, hard-linked files in the source are treated as
though they were separate files.
This option does NOT necessarily ensure that the pattern of hard links on the destination exactly
matches that on the source. Cases in which the destination may end up with extra hard links
include the following:
o If the destination contains extraneous hard-links (more linking than what is present in the
source file list), the copying algorithm will not break them explicitly. However, if one
or more of the paths have content differences, the normal file-update process will break
those extra links (unless you are using the --inplace option).
o If you specify a --link-dest directory that contains hard links, the linking of the
destination files against the --link-dest files can cause some paths in the destination to
become linked together due to the --link-dest associations.
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 --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 --inplace option for more
caveats).
If incremental recursion is active (see --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 (i.e. which files are hard-linked together), just its
efficiency (i.e. copying the data for a new, early copy of a hard-linked file that could have been
found later in the transfer in another member of the hard-linked set of files). One way to avoid
this inefficiency is to disable incremental recursion using the --no-inc-recursive option.
|