X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/e630fd11869ca2824154ee585ab77059b91ca0ac..e3bc529de9b7d0e98c492677f73a8127a1d74d35:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 610cc9d1..a1cac988 100644
--- 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,13 +944,15 @@ 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 already contains hard links, rsync will not break
-  them explicitly.  However, if one or more of the paths have content
-  differences, the normal file-update process will break those links, unless
-  you are using the bf(--inplace) option.
+  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).
   it() If you specify a bf(--link-dest) directory that contains hard links,
-  rsync may use the same bf(--link-dest) file multiple times via several of
-  its paths.
+  the linking of the destination files against the bf(--link-dest) files can
+  cause some paths in the destination to become linked together due to the
+  bf(--link-dest) associations.
 ))
 
 Note that rsync can only detect hard links between files that are inside
@@ -963,7 +966,10 @@ see the bf(--inplace) option for more caveats).
 If incremental recursion is active (see bf(--recursive)), rsync may transfer
 a missing hard-linked file before it finds that another link for that contents
 exists elsewhere in the hierarchy.  This does not affect the accuracy of
-the transfer, just its efficiency.  One way to avoid this is to disable
+the transfer (i.e. which files are hard-linked together), just its efficiency
+(i.e. copying the data for a new, early copy of a hard-linked file that could
+have been found later in the transfer in another member of the hard-linked
+set of files).  One way to avoid this inefficiency is to disable
 incremental recursion using the bf(--no-inc-recursive) option.
 
 dit(bf(-p, --perms)) This option causes the receiving rsync to set the
@@ -1173,9 +1179,16 @@ 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.
 
-NOTE: Don't use this option when the destination is a Solaris "tmpfs"
-filesystem. It seems to have problems seeking over null regions,
-and ends up corrupting the files.
+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
@@ -1486,7 +1499,7 @@ initial items are marked as perishable -- see the FILTER RULES section):
 
 quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
 .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del-*
-*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .bzr/)))
+*.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .git/ .hg/ .bzr/)))
 
 then, files listed in a $HOME/.cvsignore are added to the list and any
 files listed in the CVSIGNORE environment variable (all cvsignore names
@@ -1616,6 +1629,12 @@ bf(--files-from) filenames are being sent from one host to another, the
 filenames will be translated from the sending host's charset to the
 receiving host's charset.
 
+NOTE: sorting the list of files in the --files-from input helps rsync to be
+more efficient, as it will avoid re-visiting the path elements that are shared
+between adjacent entries.  If the input is not sorted, some path elements
+(implied directories) may end up being scanned multiple times, and rsync will
+eventually unduplicate them after they get turned into file-list elements.
+
 dit(bf(-0, --from0)) This tells rsync that the rules/filenames it reads from a
 file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
 This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any