-H, --hard-links preserve hard links
-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)
--partial keep partially transferred files
--partial-dir=DIR put a partially transferred file into DIR
--delay-updates put all updated files into place at end
+ -m, --prune-empty-dirs prune empty directory chains from file-list
--numeric-ids don't map uid/gid values by user/group name
--timeout=TIME set I/O timeout in seconds
-I, --ignore-times don't skip files that match size and time
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.)
+
+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(--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)
-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).
+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
being running as the super-user. To turn off super-user activities, the
super-user can use bf(--no-super).
-dit(bf(--chmod)) This options 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:
-
-quote(--chmod=Dg+s,ug+w,Fo-w,+X)
-
-It is also legal to specify multiple bf(--chmod) options.
-
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 options 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.
+In this case (i.e. when the scratch directory in on a different disk
+partition), rsync will not be able to rename each received temporary file
+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 (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 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
bf(--partial) option is to specify a em(DIR) that will be used to hold the
partial data (instead of writing it out to the destination file).
On the next transfer, rsync will use a file found in this
-dir as data to speed up the resumption of the transfer and then deletes it
+dir as data to speed up the resumption of the transfer and then delete it
after it has served its purpose.
+
Note that if bf(--whole-file) is specified (or implied), any partial-dir
file that is found for a file that is being updated will simply be removed
(since
specified. For instance, instead of using bf(--partial-dir=.rsync-tmp)
along with bf(--progress), you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
environment and then just use the bf(-P) option to turn on the use of the
-.rsync-tmp dir for partial transfers. The only time that the bf(--partial)
-option does not look for this environment value is (1) when bf(--inplace) was
-specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when
+.rsync-tmp dir for partial transfers. The only times that the bf(--partial)
+option does not look for this environment value are (1) when bf(--inplace) was
+specified (since bf(--inplace) conflicts with bf(--partial-dir)), and (2) when
bf(--delay-updates) was specified (see below).
For the purposes of the daemon-config's "refuse options" setting,
update algorithm that is even more atomic (it uses bf(--link-dest) and a
parallel hierarchy of files).
+dit(bf(-m, --prune-empty-dirs)) This option tells the receiving rsync to get
+rid of empty directories from the file-list, including nested directories
+that have no non-directory children. This is useful for avoiding the
+creation of a bunch of useless directories when the sending rsync is
+recursively scanning a hierarchy of files using include/exclude/filter
+rules.
+
+Because the file-list is actually being pruned, this option also affects
+what directories get deleted when a delete is active. However, keep in
+mind that excluded files and directories can prevent existing items from
+being deleted (because an exclude hides source files and protects
+destination files).
+
+You can prevent the pruning of certain empty directories from the file-list
+by using a global "protect" filter. For instance, this option would ensure
+that the directory "emptydir" was kept in the file-list:
+
+quote( --filter 'protect emptydir/')
+
+Here's an example that copies all .pdf files in a hierarchy, only creating
+the necessary destination directories to hold the .pdf files, and ensures
+that any superfluous files and directories in the destination are removed
+(note the hide filter of non-directories being used instead of an exclude):
+
+quote( rsync -avm --del --include='*.pdf' -f 'hide! */' src/ dest)
+
+If you didn't want to remove superfluous destination files, the more
+time-honored options of "--include='*/' --exclude='*'" would work fine
+in place of the hide-filter (if that is more natural to you).
+
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
something to watch.