-H, --hard-links preserve hard links
-K, --keep-dirlinks treat symlinked dir on receiver as dir
-p, --perms preserve permissions
+ -E, --executability preserve executability
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
The order of the options is important: if you specify bf(--no-r -a), the
bf(-r) option would end up being turned on, the opposite of bf(-a --no-r).
Note also that the side-effects of the bf(--files-from) option are NOT
-positional, as it affects the default state of several options and sligntly
+positional, as it affects the default state of several options and slightly
changes the meaning of bf(-a) (see the bf(--files-from) option for more
details).
Note that if you don't specify bf(--backup-dir), (1) 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
+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
deleted. Note that if you are supplying your own filter rules, you may
"disk" is actually a networked filesystem). This is the default when both
the source and destination are specified as local paths.
-dit(bf(-p, --perms)) This option causes rsync to set the destination
-permissions to be the same as the source permissions.
+dit(bf(-p, --perms)) This option causes the receiving rsync to set the
+destination permissions to be the same as the source permissions. (See
+also the bf(--chmod) option for a way to modify what rsync considers to
+be the source permissions.)
-Without this option, all existing files (including updated files) retain
-their existing permissions, while each new file gets its permissions set
-based on the source file's permissions, but masked by the receiving end's
-umask setting
-(which is the same behavior as other file-copy utilities, such as cp).
+When this option is em(off), permissions are set as follows:
+
+quote(itemize(
+ 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).
+))
+
+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).
+
+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.
+
+quote(itemize(
+ it() To make a file non-executable, rsync turns off all its 'x'
+ permissions.
+ it() To make a file executable, rsync turns on each 'x' permission that
+ has a corresponding 'r' permission enabled.
+))
+
+If bf(--perms) is enabled, this option is ignored.
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
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 the listed "chmod" pattern
-to the permission of the files on the destination. In addition to the normal
-parsing rules specified in the chmod 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:
+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.
+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.
dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
even when there are I/O errors.
-dit(bf(--force)) This option tells rsync to delete directories even if
-they are not empty when they are to be replaced by non-directories. This
-is only relevant without bf(--delete) because deletions are now done depth-first.
-Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect.
+dit(bf(--force)) This option tells rsync to delete a non-empty directory
+when it is to be replaced by a non-directory. This is only relevant if
+deletions are not active (see bf(--delete) for details).
+
+Note for older rsync versions: bf(--force) used to still be required when
+using bf(--delete-after), and it used to be non-functional unless the
+bf(--recursive) option was also enabled.
dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
files or directories (NUM must be non-zero).
file are split on whitespace).
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
-the temporary files in the receiving directory.
+scratch directory when creating temporary copies of the files transferred
+on the receiving side. The default behavior is to create each temporary
+file in the same directory as the associated destination file.
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.
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
destination file, which means that the destination file will contain
-truncated data during this copy. If this were not done this way -- for
-instance, if the destination file were first removed, a copy made to a
-temp-file in the destination dir, and that file renamed over the top of the
-destination file -- the old file could still be taking up disk space (if
-someone had it open), and thus the copy could fail due to lack of space.
+truncated data during this copy. If this were not done this way (even if
+the destination file were first removed, the data locally copied to a
+temporary file in the destination directory, and then renamed into place)
+it would be possible for the old file to continue taking up disk space (if
+someone had it open), and thus there might not be enough room to fit the
+new version on the disk at the same time.
If you are using this option for reasons other than a shortage of disk
space, you may wish to combine it with the bf(--delay-updates) option,
-which will ensure that all copied files go into a subdirectory of the
-destination dir, awaiting the end of the transfer.
+which will ensure that all copied files get put into subdirectories in the
+destination hierarchy, awaiting the end of the transfer. If you don't
+have enough room to duplicate all the arriving files on the destination
+partition, another way to tell rsync that you aren't overly concerned
+about disk space is to use the bf(--partial-dir) option with a relative
+path; because this tells rsync that it is OK to stash off a copy of a
+single file in a subdir in the destination hierarchy, rsync will use the
+partial-dir as a staging area to bring over the copied file, and then
+rename it into place from there. (Specifying a bf(--partial-dir) with
+an absolute path does not have this side-effect.)
dit(bf(-y, --fuzzy)) This option tells rsync that it should look for a
basis file for any destination file that is missing. The current algorithm
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(UXcstpog)), where bf(U) is replaced by the
+The "%i" escape has a cryptic output that is 8 letters long. The general
+format is like the string bf(YXcstpog), where bf(Y) is replaced by the
kind 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.
-The update types that replace the bf(U) are as follows:
+The update types that replace the bf(Y) are as follows:
quote(itemize(
it() A bf(<) means that a file is being transferred to the remote host
output of "%i".
The bf(--verbose) option implies a format of "%n%L", but you can use
-bf(--log-format) without bv(--verbose) if you like, or you can override
+bf(--log-format) without bf(--verbose) if you like, or you can override
the format of its per-file output using this option.
Rsync will output the log-format string prior to a file's transfer unless
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff