it() Existing files (including updated files) retain their existing
permissions, though the bf(--executability) option might change just
the execute permission for the file.
- it() Each new file gets its permissions set based on the source file's
- permissions, but masked by the receiving end's umask setting (including
- the stripping of the three special permission bits).
+ it() New files get their "normal" permission bits set to the source
+ file's permissions masked with the receiving end's umask setting, and
+ their special permission bits disabled except in the case where a new
+ directory inherits a setgid bit from its parent directory.
))
-
+
Thus, when bf(--perms) and bf(--executability) are both disabled,
rsync's behavior is the same as that of other file-copy utilities,
such as bf(cp)(1) and bf(tar)(1).
+In summary: to give destination files (both old and new) the source
+permissions, use bf(--perms). To give new files the destination-default
+permissions (while leaving existing files unchanged) make sure that the
+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):
+
+quote(tt( rsync alias -s --no-p --chmod=ugo=rwX))
+
+You could then use this new option in a command such as this one:
+
+quote(tt( rsync -asv src/ dest/))
+
+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.)
+
dit(bf(-E, --executability)) This option causes rsync to preserve the
executability (or non-executability) of regular files when bf(--perms) is
not enabled. A regular file is considered to be executable if at least one
-'x' is turned on in the source permissions.
+'x' is turned on in its permissions. When an existing destination file's
+executability differs from that of the corresponding source file, rsync
+modifies the destination file's permissions as follows:
quote(itemize(
it() To make a file non-executable, rsync turns off all its 'x'
through the hierarchy of each directory that the user specified, and also
the analogous recursion on the receiving side during deletion. Also keep
in mind that rsync treats a "bind" mount to the same device as being on the
-same filesystem.
+same filesystem.
If this option is repeated, rsync omits all mount-point directories from
the copy. Otherwise, it includes an empty directory at each mount-point it
partial-directory in the destination file's directory when needed, and then
remove it again when the partial file is deleted.
-If the partial-dir value is not an absolute path, rsync will also add a directory
-bf(--exclude) of this value at the end of all your existing excludes. This
-will prevent partial-dir files from being transferred and also prevent the
-untimely deletion of partial-dir items on the receiving side. An example:
-the above bf(--partial-dir) option would add an "bf(--exclude=.rsync-partial/)"
-rule at the end of any other filter rules. Note that if you are
-supplying your own exclude 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 your rules specify
-a trailing inclusion/exclusion of '*', the auto-added rule would never be
-reached).
+If the partial-dir value is not an absolute path, rsync will add an exclude
+rule at the end of all your existing excludes. This will prevent the
+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
+filter rules.
+
+If you are supplying your own exclude rules, you may need to add your own
+exclude/hide/protect rule for the partial-dir because (1) the auto-added
+rule may be ineffective at the end of your other rules, or (2) you may wish
+to override rsync's exclude choice. For instance, if you want to make
+rsync clean-up any left-over partial-dirs that may be lying around, you
+should specify bf(--delete-after) and add a "risk" filter rule, e.g.
+bf(-f 'R .rsync-partial/'). (Avoid using bf(--delete-before) or
+bf(--delete-during) unless you don't need rsync to use any of the
+left-over partial-dir data during the current run.)
IMPORTANT: the bf(--partial-dir) should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
succession. This attempts to make the updating of the files a little more
atomic. By default the files are placed into a directory named ".~tmp~" in
each file's destination directory, but if you've specified the
-bf(--partial-dir) option, that directory will be used instead.
+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.
Conflicts with bf(--inplace) and bf(--append).
This option uses more memory on the receiving side (one bit per file
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff