X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/a272ff8c1bdd551e697f06b4d51bfd84aa13a064..5e65c96705a80b6b0b14f8ea19e6a37563e19a6d:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 087912bc..d61dfb81 100644 --- a/rsync.yo +++ b/rsync.yo @@ -316,6 +316,7 @@ to the detailed description below for a complete description. verb( -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) @@ -498,7 +499,7 @@ could specify bf(-a --no-o) (or bf(-a --no-owner)). 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). @@ -561,7 +562,7 @@ bf(--backup-dir) and bf(--suffix) options. 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 @@ -678,14 +679,39 @@ destination machines is higher than the bandwidth to disk (especially when the "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 @@ -736,15 +762,24 @@ also for ensuring that you will get errors if the receiving side isn't 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. @@ -854,10 +889,13 @@ See bf(--delete) (which is implied) for more details on file-deletion. 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). @@ -1074,9 +1112,36 @@ It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore 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 @@ -1213,13 +1278,13 @@ if the receiving rsync is at least version 2.6.7 (you can use bf(-vv) 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 @@ -1286,7 +1351,7 @@ item that is changed in any way (as long as the receiving side is at least 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 @@ -1317,8 +1382,9 @@ dit(bf(--partial-dir=DIR)) A better way to keep partial files than the 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 @@ -1351,9 +1417,9 @@ enabled, but rather it effects where partial files go when bf(--partial) is 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,