mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(6 Nov 2006)()()
-manpagename(rsync)(faster, flexible replacement for rcp)
+manpage(rsync)(1)(17 May 2008)()()
+manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
manpagesynopsis()
-rsync [OPTION]... SRC [SRC]... DEST
+verb(Local: rsync [OPTION...] SRC... [DEST]
-rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
+Access via remote shell:
+ Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
+ Push: rsync [OPTION...] SRC... [USER@]HOST:DEST
-rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
+Access via rsync daemon:
+ Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
+ rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
+ Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
+ rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)
-rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
-
-rsync [OPTION]... SRC
-
-rsync [OPTION]... [USER@]HOST:SRC [DEST]
-
-rsync [OPTION]... [USER@]HOST::SRC [DEST]
-
-rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
+Usages with just one SRC arg and no DEST arg will list the source files
+instead of copying.
manpagedescription()
-rsync is a program that behaves in much the same way that rcp does,
-but has many more options and uses the rsync remote-update protocol to
-greatly speed up file transfers when the destination file is being
-updated.
-
-The rsync remote-update protocol allows rsync to transfer just the
-differences between two sets of files across the network connection, using
-an efficient checksum-search algorithm described in the technical
-report that accompanies this package.
+Rsync is a fast and extraordinarily versatile file copying tool. It can
+copy locally, to/from another host over any remote shell, or to/from a
+remote rsync daemon. It offers a large number of options that control
+every aspect of its behavior and permit very flexible specification of the
+set of files to be copied. It is famous for its delta-transfer algorithm,
+which reduces the amount of data sent over the network by sending only the
+differences between the source files and the existing files in the
+destination. Rsync is widely used for backups and mirroring and as an
+improved copy command for everyday use.
+
+Rsync finds files that need to be transferred using a "quick check"
+algorithm (by default) that looks for files that have changed in size or
+in last-modified time. Any changes in the other preserved attributes (as
+requested by options) are made on the destination file directly when the
+quick check indicates that the file's data does not need to be updated.
Some of the additional features of rsync are:
manpagesection(ADVANCED USAGE)
-The syntax for requesting multiple files from a remote host involves using
-quoted spaces in the SRC. Some examples:
+The syntax for requesting multiple files from a remote host is done by
+specifying additional remote-host args in the same style as the first,
+or with the hostname omitted. For instance, all these work:
-quote(tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
+quote(tt(rsync -av host:file1 :file2 host:file{3,4} /dest/)nl()
+tt(rsync -av host::modname/file{1,2} host::modname/file3 /dest/)nl()
+tt(rsync -av host::modname/file1 ::modname/file{3,4}))
-This would copy file1 and file2 into /dest from an rsync daemon. Each
-additional arg must include the same "modname/" prefix as the first one,
-and must be preceded by a single space. All other spaces are assumed
-to be a part of the filenames.
+Older versions of rsync required using quoted spaces in the SRC, like these
+examples:
-quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest))
+quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest)nl()
+tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
-This would copy file1 and file2 into /dest using a remote shell. This
-word-splitting is done by the remote shell, so if it doesn't work it means
-that the remote shell isn't configured to split its args based on
-whitespace (a very rare setting, but not unknown). If you need to transfer
-a filename that contains whitespace, you'll need to either escape the
-whitespace in a way that the remote shell will understand, or use wildcards
-in place of the spaces. Two examples of this are:
+This word-splitting still works (by default) in the latest rsync, but is
+not as easy to use as the first method.
-quote(
-tt(rsync -av host:'file\ name\ with\ spaces' /dest)nl()
-tt(rsync -av host:file?name?with?spaces /dest)nl()
-)
+If you need to transfer a filename that contains whitespace, you can either
+specify the bf(--protect-args) (bf(-s)) option, or you'll need to escape
+the whitespace in a way that the remote shell will understand. For
+instance:
-This latter example assumes that your shell passes through unmatched
-wildcards. If it complains about "no match", put the name in quotes.
+quote(tt(rsync -av host:'file\ name\ with\ spaces' /dest))
manpagesection(CONNECTING TO AN RSYNC DAEMON)
your web proxy. Note that your web proxy's configuration must support
proxy connections to port 873.
+You may also establish a daemon connection using a program as a proxy by
+setting the environment variable RSYNC_CONNECT_PROG to the commands you
+wish to run in place of making a direct socket connection. The string may
+contain the escape "%H" to represent the hostname specified in the rsync
+command (so use "%%" if you need a single "%" in your string). For
+example:
+
+verb( export RSYNC_CONNECT_PROG='ssh proxyhost nc %H 873'
+ rsync -av targethost1::module/src/ /dest/
+ rsync -av rsync:://targethost2/module/src/ /dest/ )
+
+The command specified above uses ssh to run nc (netcat) on a proxyhost,
+which forwards all data to port 873 (the rsync daemon) on the targethost
+(%H).
+
manpagesection(USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION)
It is sometimes useful to use various features of an rsync daemon (such as
-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)
+ -a, --archive archive mode; equals -rlptgoD (no -H,-A,-X)
--no-OPTION turn off an implied OPTION (e.g. --no-D)
-r, --recursive recurse into directories
-R, --relative use relative path names
-u, --update skip files that are newer on the receiver
--inplace update destination files in-place
--append append data onto shorter files
+ --append-verify --append w/old data in file checksum
-d, --dirs transfer directories without recursing
-l, --links copy symlinks as symlinks
-L, --copy-links transform symlink into referent file/dir
-p, --perms preserve permissions
-E, --executability preserve executability
--chmod=CHMOD affect file and/or directory permissions
+ -A, --acls preserve ACLs (implies -p)
+ -X, --xattrs preserve extended attributes
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
--specials preserve special files
-D same as --devices --specials
- -t, --times preserve times
- -O, --omit-dir-times omit directories when preserving times
+ -t, --times preserve modification times
+ -O, --omit-dir-times omit directories from --times
--super receiver attempts super-user activities
+ --fake-super store/recover privileged attrs using xattrs
-S, --sparse handle sparse files efficiently
- -n, --dry-run show what would have been transferred
- -W, --whole-file copy files whole (without rsync algorithm)
+ -n, --dry-run perform a trial run with no changes made
+ -W, --whole-file copy files whole (w/o delta-xfer algorithm)
-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
--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
--delay-updates put all updated files into place at end
-m, --prune-empty-dirs prune empty directory chains from file-list
--numeric-ids don't map uid/gid values by user/group name
- --timeout=TIME set I/O timeout in seconds
+ --timeout=SECONDS set I/O timeout in seconds
+ --contimeout=SECONDS set daemon connection timeout in seconds
-I, --ignore-times don't skip files that match size and time
--size-only skip files that match in size
--modify-window=NUM compare mod-times with reduced accuracy
--link-dest=DIR hardlink to files in DIR when unchanged
-z, --compress compress file data during the transfer
--compress-level=NUM explicitly set compression level
+ --skip-compress=LIST skip compressing files with suffix in LIST
-C, --cvs-exclude auto-ignore files in the same way CVS does
-f, --filter=RULE add a file-filtering RULE
-F same as --filter='dir-merge /.rsync-filter'
--include-from=FILE read include patterns from FILE
--files-from=FILE read list of source-file names from FILE
-0, --from0 all *from/filter files are delimited by 0s
+ -s, --protect-args no space-splitting; wildcard chars only
--address=ADDRESS bind address for outgoing socket to daemon
--port=PORT specify double-colon alternate port number
--sockopts=OPTIONS specify custom TCP options
--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
--only-write-batch=FILE like --write-batch but w/o updating dest
--read-batch=FILE read a batched update from FILE
--protocol=NUM force an older protocol version to be used
+ --iconv=CONVERT_SPEC request charset conversion of filenames
--checksum-seed=NUM set block/file checksum seed (advanced)
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
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.
+request the list of modules from the daemon.
dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
-already the same size and have the same modification time-stamp.
+already the same size and have the same modification timestamp.
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(--size-only) option, files will not be transferred if they have the same size,
-regardless of timestamp. This is useful when starting to use rsync
-after using another mirroring system which may not preserve timestamps
-exactly.
+dit(bf(--size-only)) This modifies rsync's "quick check" algorithm for
+finding files that need to be transferred, changing it from the default of
+transferring files with either a changed size or a changed last-modified
+time to just looking for files that have changed in size. This is useful
+when starting to use rsync after using another mirroring system which may
+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
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 forces the sender to checksum em(every)
-regular file using a 128-bit MD4 checksum. It does this during the initial
-file-system scan as it builds the list of all available files. The receiver
-then checksums its version of each file (if it exists and it has the same
-size as its sender-side counterpart) in order to decide which files need to
-be updated: files with either a changed size or a changed checksum are
-selected for transfer. Since this whole-file checksumming of all files on
-both sides of the connection occurs in addition to the automatic checksum
-verifications that occur during a file's transfer, this option can be quite
-slow.
-
-Note that rsync always verifies that each em(transferred) file was correctly
-reconstructed on the receiving side by checking its whole-file checksum, but
-that automatic after-the-transfer verification has nothing to do with this
+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
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
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 -- the full path name is preserved. To limit the amount of
-path information that is sent, you have a couple options: (1) 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:
+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/))
(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, use this idiom (which doesn't work with an
-rsync daemon):
+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()
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
-one side of the transfer, and a real directory on the other side.
+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"
preservation is to use the bf(--keep-dirlinks) option (which will also
affect symlinks to directories in the rest of the transfer).
-In a similar but opposite scenario, if the transfer of "path/foo/file" is
-requested and "path/foo" is a symlink on the sending side, running without
-bf(--no-implied-dirs) would cause rsync to transform "path/foo" on the
-receiving side into an identical symlink, and then attempt to transfer
-"path/foo/file", which might fail if the duplicated symlink did not point
-to a directory on the receiving side. Another way to avoid this sending of
-a symlink as an implied directory is to use bf(--copy-unsafe-links), or
-bf(--copy-dirlinks) (both of which also affect symlinks in the rest of the
-transfer -- see their descriptions for full details).
+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
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 "Pp *~")). 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
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
+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.)
-In the current implementation of bf(--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(--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 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 bf(--backup), since rsync is smart enough to use the backup file as the
-basis file for the transfer.
+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
Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest)
and bf(--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 in-place that is not writable by the
-receiving user.
-
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 that is not true, the file will fail the checksum test, and the
-resend will do a normal bf(--inplace) update to correct the mismatched data.
-Only files on the receiving side that are shorter than the corresponding
-file on the sending side (as well as new files) are sent.
-Implies bf(--inplace), but does not conflict with bf(--sparse) (though the
-bf(--sparse) option will be auto-disabled if a resend of the already-existing
-data is required).
+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
output a message to that effect for each one). If you specify both
bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence.
+The bf(--dirs) option is implied by the bf(--files-from) option
+or the bf(--list-only) option (including an implied
+bf(--list-only) usage) if bf(--recursive) wasn't specified (so that
+directories are seen in the listing). Specify bf(--no-dirs) (or bf(--no-d))
+if you want to turn this off.
+
+There is also a backward-compatibility helper option, bf(--old-dirs) (or
+bf(--old-d)) that tells rsync to use a hack of "-r --exclude='/*/*'" to get
+an older rsync to list a single directory without recursing.
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
also ignored. Using this option in conjunction with bf(--relative) may
give unexpected results.
-dit(bf(-K, --copy-dirlinks)) This option causes the sending side to treat
+dit(bf(-k, --copy-dirlinks)) This option causes the sending side to treat
a symlink to a directory as though it were a real directory. This is
useful if you don't want symlinks to non-directories to be affected, as
they would be using bf(--copy-links).
bf(--keep-dirlinks), the receiver keeps the symlink and "file" ends up in
"bar".
+One note of caution: if you use bf(--keep-dirlinks), you must trust all
+the symlinks in the copy! If it is possible for an untrusted user to
+create their own symlink to any directory, the user could then (on a
+subsequent copy) replace the symlink with a real directory and affect the
+content of whatever directory the symlink references. For backup copies,
+you are better off using something like a bind mount instead of a symlink
+to modify your receiving hierarchy.
+
See also bf(--copy-dirlinks) for an analogous option for the sending side.
dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in
side. Without this option, hard-linked files in the transfer are treated
as though they were separate files.
-Note that rsync can only detect hard links if both parts of the link
-are in the list of files being sent.
+When you are updating a non-empty destination, this option only ensures
+that files that are hard-linked together on the source are hard-linked
+together on the destination. It does NOT currently endeavor to break
+already existing hard links on the destination that do not exist between
+the source files. Note, however, that if one or more extra-linked files
+have content changes, they will become unlinked when updated (assuming you
+are not using the bf(--inplace) option).
+
+Note that rsync can only detect hard links between files that are inside
+the transfer set. If rsync updates a file that has extra hard-link
+connections to files outside the transfer, that linkage will be broken. If
+you are tempted to use the bf(--inplace) option to avoid this breakage, be
+very careful that you know how your files are being updated so that you are
+certain that no unintended changes happen due to lingering hard links (and
+see the bf(--inplace) option for more caveats).
+
+If incremental recursion is active (see bf(--recursive)), rsync may transfer
+a missing hard-linked file before it finds that another link for that contents
+exists elsewhere in the hierarchy. This does not affect the accuracy of
+the transfer, just its efficiency. One way to avoid this is to disable
+incremental recursion using the bf(--no-inc-recursive) option.
dit(bf(-p, --perms)) This option causes the receiving rsync to set the
destination permissions to be the same as the source permissions. (See
permissions, though the bf(--executability) option might change just
the execute permission for the file.
it() New files get their "normal" permission bits set to the source
- file's permissions masked with the receiving end's umask setting, and
+ file's permissions masked with the receiving directory's default
+ permissions (either the receiving process's umask, or the permissions
+ specified via the destination directory's default ACL), and
their special permission bits disabled except in the case where a new
directory inherits a setgid bit from its parent directory.
))
bf(--perms) option is off and use bf(--chmod=ugo=rwX) (which ensures that
all non-masked bits get enabled). If you'd care to make this latter
behavior easier to type, you could define a popt alias for it, such as
-putting this line in the file ~/.popt (this defines the bf(-s) option,
+putting this line in the file ~/.popt (the following defines the bf(-Z) option,
and includes --no-g to use the default group of the destination dir):
-quote(tt( rsync alias -s --no-p --no-g --chmod=ugo=rwX))
+quote(tt( rsync alias -Z --no-p --no-g --chmod=ugo=rwX))
You could then use this new option in a command such as this one:
-quote(tt( rsync -asv src/ dest/))
+quote(tt( rsync -avZ src/ dest/))
-(Caveat: make sure that bf(-a) does not follow bf(-s), or it will re-enable
-the "--no-*" options.)
+(Caveat: make sure that bf(-a) does not follow bf(-Z), or it will re-enable
+the two "--no-*" options mentioned above.)
The preservation of the destination's setgid bit on newly-created
directories when bf(--perms) is off was added in rsync 2.6.7. Older rsync
versions erroneously preserved the three special permission bits for
newly-created files when bf(--perms) was off, while overriding the
-destination's setgid bit setting on a newly-created directory. (Keep in
-mind that it is the version of the receiving rsync that affects this
-behavior.)
+destination's setgid bit setting on a newly-created directory. Default ACL
+observance was added to the ACL patch for rsync 2.6.7, so older (or
+non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
+(Keep in mind that it is the version of the receiving rsync that affects
+these behaviors.)
dit(bf(-E, --executability)) This option causes rsync to preserve the
executability (or non-executability) of regular files when bf(--perms) is
If bf(--perms) is enabled, this option is ignored.
+dit(bf(-A, --acls)) This option causes rsync to update the destination
+ACLs to be the same as the source ACLs.
+The option also implies bf(--perms).
+
+The source and destination systems must have compatible ACL entries for this
+option to work properly. See the bf(--fake-super) option for a way to backup
+and restore ACLs that are not compatible.
+
+dit(bf(-X, --xattrs)) This option causes rsync to update the remote
+extended attributes to be the same as the local ones.
+
+For systems that support extended-attribute namespaces, a copy being done by a
+super-user copies all namespaces except system.*. A normal user only copies
+the user.* namespace. To be able to backup and restore non-user namespaces as
+a normal user, see the bf(--fake-super) option.
+
dit(bf(--chmod)) This option tells rsync to apply one or more
comma-separated "chmod" strings to the permission of the files in the
transfer. The resulting value is treated as though it was the permissions
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
destination file to be the same as the source file, but only if the
receiving rsync is being run as the super-user (see also the bf(--super)
-option to force rsync to attempt super-user activities).
-Without this option, the owner is set to the invoking user on the
-receiving side.
+and bf(--fake-super) options).
+Without this option, the owner of new and/or transferred files are set to
+the invoking user on the receiving side.
The preservation of ownership will associate matching names by default, but
may fall back to using the ID number in some circumstances (see also the
dit(bf(--devices)) This option causes rsync to transfer character and
block device files to the remote system to recreate these devices.
This option has no effect if the receiving rsync is not run as the
-super-user and bf(--super) is not specified.
+super-user (see also the bf(--super) and bf(--fake-super) options).
dit(bf(--specials)) This option causes rsync to transfer special files
such as named sockets and fifos.
option is not used, the optimization that excludes files that have not been
modified cannot be effective; in other words, a missing bf(-t) or bf(-a) will
cause the next transfer to behave as if it used bf(-I), causing all files to be
-updated (though the rsync algorithm will make the update fairly efficient
+updated (though rsync's delta-transfer algorithm will make the update fairly efficient
if the files haven't actually changed, you're much better off using bf(-t)).
dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
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.
filesystem. It doesn't seem to handle seeks over null regions
correctly and ends up corrupting the files.
-dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
-instead it will just report the actions it would have taken.
-
-dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
+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
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 to delete extraneous files).
+(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
-directores, or nothing would get done). See also bf(--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
include/exclude modifiers in the FILTER RULES section).
Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
-was in effect. Beginning with 2.6.7, deletions will also occur when bf(--dirs)
-(bf(-d)) is in effect, but only for directories whose contents are being copied.
+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 run first using the bf(--dry-run) option (bf(-n)) to see what files would be
-deleted to make sure important files aren't listed.
+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
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 currently choose the
-bf(--delete-before) algorithm. A future version may change this to choose the
-bf(--delete-during) algorithm. See also bf(--delete-after).
+--delete-WHEN options are specified, rsync will choose the
+bf(--delete-during) algorithm when talking to an 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. This is the default if bf(--delete)
-or bf(--delete-excluded) is specified without one of the --delete-WHEN options.
+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).
+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. This is
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 during the transfer, and then removed after the transfer
+completes. 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).
+
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.
+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
bf(--recursive) option was also enabled.
dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
-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.
+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
See the bf(--max-size) option for a description of SIZE.
dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
-the rsync algorithm to a fixed value. It is normally selected based on
+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
One tricky example is to set a different default directory on the remote
machine for use with the bf(--relative) option. For instance:
-quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/))
+quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/))
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
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/ .bzr/)))
+.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del-*
+*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .bzr/)))
then, files listed in a $HOME/.cvsignore are added to the list and any
files listed in the CVSIGNORE environment variable (all cvsignore names
most useful in combination with a recursive transfer.
You may use as many bf(--filter) options on the command line as you like
-to build up the list of files to exclude.
+to build up the list of files to exclude. If the filter contains whitespace,
+be sure to quote it so that the shell gives the rule to rsync as a single
+argument. The text below also mentions that you can use an underscore to
+replace the space that separates a rule from its arg.
See the FILTER RULES section for detailed information on this option.
bf(--files-from), as does bf(--no-R) and all other options).
))
-The file names that are read from the FILE are all relative to the
+The filenames that are read from the FILE are all relative to the
source dir -- any leading slashes are removed and no ".." references are
allowed to go higher than the source dir. For example, take this
command:
It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore
file are split on whitespace).
+If the bf(--iconv) and bf(--protect-args) options are specified and the
+bf(--files-from) filenames are being sent from one host to another, the
+filenames will be translated from the sending host's charset to the
+receiving host's charset.
+
+dit(bf(-s, --protect-args)) This option sends all filenames and some options to
+the remote rsync without allowing the remote shell to interpret them. This
+means that spaces are not split in names, and any non-wildcard special
+characters are not translated (such as ~, $, ;, &, etc.). Wildcards are
+expanded on the remote host by rsync (instead of the shell doing it).
+
+If you use this option with bf(--iconv), the args will also be translated
+from the local to the remote character-set. The translation happens before
+wild-cards are expanded. See also the bf(--files-from) option.
+
dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
scratch directory when creating temporary copies of the files transferred
on the receiving side. The default behavior is to create each temporary
This option is most often used when the receiving disk partition does not
have enough free space to hold a copy of the largest file in the transfer.
-In this case (i.e. when the scratch directory in on a different disk
+In this case (i.e. when the scratch directory is on a different disk
partition), rsync will not be able to rename each received temporary file
over the top of the associated destination file, but instead must copy it
into place. Rsync does this by copying the file over the top of the
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.
+This option works best when copying into an empty destination hierarchy, as
+rsync treats existing files as definitive (so it never looks in the link-dest
+dirs when a destination file already exists), and as malleable (so it might
+change the attributes of a destination file, which affects all the hard-linked
+versions).
+
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
because it takes advantage of the implicit information in the matching data
blocks that are not explicitly sent over the connection.
+See the bf(--skip-compress) option for the default list of file suffixes
+that will not be compressed.
+
dit(bf(--compress-level=NUM)) Explicitly set the compression level to use
(see bf(--compress)) instead of letting it default. If NUM is non-zero,
the bf(--compress) option is implied.
+dit(bf(--skip-compress=LIST)) Override the list of file suffixes that will
+not be compressed. The bf(LIST) should be one or more file suffixes
+(without the dot) separated by slashes (/).
+
+You may specify an empty string to indicate that no file should be skipped.
+
+Simple character-class matching is supported: each must consist of a list
+of letters inside the square brackets (e.g. no special classes, such as
+"[:alpha:]", are supported).
+
+The characters asterisk (*) and question-mark (?) have no special meaning.
+
+Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules
+matches 2 suffixes):
+
+verb( --skip-compress=gz/jpg/mp[34]/7z/bz2)
+
+The default list of suffixes that will not be compressed is this (several
+of these are newly added for 3.0.0):
+
+verb( gz/zip/z/rpm/deb/iso/bz2/t[gb]z/7z/mp[34]/mov/avi/ogg/jpg/jpeg)
+
+This list will be replaced by your bf(--skip-compress) list in all but one
+situation: a copy from a daemon rsync will add your skipped suffixes to
+its list of non-compressing files (and its list may be configured to a
+different default).
+
dit(bf(--numeric-ids)) With this option rsync will transfer numeric group
and user IDs rather than using user and group names and mapping them
at both ends.
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(--contimeout)) This option allows you to set the amount of time
+that rsync will wait for its connection to an rsync daemon to succeed.
+If the timeout is reached, rsync exits with an error.
+
dit(bf(--address)) By default rsync will bind to the wildcard address when
connecting to an rsync daemon. The bf(--address) option allows you to
specify a specific IP address (or hostname) to bind to. See also this
with older versions of rsync, but that also turns on the output of other
verbose messages).
-The "%i" escape has a cryptic output that is 9 letters long. The general
-format is like the string bf(YXcstpogz), where bf(Y) is replaced by the
+The "%i" escape has a cryptic output that is 11 letters long. The general
+format is like the string bf(YXcstpoguax), where bf(Y) is replaced by the
type of update being done, bf(X) is replaced by the file-type, and the
other letters represent attributes that may be output if they are being
modified.
bf(--hard-links)).
it() A bf(.) means that the item is not being updated (though it might
have attributes that are being modified).
+ it() A bf(*) means that the rest of the itemized-output area contains
+ a message (e.g. "deleting").
))
The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a
The attribute that is associated with each letter is as follows:
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
+ it() A bf(c) means either that a regular file has a different checksum
+ (requires bf(--checksum)) or that a symlink, device, or special file has
+ a changed value.
+ Note that if you are sending files to an rsync prior to 3.0.1, this
+ change flag will be present only for checksum-differing regular files.
+ it() A bf(s) means the size of a regular file is different and will be updated
by the file transfer.
it() A bf(t) means the modification time is different and is being updated
to the sender's value (requires bf(--times)). An alternate value of bf(T)
- means that the time will be set to the transfer time, which happens
- anytime a symlink is transferred, or when a file or device is transferred
- without bf(--times).
+ means that the modification time will be set to the transfer time, which happens
+ when a file/symlink/device is updated without bf(--times) and when a
+ symlink is changed and the receiver can't set its time.
+ (Note: when using an rsync 3.0.0 client, you might see the bf(s) flag combined
+ with bf(t) instead of the proper bf(T) flag for this time-setting failure.)
it() A bf(p) means the permissions are different and are being updated to
the sender's value (requires bf(--perms)).
it() An bf(o) means the owner is different and is being updated to the
sender's value (requires bf(--owner) and super-user privileges).
it() A bf(g) means the group is different and is being updated to the
sender's value (requires bf(--group) and the authority to set the group).
- it() The bf(z) slot is reserved for future use.
+ it() The bf(u) slot is reserved for future use.
+ it() The bf(a) means that the ACL information changed.
+ it() The bf(x) means that the extended attribute information changed.
))
One other output is possible: when deleting files, the "%i" will output
in the rsyncd.conf manpage.
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
-on the file transfer, allowing you to tell how effective the rsync
+on the file transfer, allowing you to tell how effective rsync's delta-transfer
algorithm is for your data.
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
- were updated via the rsync algorithm, which does not include created
+ were updated via rsync's delta-transfer algorithm, which does not include created
dirs, symlinks, etc.
it() bf(Total file size) is the total sum of all file sizes in the transfer.
This does not count any size for directories or special files, but does
Note that if bf(--whole-file) is specified (or implied), any partial-dir
file that is found for a file that is being updated will simply be removed
(since
-rsync is sending files without using the incremental rsync algorithm).
+rsync is sending files without using rsync's delta-transfer algorithm).
Rsync will create the em(DIR) if it is missing (just the last dir -- not
the whole path). This makes it easy to use a relative path (such as
sending of any partial-dir files that may exist on the sending side, and
will also prevent the untimely deletion of partial-dir items on the
receiving side. An example: the above bf(--partial-dir) option would add
-the equivalent of "bf(--exclude=.rsync-partial/)" at the end of any other
+the equivalent of "bf(-f '-p .rsync-partial/')" at the end of any other
filter rules.
If you are supplying your own exclude rules, you may need to add your own
bf(--partial-dir) option, that directory will be used instead. See the
comments in the bf(--partial-dir) section for a discussion of how this
".~tmp~" dir will be excluded from the transfer, and what you can do if
-you wnat rsync to cleanup old ".~tmp~" dirs that might be lying around.
+you want rsync to cleanup old ".~tmp~" dirs that might be lying around.
Conflicts with bf(--inplace) and bf(--append).
This option uses more memory on the receiving side (one bit per file
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
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
+These statistics can be misleading if rsync's delta-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
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.
+
+This option does not supply a password to a remote shell transport such as
+ssh; to learn how to do that, consult the remote shell's documentation.
+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
arg and no destination specified, so its main uses are: (1) to turn a copy
command that includes a
-destination arg into a file-listing command, (2) to be able to specify more
-than one local source arg (note: be sure to include the destination), or
-(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that
-rsync usually uses as a compatibility kluge when generating a non-recursive
-listing. Caution: keep in mind that a source arg with a wild-card is expanded
-by the shell into multiple args, so it is never safe to try to list such an arg
+destination arg into a file-listing command, or (2) to be able to specify
+more than one source arg (note: be sure to include the destination).
+Caution: keep in mind that a source arg with a wild-card is expanded by the
+shell into multiple args, so it is never safe to try to list such an arg
without using this option. For example:
verb( rsync -av --list-only foo* dest/)
+Compatibility note: when requesting a remote listing of files from an rsync
+that is version 2.6.3 or older, you may encounter an error if you ask for a
+non-recursive listing. This is because a file listing implies the bf(--dirs)
+option w/o bf(--recursive), and older rsyncs don't have that option. To
+avoid this problem, either specify the bf(--no-dirs) option (if you don't
+need to expand a directory's content), or turn on recursion and exclude
+the content of subdirectories: bf(-r --exclude='/*/*').
+
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
batch file to force the older protocol version to be used in the batch
file (assuming you can't upgrade the rsync on the reading system).
+dit(bf(--iconv=CONVERT_SPEC)) Rsync can convert filenames between character
+sets using this option. Using a CONVERT_SPEC of "." tells rsync to look up
+the default character-set via the locale setting. Alternately, you can
+fully specify what conversion to do by giving a local and a remote charset
+separated by a comma in the order bf(--iconv=LOCAL,REMOTE), e.g.
+bf(--iconv=utf8,iso88591). This order ensures that the option
+will stay the same whether you're pushing or pulling files.
+Finally, you can specify either bf(--no-iconv) or a CONVERT_SPEC of "-"
+to turn off any conversion.
+The default setting of this option is site-specific, and can also be
+affected via the RSYNC_ICONV environment variable.
+
+For a list of what charset names your local iconv library supports, you can
+run "iconv --list".
+
+If you specify the bf(--protect-args) option (bf(-s)), rsync will translate
+the filenames you specify on the command-line that are being sent to the
+remote host. See also the bf(--files-from) option.
+
+Note that rsync does not do any conversion of names in filter files
+(including include/exclude files). It is up to you to ensure that you're
+specifying matching rules that can match on both sides of the transfer.
+For instance, you can specify extra include/exclude rules if there are
+filename differences on the two sides that need to be accounted for.
+
+When you pass an bf(--iconv) option to an rsync daemon that allows it, the
+daemon uses the charset specified in its "charset" configuration parameter
+regardless of the remote charset you actually pass. Thus, you may feel free to
+specify just the local charset for a daemon transfer (e.g. bf(--iconv=utf8)).
+
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 bf(--daemon) mode section.
+If rsync was complied without support for IPv6, the bf(--ipv6) option
+will have no effect. The bf(--version) output will tell you if this
+is the case.
+
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
MD4 checksum calculation. By default the checksum seed is generated
an "address already in use" error when nothing else is using the port,
try specifying bf(--ipv6) or bf(--ipv4) when starting the daemon).
+If rsync was complied without support for IPv6, the bf(--ipv6) option
+will have no effect. The bf(--version) output will tell you if this
+is the case.
+
dit(bf(-h, --help)) When specified after bf(--daemon), print a short help
page describing the options available for starting an rsync daemon.
enddit()
particular spot in the hierarchy of files, otherwise it is matched
against the end of the pathname. This is similar to a leading ^ in
regular expressions.
- Thus "/foo" would match a file named "foo" at either the "root of the
+ Thus "/foo" would match a name of "foo" at either the "root of the
transfer" (for a global rule) or in the merge-file's directory (for a
per-directory rule).
- An unqualified "foo" would match any file or directory named "foo"
- anywhere in the tree because the algorithm is applied recursively from
- the
+ An unqualified "foo" would match a name of "foo" anywhere in the
+ tree because the algorithm is applied recursively from the
top down; it behaves as if each path component gets a turn at being the
- end of the file name. Even the unanchored "sub/foo" would match at
+ end of the filename. Even the unanchored "sub/foo" would match at
any point in the hierarchy where a "foo" was found within a directory
named "sub". See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for
a full discussion of how to specify a pattern that matches at the root
of the transfer.
it() if the pattern ends with a / then it will only match a
- directory, not a file, link, or device.
+ directory, not a regular file, symlink, or device.
it() rsync chooses between doing a simple string match and wildcard
matching by checking if the pattern contains one of these three wildcard
characters: '*', '?', and '[' .
can actually be any portion of a path from the starting directory on
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
+ "dir_name/" had been specified) and everything in the directory
(as if "dir_name/**" had been specified). This behavior was added in
version 2.6.7.
)
Here are some examples of exclude/include matching:
itemization(
- it() "- *.o" would exclude all filenames matching *.o
+ it() "- *.o" would exclude all names matching *.o
it() "- /foo" would exclude a file (or directory) named foo in the
transfer-root directory
it() "- foo/" would exclude any directory named foo
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)
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
dit(bf(24)) Partial transfer due to vanished source files
dit(bf(25)) The --max-delete limit stopped deletions
dit(bf(30)) Timeout in data send/receive
+dit(bf(35)) Timeout waiting for daemon connection
enddit()
manpagesection(ENVIRONMENT VARIABLES)
dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
ignore patterns in .cvsignore files. See the bf(--cvs-exclude) option for
more details.
+dit(bf(RSYNC_ICONV)) Specify a default bf(--iconv) setting using this
+environment variable.
dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
override the default shell used as the transport for rsync. Command line
options are permitted after the command name, just as in the bf(-e) option.
dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required
password allows you to run authenticated rsync connections to an rsync
daemon without user intervention. Note that this does not supply a
-password to a shell transport such as ssh.
+password to a remote shell transport such as ssh; to learn how to do that,
+consult the remote shell's documentation.
dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
are used to determine the default username sent to an rsync daemon.
If neither is set, the username defaults to "nobody".
see also the comments on the bf(--delete) option
-Please report bugs! See the website at
+Please report bugs! See the web site at
url(http://rsync.samba.org/)(http://rsync.samba.org/)
manpagesection(VERSION)
-This man page is current for version 2.6.9 of rsync.
+This man page is current for version 3.0.3pre2 of rsync.
manpagesection(INTERNAL OPTIONS)
url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
We would be delighted to hear from you if you like this program.
+Please contact the mailing-list at rsync@lists.samba.org.
This program uses the excellent zlib compression library written by
Jean-loup Gailly and Mark Adler.
manpagesection(THANKS)
-Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
-and David Bell for helpful suggestions, patches and testing of rsync.
-I've probably missed some people, my apologies if I have.
+Especial thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra,
+David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
+gone-but-not-forgotten compadre, J.W. Schultz.
-Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
-Martin Pool, Wayne Davison, J.W. Schultz.
+Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
+and David Bell. I've probably missed some people, my apologies if I have.
manpageauthor()
rsync was originally written by Andrew Tridgell and Paul Mackerras.
-Many people have later contributed to it.
+Many people have later contributed to it. It is currently maintained
+by Wayne Davison.
Mailing lists for support and development are available at
url(http://lists.samba.org)(lists.samba.org)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff