Man page: Move the description of --info=progress2 to a better place.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index c09114e..fcb8b43 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -360,6 +360,7 @@ to the detailed description below for a complete description.  verb(
      --super                 receiver attempts super-user activities
      --fake-super            store/recover privileged attrs using xattrs
  -S, --sparse                handle sparse files efficiently
+     --preallocate           allocate dest files before writing
  -n, --dry-run               perform a trial run with no changes made
  -W, --whole-file            copy files whole (w/o delta-xfer algorithm)
  -x, --one-file-system       don't cross filesystem boundaries
@@ -943,7 +944,8 @@ destination exactly matches that on the source.  Cases in which the
 destination may end up with extra hard links include the following:
 
 quote(itemization(
-  it() If the destination contains extraneous hard-linked files, rsync will not
+  it() If the destination contains extraneous hard-links (more linking than
+  what is present in the source file list), the copying algorithm will not
   break them explicitly.  However, if one or more of the paths have content
   differences, the normal file-update process will break those extra links
   (unless you are using the bf(--inplace) option).
@@ -1177,6 +1179,17 @@ dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
 up less space on the destination.  Conflicts with bf(--inplace) because it's
 not possible to overwrite data in a sparse fashion.
 
+dit(bf(--preallocate)) This tells the receiver to allocate each destination
+file to its eventual size before writing data to the file.  Rsync will only use
+the real filesystem-level preallocation support provided by Linux's
+bf(fallocate)(2) system call or Cygwin's bf(posix_fallocate)(3), not the slow
+glibc implementation that writes a zero byte into each block.
+
+Without this option, larger files may not be entirely contiguous on the
+filesystem, but with this option rsync will probably copy more slowly.  If the
+destination is not an extent-supporting filesystem (such as ext4, xfs, NTFS,
+etc.), this option may have no positive effect at all.
+
 dit(bf(-n, --dry-run)) This makes rsync perform a trial run that doesn't
 make any changes (and produces mostly the same output as a real run).  It
 is most commonly used in combination with the bf(-v, --verbose) and/or
@@ -1248,6 +1261,19 @@ dit(bf(--remove-source-files)) This tells rsync to remove from the sending
 side the files (meaning non-directories) that are a part of the transfer
 and have been successfully duplicated on the receiving side.
 
+Note that you should only use this option on source files that are quiescent.
+If you are using this to move files that show up in a particular directory over
+to another host, make sure that the finished files get renamed into the source
+directory, not directly written into it, so that rsync can't possibly transfer
+a file that is not yet fully written.  If you can't first write the files into
+a different directory, you should use a naming idiom that lets rsync avoid
+transferring files that are not yet finished (e.g. name the file "foo.new" when
+it is written, rename it to "foo" when it is done, and then use the option
+bf(--exclude='*.new') for the rsync transfer).
+
+Starting with 3.1.0, rsync will skip the sender-side removal (and output an
+error) if the file's size or modify time has not stayed unchanged.
+
 dit(bf(--delete)) This tells rsync to delete extraneous files from the
 receiving side (ones that aren't on the sending side), but only for the
 directories that are being synchronized.  You must have asked rsync to
@@ -2319,10 +2345,6 @@ in the file list is still going to increase (and each time it does, the count
 of files left to check  will increase by the number of the files added to the
 list).
 
-dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress).  Its
-purpose is to make it much easier to specify these two options for a long
-transfer that may be interrupted.
-
 There is also a bf(--info=progress2) option that outputs statistics based
 on the whole transfer, rather than individual files.  Use this flag without
 outputting a filename (e.g. avoid bf(-v) or specify bf(--info=name0) if you
@@ -2330,6 +2352,10 @@ want to see how the transfer is doing without scrolling the screen with a
 lot of names.  (You don't need to specify the bf(--progress) option in
 order to use bf(--info=progress2).)
 
+dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress).  Its
+purpose is to make it much easier to specify these two options for a long
+transfer that may be interrupted.
+
 dit(bf(--password-file)) This option allows you to provide a password in a
 file for accessing an rsync daemon.  The file must not be world readable.
 It should contain just the password as the first line of the file (all