--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
than using bf(--delete-after).
Incremental recursion can be disabled using the bf(--no-inc-recursive)
-option or its shorter bf(--no-ir) alias.
+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
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
If incremental recursion is active (see bf(--recursive)), rsync may transfer
a missing hard-linked file before it finds that another link for the file
-exists elsewhere in the hierarchy. One way to avoid this is to disable
-incremental recursion using the bf(--no-ir) option.
+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
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. This nonstandard option only
-works if the remote rsync also supports it. bf(--acls) implies bf(--perms).
+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. This will work
-only if the remote machine's rsync also supports this option.
+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
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)
and bf(--fake-super) options).
-Without this option, the owner is set to the invoking user on the
-receiving side.
+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
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 a
-special extended attribute that is attached to each file (as needed). This
+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 withou 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
Since there is only one "side" in a local copy, this option affects both
the sending and recieving of files. You'll need to specify a copy using
-"localhost" if you need to avoid this. Note, however, that it is always
-safe to copy from some non-fake-super files into some fake-super files
-using a local bf(--fake-super) command because the non-fake source files
-will just have their normal attributes.
+"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).
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
The default setting of this option is site-specific, and can also be
affected via the RSYNC_ICONV environment variable.
+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), in a files-from file, nor those
-specified on the command line. It is up to you to ensure that you're
-requesting the right names from a remote server, and you can specify
-extra include/exclude rules if there are filename differences on the
-two sides that need to be accounted for. (In the future there may be
-a way to specify a UTF-8 filter rule that gets auto-converted to the
-local side's character set.)
+(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.
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
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff