-r, --recursive recurse into directories
-R, --relative use relative path names
-b, --backup make backups (default ~ suffix)
+ --backup-dir=DIR put backups in the specified directory
--suffix=SUFFIX override backup suffix
-u, --update update only (don't overwrite newer files)
-l, --links preserve soft links
--delete delete files that don't exist on the sending side
--delete-excluded also delete excluded files on the receiving side
--delete-after delete after transferring, not before
+ --ignore-errors delete even if there are IO errors
--max-delete=NUM don't delete more than NUM files
--partial keep partially transferred files
--force force deletion of directories even if not empty
--address bind to the specified address
--config=FILE specify alternate rsyncd.conf file
--port=PORT specify alternate rsyncd port number
+ --blocking-io use blocking IO for the remote shell
--stats give some file transfer stats
--progress show progress during transfer
--log-format=FORMAT log file transfers using specified format
--password-file=FILE get password from FILE
+ --bwlimit=KBPS limit I/O bandwidth, KBytes per second
-h, --help show this help screen
)
which already exist and have the same checksum and size on the
receiver are skipped. This option can be quite slow.
-dit(bf(-a, --archive)) This is equivalent to -rlptg. It is a quick way
+dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick way
of saying you want recursion and want to preserve everything.
-Note: if the user launching rsync is root then the -o (preserve
-uid) and -D (preserve devices) options are also implied.
-
dit(bf(-r, --recursive)) This tells rsync to copy directories
recursively. If you don't specify this then rsync won't copy
directories at all.
renamed with a ~ extension as each file is transferred. You can
control the backup suffix using the --suffix option.
+dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
+tells rsync to store all backups in the specified directory. This is
+very useful for incremental backups.
+
dit(bf(--suffix=SUFFIX)) This option allows you to override the default
backup suffix used with the -b option. The default is a ~.
dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
rather than the default port 873.
+dit(bf(--blocking-io)) This specifies whether rsync will use blocking
+IO when launching a remote shell transport. You may find this is
+needed for some remote shells that can't handle the default
+non-blocking IO.
+
dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
rsync client logs to stdout on a per-file basis. The log format is
specified using the same format conventions as the log format option in
in a file for accessing a remote rsync server. Note that this option
is only useful when accessing a rsync server using the built in
transport, not when using a remote shell as the transport. The file
-must not be world readable.
+must not be world readable. It should contain just the password as a
+single line.
+
+dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
+transfer rate in kilobytes per second. This option is most effective when
+using rsync with large files (several megabytes and up). Due to the nature
+of rsync transfers, blocks of data are sent, then if rsync determines the
+transfer was too fast, it will wait before sending the next data block. The
+result is an average transfer rate equalling the specified limit. A value
+of zero specifies no limit.
enddit()
skipped. If no matching include/exclude pattern is found then the
filename is not skipped.
-Note that the --include and --exclude options take one pattern
+Note that when used with -r (which is implied by -a), every subcomponent of
+every path is visited from top down, so include/exclude patterns get
+applied recursively to each subcomponent.
+
+Note also that the --include and --exclude options take one pattern
each. To add multiple patterns use the --include-from and
--exclude-from options or multiple --include and --exclude options.
itemize(
it() if the pattern starts with a / then it is matched against the
start of the filename, otherwise it is matched against the end of
- the filename. Thus /foo would match a file called foo
- at the base of the tree whereas foo would match any file
- called foo anywhere in the tree.
+ the filename. Thus "/foo" would match a file called "foo" at the base of
+ the tree. On the other hand, "foo" would match any file called "foo"
+ anywhere in the tree because the algorithm is applied recursively from
+ top down; it behaves as if each path component gets a turn at being the
+ end of the file name.
it() if the pattern ends with a / then it will only match a
directory, not a file, link or device.
*?[ then expression matching is applied using the shell filename
matching rules. Otherwise a simple string match is used.
+ it() if the pattern includes a double asterisk "**" then all wildcards in
+ the pattern will match slashes, otherwise they will stop at slashes.
+
it() if the pattern contains a / (not counting a trailing /) then it
is matched against the full filename, including any leading
directory. If the pattern doesn't contain a / then it is matched
- only against the final component of the filename. Furthermore, if
- the pattern includes a double asterisk "**" then all wildcards in
- the pattern will match slashes, otherwise they will stop at slashes.
+ only against the final component of the filename. Again, remember
+ that the algorithm is applied recursively so "full filename" can
+ actually be any portion of a path.
it() if the pattern starts with "+ " (a plus followed by a space)
then it is always considered an include pattern, even if specified as
The +/- rules are most useful in exclude lists, allowing you to have a
single exclude list that contains both include and exclude options.
-Here are some examples:
+If you end an exclude list with --exclude '*', note that since the
+algorithm is applied recursively that unless you explicitly include
+parent directories of files you want to include then the algorithm
+will stop at the parent directories and never see the files below
+them. To include all directories, use --include '*/' before the
+--exclude '*'.
+
+Here are some exclude/include examples:
itemize(
it() --exclude "*.o" would exclude all filenames matching *.o