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 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).
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff