mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(22 Apr 2006)()()
+manpage(rsync)(1)(6 Nov 2006)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
Some of the additional features of rsync are:
-itemize(
+itemization(
it() support for copying links, devices, owners, groups, and permissions
it() exclude and exclude-from options similar to GNU tar
it() a CVS exclude mode for ignoring the same files that CVS would ignore
Using rsync in this way is the same as using it with a remote shell except
that:
-itemize(
+itemization(
it() you either use a double colon :: instead of a single colon to
separate the hostname from the path, or you use an rsync:// URL.
it() the first word of the "path" is actually a module name.
to the detailed description below for a complete description. verb(
-v, --verbose increase verbosity
-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)
--no-OPTION turn off an implied OPTION (e.g. --no-D)
-H, --hard-links preserve hard links
-p, --perms preserve permissions
-E, --executability preserve executability
- --chmod=CHMOD change destination permissions
+ --chmod=CHMOD affect file and/or directory permissions
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
--delete delete extraneous files from dest dirs
--delete-before receiver deletes before transfer (default)
--delete-during receiver deletes during xfer, not before
+ --delete-delay find deletions during, delete after
--delete-after receiver deletes after transfer, not before
--delete-excluded also delete excluded files from dest dirs
--ignore-errors delete even if there are I/O errors
--out-format=FORMAT output updates using the specified FORMAT
--log-file=FILE log what we're doing to the specified FILE
--log-file-format=FMT log updates using the specified FMT
- --password-file=FILE read password from FILE
+ --password-file=FILE read daemon-access password from FILE
--list-only list the files instead of copying them
--bwlimit=KBPS limit I/O bandwidth; KBytes per second
--write-batch=FILE write a batched update to FILE
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
--version print version number
-(-h) --help show this help (see below for -h comment)
-)
+(-h) --help show this help (see below for -h comment))
Rsync can also be run as a daemon, in which case the following options are
accepted: verb(
-v, --verbose increase verbosity
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
- -h, --help show this help (if used after --daemon)
-)
+ -h, --help show this help (if used after --daemon))
manpageoptions()
from the remote server. This flag is useful when invoking rsync from
cron.
+dit(bf(--no-motd)) This option affects the information that is output
+by the client at the start of a daemon transfer. This suppresses the
+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.
+
dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
already the same size and have the same modification time-stamp.
-This option turns off this "quick check" behavior.
+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(--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. -f "P *~"). This will prevent previously backed-up files from being
+(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
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. This is
-very useful for incremental backups. You can additionally
+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).
When this option is em(off), permissions are set as follows:
-quote(itemize(
+quote(itemization(
it() Existing files (including updated files) retain their existing
permissions, though the bf(--executability) option might change just
the execute permission for the file.
executability differs from that of the corresponding source file, rsync
modifies the destination file's permissions as follows:
-quote(itemize(
+quote(itemization(
it() To make a file non-executable, rsync turns off all its 'x'
permissions.
it() To make a file executable, rsync turns on each 'x' permission that
but it is only supported beginning with 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 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.
+
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
bf(--recursive) option was also enabled.
dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
-files or directories (NUM must be non-zero).
+files or directories.
+Beginning with version 3.0.0, you may specify bf(--max-delete=0) to
+be warned about any extraneous files in the destination, but be very
+careful to never specify a 0 value to an older rsync client, or the
+option will be silently ignored. (A 3.0.0 client will die with an
+error if the remote rsync is not new enough to handle the situation.)
This is useful when mirroring very large trees to prevent disasters.
dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
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
-systems. It uses the same algorithm that CVS uses to determine if
+systems. It uses a similar algorithm to CVS to determine if
a file should be ignored.
-The exclude list is initialized to:
+The exclude list is initialized to exclude the following items (these
+initial items are marked as perishable -- see the FILTER RULES section):
quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
-.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)))
+.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .bzr/)))
-then files listed in a $HOME/.cvsignore are added to the list and any
+then, files listed in a $HOME/.cvsignore are added to the list and any
files listed in the CVSIGNORE environment variable (all cvsignore names
are delimited by whitespace).
for standard input). It also tweaks the default behavior of rsync to make
transferring just the specified files and directories easier:
-quote(itemize(
+quote(itemization(
it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
information that is specified for each item in the file (use
bf(--no-relative) or bf(--no-R) if you want to turn that off).
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.
+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
+file is updated.
+
If em(DIR) is a relative path, it is relative to the destination directory.
See also bf(--compare-dest) and bf(--copy-dest).
The update types that replace the bf(Y) are as follows:
-quote(itemize(
+quote(itemization(
it() A bf(<) means that a file is being transferred to the remote host
(sent).
it() A bf(>) means that a file is being transferred to the local host
The attribute that is associated with each letter is as follows:
-quote(itemize(
+quote(itemization(
it() A bf(c) means the checksum of the file is different and will be
updated by the file transfer (requires bf(--checksum)).
it() A bf(s) means the size of the file is different and will be updated
on the file transfer, allowing you to tell how effective the rsync
algorithm is for your data.
-The current statistics are as follows: quote(itemize(
+The current statistics are as follows: quote(itemization(
it() bf(Number of files) is the count of all "files" (in the generic
sense), which includes directories, symlinks, etc.
it() bf(Number of files transferred) is the count of normal files that
quote( rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest)
If you didn't want to remove superfluous destination files, the more
-time-honored options of "--include='*/' --exclude='*'" would work fine
+time-honored options of "bf(--include='*/' --exclude='*')" would work fine
in place of the hide-filter (if that is more natural to you).
dit(bf(--progress)) This option tells rsync to print information
something to watch.
Implies bf(--verbose) if it wasn't already specified.
-When the file is transferring, the data looks like this:
+While rsync is transferring a regular file, it updates a progress line that
+looks like this:
verb( 782448 63% 110.64kB/s 0:00:04)
-This tells you the current file size, the percentage of the transfer that
-is complete, the current calculated file-completion rate (including both
-data over the wire and data being matched locally), and the estimated time
-remaining in this transfer.
+In this example, the receiver has reconstructed 782448 bytes or 63% of the
+sender's file, which is being reconstructed at a rate of 110.64 kilobytes
+per second, and the transfer will finish in 4 seconds if the current rate
+is maintained until the end.
+
+These statistics can be misleading if the incremental transfer algorithm is
+in use. For example, if the sender's file consists of the basis file
+followed by additional data, the reported rate will probably drop
+dramatically when the receiver gets to the literal data, and the transfer
+will probably take much longer to finish than the receiver estimated as it
+was finishing the matched part of the file.
-After a file is complete, the data looks like this:
+When the file transfer finishes, rsync replaces the progress line with a
+summary line that looks like this:
-verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396))
+verb( 1238099 100% 146.38kB/s 0:00:08 (xfer#5, to-check=169/396))
-This tells you the final file size, that it's 100% complete, the final
-transfer rate for the file, the amount of elapsed time it took to transfer
-the file, and the addition of a total-transfer summary in parentheses.
-These additional numbers tell you how many files have been updated, and
-what percent of the total number of files has been scanned.
+In this example, the file was 1238099 bytes long in total, the average rate
+of transfer for the whole file was 146.38 kilobytes per second over the 8
+seconds that it took to complete, it was the 5th transfer of a regular file
+during the current rsync session, and there are 169 more files for the
+receiver to check (to see if they are up-to-date or not) remaining out of
+the 396 total files in the file-list.
dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). Its
purpose is to make it much easier to specify these two options for a long
transfer that may be interrupted.
-dit(bf(--password-file)) This option allows you to provide a password
-in a file for accessing a remote rsync daemon. Note that this option
-is only useful when accessing an rsync daemon using the built in
-transport, not when using a remote shell as the transport. The file
-must not be world readable. It should contain just the password as a
-single line.
+dit(bf(--password-file)) This option allows you to provide a password in a
+file for accessing an rsync daemon. The file must not be world readable.
+It should contain just the password as a single line.
+
+When accessing an rsync daemon using a remote shell as the transport, this
+option only comes into effect after the remote shell finishes its
+authentication (i.e. if you have also specified a password in the daemon's
+config file).
dit(bf(--list-only)) This option will cause the source files to be listed
instead of transferred. This option is inferred if there is a single source
the names of the files that are going to be transferred. These patterns
can take several forms:
-itemize(
+itemization(
it() if the pattern starts with a / then it is anchored to a
particular spot in the hierarchy of files, otherwise it is matched
against the end of the pathname. This is similar to a leading ^ in
down.)
it() a trailing "dir_name/***" will match both the directory (as if
"dir_name/" had been specified) and all the files in the directory
- (as if "dir_name/**" had been specified). (This behavior is new for
- version 2.6.7.)
+ (as if "dir_name/**" had been specified). This behavior was added in
+ version 2.6.7.
)
Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by
Here are some examples of exclude/include matching:
-itemize(
+itemization(
it() "- *.o" would exclude all filenames matching *.o
it() "- /foo" would exclude a file (or directory) named foo in the
transfer-root directory
The following modifiers are accepted after a merge or dir-merge rule:
-itemize(
+itemization(
it() A bf(-) specifies that the file should consist of only exclude
patterns, with no other rule-parsing except for in-file comments.
it() A bf(+) specifies that the file should consist of only include
The following modifiers are accepted after a "+" or "-":
-itemize(
- it() A "/" specifies that the include/exclude rule should be matched
+itemization(
+ it() A bf(/) specifies that the include/exclude rule should be matched
against the absolute pathname of the current item. For example,
"-/ /etc/passwd" would exclude the passwd file any time the transfer
was sending files from the "/etc" directory, and "-/ subdir/foo"
would always exclude "foo" when it is in a dir named "subdir", even
if "foo" is at the root of the current transfer.
- it() A "!" specifies that the include/exclude should take effect if
+ it() A bf(!) specifies that the include/exclude should take effect if
the pattern fails to match. For instance, "-! */" would exclude all
non-directories.
it() A bf(C) is used to indicate that all the global CVS-exclude rules
being deleted. See the bf(s) modifier for more info. See also the
protect (P) and risk (R) rules, which are an alternate way to
specify receiver-side includes/excludes.
+ it() A bf(p) indicates that a rule is perishable, meaning that it is
+ ignored in directories that are being deleted. For instance, the bf(-C)
+ option's default rules that exclude things like "CVS" and "*.o" are
+ marked as perishable, and will not prevent a directory that was removed
+ on the source from being deleted on the destination.
)
Per-directory rules are inherited in all subdirectories of the directory
affect the other CVS exclude rules (i.e. the default list of exclusions,
the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
omit the bf(-C) command-line option and instead insert a "-C" rule into
-your filter rules; e.g. "--filter=-C".
+your filter rules; e.g. "bf(--filter=-C)".
manpagesection(LIST-CLEARING FILTER RULE)
into the directory /bdest/dir. The differences between the two examples
reveals some of the flexibility you have in how you deal with batches:
-itemize(
+itemization(
it() The first example shows that the initial copy doesn't have to be
local -- you can push or pull data to/from a remote host using either the
remote-shell syntax or rsync daemon syntax, as desired.
bf(--links) for bf(--safe-links) to have any effect.)
Symbolic links are considered unsafe if they are absolute symlinks
-(start with bf(/)), empty, or if they contain enough bf("..")
+(start with bf(/)), empty, or if they contain enough ".."
components to ascend from the directory being copied.
Here's a summary of how the symlink options are interpreted. The list is
manpagesection(VERSION)
-This man page is current for version 2.6.8 of rsync.
+This man page is current for version 2.6.9 of rsync.
manpagesection(INTERNAL OPTIONS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff