X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/a272ff8c1bdd551e697f06b4d51bfd84aa13a064..656c20715eb5261f8158a7f7b999d5099db3a3f9:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 087912bc..7c06d1bd 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -498,7 +498,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).
 
@@ -746,6 +746,9 @@ quote(--chmod=Dg+s,ug+w,Fo-w,+X)
 
 It is also legal to specify multiple bf(--chmod) options.
 
+If permissions are not being preserved (via bf(--perms)), the resulting value
+will still be masked by the receiving end's umask setting.
+
 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 +857,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 +1080,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
@@ -1286,7 +1319,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 +1350,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 +1385,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,