-K, --keep-dirlinks treat symlinked dir on receiver as dir
-p, --perms preserve permissions
-E, --executability preserve executability
+ --chmod=CHMOD change destination permissions
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
-t, --times preserve times
-O, --omit-dir-times omit directories when preserving times
--super receiver attempts super-user activities
- --chmod=CHMOD change destination permissions
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy files whole (without rsync algorithm)
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'
If bf(--perms) is enabled, this option is ignored.
+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
+that the sending side supplied for the file, which means that this option
+can seem to have no effect on existing files if bf(--perms) is not enabled.
+
+In addition to the normal parsing rules specified in the bf(chmod)(1)
+manpage, you can specify an item that should only apply to a directory by
+prefixing it with a 'D', or specify an item that should only apply to a
+file by prefixing it with a 'F'. For example:
+
+quote(--chmod=Dg+s,ug+w,Fo-w,+X)
+
+It is also legal to specify multiple bf(--chmod) options, as each
+additional option is just appended to the list of changes to make.
+
+See the bf(--perms) and bf(--executability) options for how the resulting
+permission value can be applied to the files in the transfer.
+
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
destination file to be the same as the source file. By default, the
preservation is done by name, but may fall back to using the ID number
being running as the super-user. To turn off super-user activities, the
super-user can use bf(--no-super).
-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
-that the sending side supplied for the file, which means that this option
-can seem to have no effect on existing files if bf(--perms) is not enabled.
-
-In addition to the normal parsing rules specified in the bf(chmod)(1)
-manpage, you can specify an item that should only apply to a directory by
-prefixing it with a 'D', or specify an item that should only apply to a
-file by prefixing it with a 'F'. For example:
-
-quote(--chmod=Dg+s,ug+w,Fo-w,+X)
-
-It is also legal to specify multiple bf(--chmod) options, as each
-additional option is just appended to the list of changes to make.
-
-See the bf(--perms) and bf(--executability) options for how the resulting
-permission value can be applied to the files in the transfer.
-
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.
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