rsync.yo

Rsync 3.0.5 source code

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
value.  This is normally 0 (for an exact match), but you may find it useful
to set this to a larger value in some situations.  In particular, when
transferring to or from an MS Windows FAT filesystem (which represents
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 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 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
way of saying you want recursion and want to preserve almost
everything (with -H being a notable omission).
The only exception to the above equivalence is when bf(--files-from) is
specified, in which case bf(-r) is not implied.

Note that bf(-a) bf(does not preserve hardlinks), because
finding multiply-linked files is expensive.  You must separately
specify bf(-H).

dit(--no-OPTION) You may turn off one or more implied options by prefixing
the option name with "no-".  Not all options may be prefixed with a "no-":
only options that are implied by other options (e.g. bf(--no-D),
bf(--no-perms)) or have different defaults in various circumstances
(e.g. bf(--no-whole-file), bf(--no-blocking-io), bf(--no-dirs)).  You may
specify either the short or the long option name after the "no-" prefix
(e.g. bf(--no-R) is the same as bf(--no-relative)).

For example: if you want to use bf(-a) (bf(--archive)) but don't want
bf(-o) (bf(--owner)), instead of converting bf(-a) into bf(-rlptgD), you
could specify bf(-a --no-o) (or bf(-a --no-owner)).

The order of the options is important:  if you specify bf(--no-r -a), the
bf(-r) option would end up being turned on, the opposite of bf(-a --no-r).
Note also that the side-effects of the bf(--files-from) option are NOT
positional, as it affects the default state of several options and slightly
changes the meaning of bf(-a) (see the bf(--files-from) option for more
details).

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.  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), and bf(--delay-updates).
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).

Incremental recursion can be disabled using the bf(--no-inc-recursive)
option or its shorter bf(--no-i-r) alias.

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
you want to send several different directories at the same time. For
example, if you used this command:

quote(tt(   rsync -av /foo/bar/baz.c remote:/tmp/))

... this would create a file named baz.c in /tmp/ on the remote
machine. If instead you used

quote(tt(   rsync -avR /foo/bar/baz.c remote:/tmp/))

then a file named /tmp/foo/bar/baz.c would be created on the remote
machine, preserving its full path.  These extra path elements are called
"implied directories" (i.e. the "foo" and the "foo/bar" directories in the
above example).

Beginning with rsync 3.0.0, rsync always sends these implied directories as
real directories in the file list, even if a path element is really a
symlink on the sending side.  This prevents some really unexpected
behaviors when copying the full path of a file that you didn't realize had
a symlink in its path.  If you want to duplicate a server-side symlink,
include both the symlink via its path, and referent directory via its real
path.  If you're dealing with an older rsync on the sending side, you may
need to use the bf(--no-implied-dirs) option.

It is also possible to limit the amount of path information that is sent as
implied directories for each path you specify.  With a modern rsync on the
sending side (beginning with 2.6.7), you can insert a dot and a slash into
the source path, like this:

quote(tt(   rsync -avR /foo/./bar/baz.c remote:/tmp/))

That would create /tmp/bar/baz.c on the remote machine.  (Note that the
dot must be followed by a slash, so "/foo/." would not be abbreviated.)
(2) For older rsync versions, you would need to use a chdir to limit the
source path.  For example, when pushing files:

quote(tt(   (cd /foo; rsync -avR bar/baz.c remote:/tmp/) ))

(Note that the parens put the two commands into a sub-shell, so that the
"cd" command doesn't remain in effect for future commands.)
If you're pulling files from an older rsync, use this idiom (but only
for a non-daemon transfer):

quote(
tt(   rsync -avR --rsync-path="cd /foo; rsync" \ )nl()
tt(       remote:bar/baz.c /tmp/)
)

dit(bf(--no-implied-dirs)) This option affects the default behavior of the
bf(--relative) option.  When it is specified, the attributes of the implied
directories from the source names are not included in the transfer.  This
means that the corresponding path elements on the destination system are
left unchanged if they exist, and any missing implied directories are
created with default attributes.  This even allows these implied path
elements to have big differences, such as being a symlink to a directory on
the receiving side.

For instance, if a command-line arg or a files-from entry told rsync to
transfer the file "path/foo/file", the directories "path" and "path/foo"
are implied when bf(--relative) is used.  If "path/foo" is a symlink to
"bar" on the destination system, the receiving rsync would ordinarily
delete "path/foo", recreate it as a directory, and receive the file into
the new directory.  With bf(--no-implied-dirs), the receiving rsync updates
"path/foo/file" using the existing path elements, which means that the file
ends up being created in "path/bar".  Another way to accomplish this link
preservation is to use the bf(--keep-dirlinks) option (which will also
affect symlinks to directories in the rest of the transfer).

When pulling files from an rsync older than 3.0.0, you may need to use this
option if the sending side has a symlink in the path you request and you
wish the implied directories to be transferred as normal directories.

dit(bf(-b, --backup)) With this option, preexisting destination files are
renamed as each file is transferred or deleted.  You can control where the
backup file goes and what (if any) suffix gets appended using the
bf(--backup-dir) and bf(--suffix) options.

Note that if you don't specify bf(--backup-dir), (1) the
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
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
your rules specify a trailing inclusion/exclusion of '*', the auto-added
rule would never be reached).

dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
tells rsync to store all backups in the specified directory on the receiving
side.  This can be used for incremental backups.  You can additionally
specify a backup suffix using the bf(--suffix) option
(otherwise the files backed up in the specified directory
will keep their original filenames).

dit(bf(--suffix=SUFFIX)) This option allows you to override the default
backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~
if no -bf(-backup-dir) was specified, otherwise it is an empty string.

dit(bf(-u, --update)) This forces rsync to skip any files which exist on
the destination and have a modified time that is newer than the source
file.  (If an existing destination file has a modification time equal to the
source file's, it will be updated if the sizes are different.)

Note that this does not affect the copying of symlinks or other special
files.  Also, a difference of file format between the sender and receiver
is always considered to be important enough for an update, no matter what
date is on the objects.  In other words, if the source has a directory
where the destination has a file, the transfer would occur regardless of
the timestamps.

dit(bf(--inplace)) This option changes how rsync transfers a file when the
file's data needs to be updated: instead of the default method of creating
a new copy of the file and moving it into place when it is complete, rsync
instead writes the updated data directly to the destination file.

This has several effects: (1) in-use binaries cannot be updated (either the
OS will prevent this from happening, or binaries that attempt to swap-in
their data will misbehave or crash), (2) the file's data will be in an
inconsistent state during the transfer, (3) a file's data may be left in an
inconsistent state after the transfer if the transfer is interrupted or if
an update fails, (4) a file that does not have write permissions can not be
updated, and (5) the efficiency of rsync's delta-transfer algorithm may be
reduced if some data in the destination file is overwritten before it can
be copied to a position later in the file (one exception to this is if you
combine this option with bf(--backup), since rsync is smart enough to use
the backup file as the basis file for the transfer).

WARNING: you should not use this option to update files that are being
accessed by others, so be careful when choosing to use this for a copy.

This option is useful for transfer of large files with block-based changes
or appended data, and also on systems that are disk bound, not network
bound.

The option implies bf(--partial) (since an interrupted transfer does not delete
the file), but conflicts with bf(--partial-dir) and bf(--delay-updates).
Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest)
and bf(--link-dest).

dit(bf(--append)) This causes rsync to update a file by appending data onto
the end of the file, which presumes that the data that already exists on
the receiving side is identical with the start of the file on the sending
side.  If a file needs to be transferred and its size on the receiver is
the same or longer than the size on the sender, the file is skipped.  This
does not interfere with the updating of a file's non-content attributes
(e.g. permissions, ownership, etc.) when the file does not need to be
transferred, nor does it affect the updating of any non-regular files.
Implies bf(--inplace),
but does not conflict with bf(--sparse) (since it is always extending a
file's length).

dit(bf(--append-verify)) This works just like the bf(--append) option, but
the existing data on the receiving side is included in the full-file
checksum verification step, which will cause a file to be resent if the
final verification step fails (rsync uses a normal, non-appending
bf(--inplace) transfer for the resend).

Note: prior to rsync 3.0.0, the bf(--append) option worked like
bf(--append-verify), so if you are interacting with an older rsync (or the
transfer is using a protocol prior to 30), specifying either append option
will initiate an bf(--append-verify) transfer.

dit(bf(-d, --dirs)) Tell the sending side to include any directories that
are encountered.  Unlike bf(--recursive), a directory's contents are not copied
unless the directory name specified is "." or ends with a trailing slash
(e.g. ".", "dir/.", "dir/", etc.).  Without this option or the