--backup-dir make backups into this directory
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
-u, --update update only (don't overwrite newer files)
- --inplace update the destination files inplace
+ --inplace update the destination files in-place
+ -k, --keep-dirs transfer a directory without recursing
-K, --keep-dirlinks treat symlinked dir on receiver as dir
-l, --links copy symlinks as symlinks
-L, --copy-links copy the referent of all symlinks
--existing only update files that already exist
--ignore-existing ignore files that already exist on receiver
--delete delete files that don't exist on sender
- --delete-excluded also delete excluded files on receiver
--delete-after receiver deletes after transfer, not before
+ --delete-excluded also delete excluded files on receiver
--ignore-errors delete even if there are I/O errors
+ --force force deletion of dirs even if not empty
--max-delete=NUM don't delete more than NUM files
--max-size=SIZE don't transfer any file larger than SIZE
--partial keep partially transferred files
--partial-dir=DIR put a partially transferred file into DIR
- --force force deletion of dirs even if not empty
--numeric-ids don't map uid/gid values by user/group name
--timeout=TIME set I/O timeout in seconds
-I, --ignore-times turn off mod time & file size quick check
--files-from=FILE read FILE for list of source-file names
-0 --from0 all file lists are delimited by nulls
--version print version number
+ --port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
--no-blocking-io turn off --blocking-io
--stats give some file transfer stats
--bwlimit=KBPS limit I/O bandwidth, KBytes per second
--config=FILE specify alternate rsyncd.conf file
--no-detach do not detach from the parent
- --port=PORT specify alternate rsyncd port number
+ --port=PORT listen on alternate port number
-4 --ipv4 prefer IPv4
-6 --ipv6 prefer IPv6
-h, --help show this help screen
specify bf(-H).
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.
+recursively. See also --keep-dirs (-k).
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
you want to send several different directories at the same time. For
example, if you used the command
-verb(rsync foo/bar/foo.c remote:/tmp/)
+verb(rsync /foo/bar/foo.c remote:/tmp/)
then this would create a file called foo.c in /tmp/ on the remote
machine. If instead you used
-verb(rsync -R foo/bar/foo.c remote:/tmp/)
+verb(rsync -R /foo/bar/foo.c remote:/tmp/)
then a file called /tmp/foo/bar/foo.c would be created on the remote
-machine -- the full path name is preserved.
+machine -- the full path name is preserved. To limit the amount of
+path information that is sent, do something like this:
+
+verb(cd /foo
+rsync -R bar/foo.c remote:/tmp/)
+
+That would create /tmp/bar/foo.c on the remote machine.
dit(bf(--no-relative)) Turn off the --relative option. This is only
needed if you want to use --files-from without its implied --relative
backup suffix used with the --backup (-b) option. The default suffix is a ~
if no --backup-dir was specified, otherwise it is an empty string.
-dit(bf(-u, --update)) This forces rsync to skip any files for which the
-destination file already exists and has a date later than the source
-file.
+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 modify time equal to the
+source file's, it will be updated if the sizes are different.)
-In the currently implementation, a difference of file format is always
+In the current implementation of --update, 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 or a
symlink where the destination has a file, the transfer would occur
regardless of the timestamps. This might change in the future (feel
free to comment on this on the mailing list if you have an opinion).
+dit(bf(-k, --keep-dirs)) Tell the sending side to keep any directories that
+are encountered. Unlike --recursive, a directory's contents are not copied
+unless the directory was specified on the command-line as either "." or a
+name with a trailing slash (e.g. "foo/"). Without this option or the
+--recursive option, rsync will skip all directories it encounters (and
+output a message to that effect for each one).
+
dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
pointing to a directory, it will be treated as matching a directory
from the sender.
dit(bf(--inplace)) This causes rsync not to create a new copy of the file
and then move it into place. Instead rsync will overwrite the existing
-file, meaning that the rsync algorithm can't extract the full amount of
-network reduction it might otherwise (since it does not yet try to sort
-data matches -- a future version may improve this).
+file, meaning that the rsync algorithm can't accomplish the full amount of
+network reduction it might be able to otherwise (since it does not yet try
+to sort data matches). One exception to this is if you combine the option
+with --backup, since rsync is smart enough to use the backup file as the
+basis file for the transfer.
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 --partial (since an interrupted transfer does not delete
-the file), but conflicts with --partial-dir, --compare-dest, --copy-dest, and
---link-dest (a future rsync version will hopefully update the protocol to
-remove some of these restrictions).
+the file), but conflicts with --partial-dir. Prior to rsync 2.6.4
+--inplace was also incompatible with --compare-dest, --copy-dest, and
+--link-dest.
WARNING: The file's data will be in an inconsistent state during the
transfer (and possibly afterward if the transfer gets interrupted), so you
should not use this option to update files that are in use. Also note that
-rsync will be unable to update a file inplace that is not writable by the
+rsync will be unable to update a file in-place that is not writable by the
receiving user.
dit(bf(-l, --links)) When symlinks are encountered, recreate the
suffixed with a letter to indicate a size multiplier (K, M, or G) and
may be a fractional value (e.g. "--max-size=1.5m").
-dit(bf(--delete)) This tells rsync to delete any files on the receiving
-side that aren't on the sending side. Files that are excluded from
-transfer are excluded from being deleted unless you use --delete-excluded.
+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 those files, not
+the files' parent directory. Files that are excluded from transfer are
+excluded from being deleted unless you use --delete-excluded.
-This option has no effect if directory recursion is not selected.
+This option has no effect unless directory recursion is enabled.
This option can be dangerous if used incorrectly! It is a very good idea
-to run first using the dry run option (-n) to see what files would be
+to run first using the --dry-run option (-n) to see what files would be
deleted to make sure important files aren't listed.
-If the sending side detects any I/O errors then the deletion of any
+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 --ignore-errors option.
-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 --exclude).
-Implies --delete.
-
dit(bf(--delete-after)) By default rsync does file deletions on the
receiving side before transferring files to try to ensure that there is
sufficient space on the receiving filesystem. If you want to delete
after transferring, use the --delete-after switch. Implies --delete.
+One reason to use --delete-after is to avoid a delay before the start of
+the transfer (while the receiving side is scanned for deletions) as this
+delay might cause the transfer to timeout.
+
+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 --exclude).
+Implies --delete.
+
dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
even when there are I/O errors.
Note that rsync versions prior to 2.6.1 had a bug that could prevent
--link-dest from working properly for a non-root user when -o was specified
-(or implied by -a). If the receiving rsync is not new enough, you can work
-around this bug by avoiding the -o option.
+(or implied by -a). You can work-around this bug by avoiding the -o option
+when sending to an old rsync.
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
timeout in seconds. If no data is transferred for the specified time
then rsync will exit. The default is 0, which means no timeout.
+dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
+rather than the default of 873. This is only needed if you are using the
+double-colon (::) syntax to connect with an rsync daemon (since the URL
+syntax has a way to specify the port as a part of the URL). See also this
+option in the --daemon mode section.
+
dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching
a remote shell transport. If the remote shell is either rsh or remsh,
rsync defaults to using
data over the wire and data being matched locally), and the estimated time
remaining in this transfer.
-After the a file is complete, it the data looks like this:
+After a file is complete, the data looks like this:
verb(
1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396)
dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
when creating sockets. This only affects sockets that rsync has direct
control over, such as the outgoing socket when directly contacting an
-rsync daemon (see also these options in the --daemon mode section).
+rsync daemon. See also these options in the --daemon mode section.
dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer
NUM. This 4 byte checksum seed is included in each block and file
when run as a daemon with the --daemon option or when connecting to a
rsync server. The --address option allows you to specify a specific IP
address (or hostname) to bind to. This makes virtual hosting possible
-in conjunction with the --config option.
+in conjunction with the --config option. See also the "address" global
+option in the rsyncd.conf manpage.
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second for the data the daemon sends.
debugger. This option has no effect if rsync is run from inetd or
sshd.
-dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
-rather than the default port 873.
+dit(bf(--port=PORT)) This specifies an alternate TCP port number for the
+daemon to listen on rather than the default of 873. See also the "port"
+global option in the rsyncd.conf manpage.
dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
when creating the incoming sockets that the rsync daemon will use to
Note that, when using the --recursive (-r) option (which is implied by -a),
every subcomponent of
every path is visited from the top down, so include/exclude patterns get
-applied recursively to each subcomponent.
+applied recursively to each subcomponent's full name (e.g. to include
+"/foo/bar/baz" the subcomponents "/foo" and "/foo/bar" must not be excluded).
The exclude patterns actually short-circuit the directory traversal stage
when rsync finds the files to send. If a pattern excludes a particular
parent directory, it can render a deeper include pattern ineffectual