manpagedescription()
-rsync is a program that behaves in much the same way that rcp does,
+Rsync is a program that behaves in much the same way that rcp does,
but has many more options and uses the rsync remote-update protocol to
greatly speed up file transfers when the destination file is being
updated.
an efficient checksum-search algorithm described in the technical
report that accompanies this package.
+Rsync finds files that need to be transferred using a "quick check" algorithm
+that looks for files that have changed in size or in last-modified time (by
+default). Any changes in the other preserved attributes (as requested by
+options) are made on the destination file directly when the quick check
+indicates that the file's data does not need to be updated.
+
Some of the additional features of rsync are:
itemization(
-q, --quiet suppress non-error messages
--no-motd suppress daemon-mode MOTD (see caveat)
-c, --checksum skip based on checksum, not mod-time & size
- -a, --archive archive mode; same as -rlptgoD (no -H)
+ -a, --archive archive mode; equals -rlptgoD (no -H,-A,-X)
--no-OPTION turn off an implied OPTION (e.g. --no-D)
-r, --recursive recurse into directories
-R, --relative use relative path names
-p, --perms preserve permissions
-E, --executability preserve executability
--chmod=CHMOD affect file and/or directory permissions
+ -A, --acls preserve ACLs (implies -p)
+ -X, --xattrs preserve extended attrs (implies -p)
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
-t, --times preserve times
-O, --omit-dir-times omit directories when preserving times
--super receiver attempts super-user activities
+ --fake-super store/recover privileged attrs using xattrs
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy files whole (without rsync algorithm)
--only-write-batch=FILE like --write-batch but w/o updating dest
--read-batch=FILE read a batched update from FILE
--protocol=NUM force an older protocol version to be used
+ --iconv=CONVERT_SPEC request charset conversion of filesnames
--checksum-seed=NUM set block/file checksum seed (advanced)
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
request the list of modules from the daemon.
dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
-already the same size and have the same modification time-stamp.
+already the same size and have the same modification timestamp.
This option turns off this "quick check" behavior, causing all files to
be updated.
-dit(bf(--size-only)) Normally rsync will not transfer any files that are
-already the same size and have the same modification time-stamp. With the
-bf(--size-only) option, files will not be transferred if they have the same size,
-regardless of timestamp. This is useful when starting to use rsync
-after using another mirroring system which may not preserve timestamps
-exactly.
+dit(bf(--size-only)) This modifies rsync's "quick check" 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.
dit(bf(--modify-window)) When comparing two timestamps, rsync treats the
timestamps as being equal if they differ by no more than the modify-window
times with a 2-second resolution), bf(--modify-window=1) is useful
(allowing times to differ by up to 1 second).
-dit(bf(-c, --checksum)) This forces the sender to checksum em(every)
-regular file using a 128-bit MD4 checksum. It does this during the initial
-file-system scan as it builds the list of all available files. The receiver
-then checksums its version of each file (if it exists and it has the same
-size as its sender-side counterpart) in order to decide which files need to
-be updated: files with either a changed size or a changed checksum are
-selected for transfer. Since this whole-file checksumming of all files on
-both sides of the connection occurs in addition to the automatic checksum
-verifications that occur during a file's transfer, this option can be quite
-slow.
-
-Note that rsync always verifies that each em(transferred) file was correctly
-reconstructed on the receiving side by checking its whole-file checksum, but
-that automatic after-the-transfer verification has nothing to do with this
+dit(bf(-c, --checksum)) 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 "quick check" 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.
+
+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.
+
+Note that rsync always verifies that each em(transferred) file was
+correctly reconstructed on the receiving side by checking a whole-file
+checksum that is generated when as the file is transferred, but that
+automatic after-the-transfer verification has nothing to do with this
option's before-the-transfer "Does this file need to be updated?" check.
dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is
also in effect (without bf(--delete-excluded)), rsync will add a "protect"
filter-rule for the backup suffix to the end of all your existing excludes
-(e.g. bf(-f "P *~")). This will prevent previously backed-up files from being
+(e.g. bf(-f "Pp *~")). 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
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
+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).
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 end's umask setting, and
+ 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.
))
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. (Keep in
-mind that it is the version of the receiving rsync that affects this
-behavior.)
+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
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. This nonstandard option only
+works if the remote rsync also supports it. bf(--acls) implies bf(--perms).
+
+dit(bf(-X, --xattrs)) This option causes rsync to update the remote
+extended attributes to be the same as the local ones. This will work
+only if the remote machine's rsync supports this option also. This is
+a non-standard 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
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)
-option to force rsync to attempt super-user activities).
+and bf(--fake-super) options).
Without this option, the owner is set to the invoking user on the
receiving side.
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 and bf(--super) is not specified.
+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.
being running as the super-user. To turn off super-user activities, the
super-user can use bf(--no-super).
+dit(bf(--fake-super)) When this option is enabled, rsync simulates
+super-user activities by saving/restoring the privileged attributes via a
+special extended attribute that is 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 or
+directory, the files we create can always be accessed/changed by the
+creating user).
+
+The bf(--fake-super) option only affects the side where the option is used.
+To affect the remote side of a remote-shell connection, specify an rsync
+path:
+
+quote(tt( rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
+
+Since there is only one "side" in a local copy, this option affects both
+the sending and recieving of files. You'll need to specify a copy using
+"localhost" if you need to avoid this. Note, however, that it is always
+safe to copy from some non-fake-super files into some fake-super files
+using a local bf(--fake-super) command because the non-fake source files
+will just have their normal attributes.
+
+This option is overridden by both bf(--super) and bf(--no-super).
+
+See also the "fake super" setting in the daemon's rsyncd.conf file.
+
dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
up less space on the destination. Conflicts with bf(--inplace) because it's
not possible to overwrite data in a sparse fashion.
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 9 letters long. The general
-format is like the string bf(YXcstpogz), where bf(Y) is replaced by the
+The "%i" escape has a cryptic output that is 11 letters long. The general
+format is like the string bf(YXcstpoguax), where bf(Y) is replaced by the
type of update being done, bf(X) is replaced by the file-type, and the
other letters represent attributes that may be output if they are being
modified.
sender's value (requires bf(--owner) and super-user privileges).
it() A bf(g) means the group is different and is being updated to the
sender's value (requires bf(--group) and the authority to set the group).
- it() The bf(z) slot is reserved for future use.
+ it() The bf(u) slot is reserved for reporting update (access) time changes
+ (a feature that is not yet released).
+ it() The bf(a) means that the ACL information changed.
+ it() The bf(x) slot is reserved for reporting extended attribute changes
+ (a feature that is not yet released).
))
One other output is possible: when deleting files, the "%i" will output
sending of any partial-dir files that may exist on the sending side, and
will also prevent the untimely deletion of partial-dir items on the
receiving side. An example: the above bf(--partial-dir) option would add
-the equivalent of "bf(--exclude=.rsync-partial/)" at the end of any other
+the equivalent of "bf(-f '-p .rsync-partial/')" at the end of any other
filter rules.
If you are supplying your own exclude rules, you may need to add your own
batch file to force the older protocol version to be used in the batch
file (assuming you can't upgrade the rsync on the reading system).
+dit(bf(--iconv=CONVERT_SPEC)) Rsync can convert filenames between character
+sets using this option. Using a CONVERT_SPEC of "." tells rsync to look up
+the default character-set via the locale setting. Alternately, you can
+fully specify what conversion to do by giving a local and a remote charset
+separated by a comma (local first), e.g. bf(--iconv=utf8,iso88591).
+Finally, you can specify a CONVERT_SPEC of "-" to turn off any conversion.
+The default setting of this option is site-specific, and can also be
+affected via the RSYNC_ICONV environment variable.
+
+Note that rsync does not do any conversion of names in filter files
+(including include/exclude files), in a files-from file, nor those
+specified on the command line. It is up to you to ensure that you're
+requesting the right names from a remote server, and you can specify
+extra include/exclude rules if there are filename differences on the
+two sides that need to be accounted for. (In the future there may be
+a way to specify a UTF-8 filter rule that gets auto-converted to the
+local side's character set.)
+
dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
when creating sockets. This only affects sockets that rsync has direct
control over, such as the outgoing socket when directly contacting an
dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
ignore patterns in .cvsignore files. See the bf(--cvs-exclude) option for
more details.
+dit(bf(RSYNC_ICONV)) Specify a default bf(--iconv) setting using this
+environment variable.
dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
override the default shell used as the transport for rsync. Command line
options are permitted after the command name, just as in the bf(-e) option.
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff