-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)
message-of-the-day (MOTD) text, but it also affects the list of modules
that the daemon sends in response to the "rsync host::" request (due to
a limitation in the rsync protocol), so omit this option if you want to
-request the list of modules from the deamon.
+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.
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
dit(bf(-r, --recursive)) This tells rsync to copy directories
recursively. See also bf(--dirs) (bf(-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 (e.g. when using a fully-specified
+bf(--files-from) list). 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: bf(--delete-before),
+bf(--delete-after), bf(--prune-empty-dirs), bf(--delay-updates), and bf(--hard-links).
+Because of this, the default delete mode when you specify bf(--delete) is now
+bf(--delete-during) when both ends of the connection are at least 3.0.0
+(use bf(--del) or bf(--delete-during) to request this improved deletion mode
+explicitly). See also the bf(--delete-delay) option that is a better choice
+than using bf(--delete-after).
+
dit(bf(-R, --relative)) Use relative paths. This means that the full path
names specified on the command line are sent to the server rather than
just the last parts of the filenames. This is particularly useful when
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(--ignore-existing)) This tells rsync to skip updating files that
already exist on the destination (this does em(not) ignore existing
-directores, or nothing would get done). See also bf(--existing).
+directories, or nothing would get done). See also bf(--existing).
dit(bf(--remove-source-files)) This tells rsync to remove from the sending
side the files (meaning non-directories) that are a part of the transfer
include/exclude modifiers in the FILTER RULES section).
Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
-was in effect. Beginning with 2.6.7, deletions will also occur when bf(--dirs)
-(bf(-d)) is in effect, but only for directories whose contents are being copied.
+was enabled. Beginning with 2.6.7, deletions will also occur when bf(--dirs)
+(bf(-d)) is enabled, but only for directories whose contents are being copied.
This option can be dangerous if used incorrectly! It is a very good idea
to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
The bf(--delete) option may be combined with one of the --delete-WHEN options
without conflict, as well as bf(--delete-excluded). However, if none of the
---delete-WHEN options are specified, rsync will currently choose the
-bf(--delete-before) algorithm. A future version may change this to choose the
-bf(--delete-during) algorithm. See also bf(--delete-after).
+--delete-WHEN options are specified, rsync will choose the
+bf(--delete-during) algorithm when talking to an rsync 3.0.0 or newer, and
+the bf(--delete-before) algorithm when talking to an older rsync. See also
+bf(--delete-delay) and bf(--delete-after).
dit(bf(--delete-before)) Request that the file-deletions on the receiving
-side be done before the transfer starts. This is the default if bf(--delete)
-or bf(--delete-excluded) is specified without one of the --delete-WHEN options.
+side be done before the transfer starts.
See bf(--delete) (which is implied) for more details on file-deletion.
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 bf(--timeout) was
-specified).
+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 bf(--recursive)).
dit(bf(--delete-during, --del)) Request that the file-deletions on the
receiving side be done incrementally as the transfer happens. This is
See bf(--delete) (which is implied) for more details on file-deletion.
dit(bf(--delete-delay)) Request that the file-deletions on the receiving
-side be computed incrementally as the transfer happens, and then removed
-after the transfer completes. A temporary file will be created on the
-receiving side to hold the names, but it is removed while open, so you
-won't see it during the transfer.
+side be computed during the transfer, and then removed after the transfer
+completes. 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 bf(--delete-after) (which it cannot do if bf(--recursive) is doing an
+incremental scan).
dit(bf(--delete-after)) 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.
+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 bf(--recursive)).
See bf(--delete) (which is implied) for more details on file-deletion.
dit(bf(--delete-excluded)) In addition to deleting the files on the
One tricky example is to set a different default directory on the remote
machine for use with the bf(--relative) option. For instance:
-quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/))
+quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/))
dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
broad range of files that you often don't want to transfer between
If a match is not found, a basis file from one of the em(DIR)s will be
selected to try to speed up the transfer.
+This option works best when copying into an empty destination hierarchy, as
+rsync treats existing files as definitive (so it never looks in the link-dest
+dirs when a destination file already exists), and as malleable (so it might
+change the attributes of a destination file, which affects all the hard-linked
+versions).
+
Note that if you combine this option with bf(--ignore-times), rsync will not
link any files together because it only links identical files together as a
substitute for transferring the file, never as an additional check after the
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
bf(--partial-dir) option, that directory will be used instead. See the
comments in the bf(--partial-dir) section for a discussion of how this
".~tmp~" dir will be excluded from the transfer, and what you can do if
-you wnat rsync to cleanup old ".~tmp~" dirs that might be lying around.
+you want rsync to cleanup old ".~tmp~" dirs that might be lying around.
Conflicts with bf(--inplace) and bf(--append).
This option uses more memory on the receiving side (one bit per file
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff