rsync.yo

Rsync 3.0.5 source code

also for ensuring that you will get errors if the receiving side isn't
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
special extended attributes that are 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, the
files we create can always be accessed/changed by the creating user).
This option also handles ACLs (if bf(--acls) was specified) and non-user
extended attributes (if bf(--xattrs) was specified).

This is a good way to backup data without using a super-user, and to store
ACLs from incompatible systems.

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 receiving of files.  You'll need to specify a copy using
"localhost" if you need to avoid this, possibly using the "lsh" shell
script (from the support directory) as a substitute for an actual remote
shell (see bf(--rsh)).

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.

NOTE: Don't use this option when the destination is a Solaris "tmpfs"
filesystem. It doesn't seem to handle seeks over null regions
correctly and ends up corrupting the files.

dit(bf(-n, --dry-run)) This makes rsync perform a trial run that doesn't
make any changes (and produces mostly the same output as a real run).  It
is most commonly used in combination with the bf(-v, --verbose) and/or
bf(-i, --itemize-changes) options to see what an rsync command is going
to do before one actually runs it.

The output of bf(--itemize-changes) is supposed to be exactly the same on a
dry run and a subsequent real run (barring intentional trickery and system
call failures); if it isn't, that's a bug.  Other output is the same to the
extent practical, but may differ in some areas.  Notably, a dry run does not
send the actual data for file transfers, so bf(--progress) has no effect,
the "bytes sent", "bytes received", "literal data", and "matched data"
statistics are too small, and the "speedup" value is equivalent to a run
where no file transfers are needed.

dit(bf(-W, --whole-file)) With this option rsync's delta-transfer algorithm
is not used and the whole file is sent as-is instead.  The transfer may be
faster if this option is used when the bandwidth between the source and
destination machines is higher than the bandwidth to disk (especially when the
"disk" is actually a networked filesystem).  This is the default when both
the source and destination are specified as local paths.

dit(bf(-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 bf(--copy-links) or
bf(--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.

dit(bf(--existing, --ignore-non-existing)) This tells rsync to skip
creating files (including directories) that do not exist
yet on the destination.  If this option is
combined with the bf(--ignore-existing) option, no files will be updated
(which can be useful if all you want to do is delete extraneous files).

dit(bf(--ignore-existing)) This tells rsync to skip updating files that
already exist on the destination (this does em(not) ignore existing
directories, or nothing would get done).  See also bf(--existing).

This option can be useful for those doing backups using the bf(--link-dest)
option when they need to continue a backup run that got interrupted.  Since
a bf(--link-dest) run is copied into a new directory hierarchy (when it is
used properly), using bf(--ignore existing) will ensure that the
already-handled files don't get tweaked (which avoids a change in
permissions on the hard-linked files).  This does mean that this option
is only looking at the existing files in the destination hierarchy itself.

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
and have been successfully duplicated on the receiving side.

dit(bf(--delete)) This tells rsync to delete extraneous files from the
receiving side (ones that aren't on the sending side), but only for the
directories that are being synchronized.  You must have asked rsync to
send the whole directory (e.g. "dir" or "dir/") without using a wildcard
for the directory's contents (e.g. "dir/*") since the wildcard is expanded
by the shell and rsync thus gets a request to transfer individual files, not
the files' parent directory.  Files that are excluded from the transfer are
also excluded from being deleted unless you use the bf(--delete-excluded)
option or mark the rules as only matching on the sending side (see the
include/exclude modifiers in the FILTER RULES section).

Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
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
first try a run using the bf(--dry-run) option (bf(-n)) to see what files are
going to be deleted.

If the sending side detects any I/O errors, then the deletion of any
files at the destination will be automatically disabled. This is to
prevent temporary filesystem failures (such as NFS errors) on the
sending side causing a massive deletion of files on the
destination.  You can override this with the bf(--ignore-errors) option.

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 choose the
bf(--delete-during) algorithm when talking to 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.
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).  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.  The
per-directory delete scan is done right before each directory is checked
for updates, so it behaves like a more efficient bf(--delete-before),
including doing the deletions prior to any per-directory filter files
being updated.  This option was first added in rsync version 2.6.4.
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 during the transfer (like bf(--delete-during)), and then
removed after the transfer completes.  This is useful when combined with
bf(--delay-updates) and/or bf(--fuzzy), and is more efficient than using
bf(--delete-after) (but can behave differently, since bf(--delete-after)
computes the deletions in a separate pass after all updates are done).
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).
See bf(--delete) (which is implied) for more details on file-deletion.

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.  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
receiving side that are not on the sending side, this tells rsync to also
delete any files on the receiving side that are excluded (see bf(--exclude)).
See the FILTER RULES section for a way to make individual exclusions behave
this way on the receiver, and for a way to protect files from
bf(--delete-excluded).
See bf(--delete) (which is implied) for more details on file-deletion.

dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
even when there are I/O errors.

dit(bf(--force)) This option tells rsync to delete a non-empty directory
when it is to be replaced by a non-directory.  This is only relevant if
deletions are not active (see bf(--delete) for details).

Note for older rsync versions: bf(--force) used to still be required when
using bf(--delete-after), and it used to be non-functional unless the
bf(--recursive) option was also enabled.

dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
files or directories.  If that limit is exceeded, a warning is output
and rsync exits with an error code of 25 (new for 3.0.0).

Also new for version 3.0.0, you may specify bf(--max-delete=0) to be warned
about any extraneous files in the destination without removing any of them.
Older clients interpreted this as "unlimited", so if you don't know what
version the client is, you can use the less obvious bf(--max-delete=-1) as
a backward-compatible way to specify that no deletions be allowed (though
older versions didn't warn when the limit was exceeded).

dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
file that is larger than the specified SIZE. The SIZE value can be
suffixed with a string to indicate a size multiplier, and
may be a fractional value (e.g. "bf(--max-size=1.5m)").

The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024),
"M" (or "MiB") is a mebibyte (1024*1024), and "G" (or "GiB") is a
gibibyte (1024*1024*1024).
If you want the multiplier to be 1000 instead of 1024, use "KB",
"MB", or "GB".  (Note: lower-case is also accepted for all values.)
Finally, if the suffix ends in either "+1" or "-1", the value will
be offset by one byte in the indicated direction.

Examples: --max-size=1.5mb-1 is 1499999 bytes, and --max-size=2g+1 is
2147483649 bytes.

dit(bf(--min-size=SIZE)) This tells rsync to avoid transferring any
file that is smaller than the specified SIZE, which can help in not
transferring small, junk files.
See the bf(--max-size) option for a description of SIZE.

dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
rsync's delta-transfer algorithm to a fixed value.  It is normally selected based on
the size of each file being updated.  See the technical report for details.

dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
remote shell program to use for communication between the local and
remote copies of rsync. Typically, rsync is configured to use ssh by
default, but you may prefer to use rsh on a local network.

If this option is used with bf([user@]host::module/path), then the
remote shell em(COMMAND) will be used to run an rsync daemon on the
remote host, and all data will be transmitted through that remote
shell connection, rather than through a direct socket connection to a
running rsync daemon on the remote host.  See the section "USING
RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" above.

Command-line arguments are permitted in COMMAND provided that COMMAND is
presented to rsync as a s