More --delete-before improvements.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 6f241b2..f408b27 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -344,6 +344,7 @@ verb(
      --ignore-existing       ignore files that already exist on receiver
      --del                   an alias for --delete-during
      --delete                delete files that don't exist on sender
      --ignore-existing       ignore files that already exist on receiver
      --del                   an alias for --delete-during
      --delete                delete files that don't exist on sender

+     --delete-before         receiver deletes before transfer (default)

      --delete-during         receiver deletes during xfer, not before
      --delete-after          receiver deletes after transfer, not before
      --delete-excluded       also delete excluded files on receiver
      --delete-during         receiver deletes during xfer, not before
      --delete-after          receiver deletes after transfer, not before
      --delete-excluded       also delete excluded files on receiver


@@ -353,6 +354,7 @@ verb(
      --max-size=SIZE         don't transfer any file larger than SIZE
      --partial               keep partially transferred files
      --partial-dir=DIR       put a partially transferred file into DIR
      --max-size=SIZE         don't transfer any file larger than SIZE
      --partial               keep partially transferred files
      --partial-dir=DIR       put a partially transferred file into DIR

+     --delay-updates         update transferred files into place at end

      --numeric-ids           don't map uid/gid values by user/group name
      --timeout=TIME          set I/O timeout in seconds
  -I, --ignore-times          turn off mod time & file size quick check
      --numeric-ids           don't map uid/gid values by user/group name
      --timeout=TIME          set I/O timeout in seconds
  -I, --ignore-times          turn off mod time & file size quick check


@@ -549,9 +551,9 @@ or appended data, and also on systems that are disk bound, not network
 bound.
 
 The option implies --partial (since an interrupted transfer does not delete
 bound.
 
 The option implies --partial (since an interrupted transfer does not delete

-the file), but conflicts with --partial-dir.  Prior to rsync 2.6.4
---inplace was also incompatible with --compare-dest, --copy-dest, and
---link-dest.
+the file), but conflicts with --partial-dir and --delay-updates.
+Prior to rsync 2.6.4 --inplace was also incompatible with --compare-dest,
+--copy-dest, and --link-dest.

 
 WARNING: The file's data will be in an inconsistent state during the
 transfer (and possibly afterward if the transfer gets interrupted), so you
 
 WARNING: The file's data will be in an inconsistent state during the
 transfer (and possibly afterward if the transfer gets interrupted), so you


@@ -699,21 +701,30 @@ prevent temporary filesystem failures (such as NFS errors) on the
 sending side causing a massive deletion of files on the
 destination.  You can override this with the --ignore-errors option.
 
 sending side causing a massive deletion of files on the
 destination.  You can override this with the --ignore-errors option.
 

-If you don't specify --delete-during (--del) or --delete-after, the
-file deletions will be done before the first file is transferred.
-This is helpful if the filesystem is tight for space
+The --delete option may be combined with one of the --delete-WHEN options
+without conflict, as well as --delete-excluded.  However, if none of the
+--delete-WHEN options are specified, rsync will currently choose the
+--delete-before algorithm.  A future version may change this to choose the
+--delete-during algorithm.  See also --delete-after.
+
+dit(bf(--delete-before)) Request that the file-deletions on the receiving
+side be done before the transfer starts.  This is the default if --delete
+or --delete-excluded is specified without one of the --delete-WHEN options.
+See --delete (which is implied) for more details on file-deletion.
+
+Deleting before the transfer is helpful if the filesystem is tight for space

 and removing extraneous files would help to make the transfer possible.
 However, it does introduce a delay before the start of the transfer,
 and this delay might cause the transfer to timeout (if --timeout was
 specified).
 
 and removing extraneous files would help to make the transfer possible.
 However, it does introduce a delay before the start of the transfer,
 and this delay might cause the transfer to timeout (if --timeout was
 specified).
 

-dit(bf(--del, --delete-during)) Request that the file-deletions on the
-receving side be done incrementally as the transfer happens.  This is
-a faster method than chosing the before- or after-transfer processing,
+dit(bf(--delete-during, --del)) Request that the file-deletions on the
+receiving side be done incrementally as the transfer happens.  This is
+a faster method than chosing the before- or after-transfer algorithm,

 but it is only supported beginning with rsync version 2.6.4.
 See --delete (which is implied) for more details on file-deletion.
 
 but it is only supported beginning with rsync version 2.6.4.
 See --delete (which is implied) for more details on file-deletion.
 

-dit(bf(--delete-after)) Request that the file-deletions on the receving
+dit(bf(--delete-after)) Request that the file-deletions on the receiving

 side be done after the transfer has completed.  This is useful if you
 are sending new per-directory merge files as a part of the transfer and
 you want their exclusions to take effect for the delete phase of the
 side be done after the transfer has completed.  This is useful if you
 are sending new per-directory merge files as a part of the transfer and
 you want their exclusions to take effect for the delete phase of the


@@ -1028,13 +1039,34 @@ is a security risk.  E.g. AVOID "/tmp".
 
 You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
 variable.  Setting this in the environment does not force --partial to be
 
 You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
 variable.  Setting this in the environment does not force --partial to be

-enabled, but rather it effects where partial files go when --partial (or
--P) is used.  For instance, instead of specifying --partial-dir=.rsync-tmp
+enabled, but rather it effects where partial files go when --partial is
+specified.  For instance, instead of using --partial-dir=.rsync-tmp

 along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
 environment and then just use the -P option to turn on the use of the
 along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
 environment and then just use the -P option to turn on the use of the

-.rsync-tmp dir for partial transfers.  The only time the --partial option
-does not look for this environment value is when --inplace was also
-specified (since --inplace conflicts with --partial-dir).
+.rsync-tmp dir for partial transfers.  The only time that the --partial
+option does not look for this environment value is (1) when --inplace was
+specified (since --inplace conflicts with --partial-dir), or (2) when
+--delay-updates was specified (see below).
+
+dit(bf(--delay-updates)) This option puts the temporary file from each
+updated file into the file's partial-dir (see above) until the end of the
+transfer, at which time all the files are renamed into place in rapid
+succession.  This attempts to make the updating of the files a little more
+atomic.  If you don't specify the --partial-dir option, this option will
+cause it to default to ".~tmp~" (RSYNC_PARTIAL_DIR is not consulted for
+this value).  Conflicts with --inplace.
+
+This option uses more memory on the receiving side (one bit per file
+transferred) and also requires enough free disk space on the receiving
+side to hold an additional copy of all the updated files.  Note also that
+you should not use an absolute path to --partial-dir unless there is no
+chance of any of the files in the transfer having the same name (since all
+the updated files will be put into a single directory if the path is
+absolute).
+
+See also the "atomic-rsync" perl script in the "support" subdir for an
+update algorithm that is even more atomic (it uses --link-dest and a
+parallel hierarchy of files).

 
 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