Document the side-effect that --partial-dir can have on --temp-dir.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 6ddfe22..2cff135 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -349,7 +349,7 @@ to the detailed description below for a complete description.  verb(
      --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
      --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

- -k, --skip-empty-dirs       skip empty directory chains
+ -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
      --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


@@ -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
 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).
 
 changes the meaning of bf(-a) (see the bf(--files-from) option for more
 details).
 


@@ -1074,9 +1074,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
 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
 
 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 +1313,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
 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
 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 +1344,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
 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.
 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
 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 +1379,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
 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,
 bf(--delay-updates) was specified (see below).
 
 For the purposes of the daemon-config's "refuse options" setting,


@@ -1386,21 +1414,35 @@ See also the "atomic-rsync" perl script in the "support" subdir for an
 update algorithm that is even more atomic (it uses bf(--link-dest) and a
 parallel hierarchy of files).
 
 update algorithm that is even more atomic (it uses bf(--link-dest) and a
 parallel hierarchy of files).
 

-dit(bf(-k, --skip-empty-dirs)) This option tells the receiving rsync to get
+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
 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

-directives.  This also affects what directories get deleted when a delete
-option was specified (but keep in mind that excluded files are also
-protected from deletion).
+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
 
 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

-(due to a hide filter on non-directories being used instead of an exclude):
+(note the hide filter of non-directories being used instead of an exclude):
+
+quote(     rsync -avm --del --include='*.pdf' -f 'hide! */' src/ dest)

 
 

-quote(     rsync -avk --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
 
 dit(bf(--progress)) This option tells rsync to print information
 showing the progress of the transfer. This gives a bored user