Document --copy-dest and the support for multiple --*-dest options.

diff --git a/rsync.yo b/rsync.yo
index de1af7f..a8a5d48 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -356,7 +356,8 @@ verb(
      --modify-window=NUM     compare mod times with reduced accuracy
  -T  --temp-dir=DIR          create temporary files in directory DIR
      --compare-dest=DIR      also compare received files relative to DIR
      --modify-window=NUM     compare mod times with reduced accuracy
  -T  --temp-dir=DIR          create temporary files in directory DIR
      --compare-dest=DIR      also compare received files relative to DIR

-     --link-dest=DIR         create hardlinks to DIR for unchanged files
+     --copy-dest=DIR         ... and include copies of unchanged files
+     --link-dest=DIR         hardlink to files in DIR when unchanged

  -P                          equivalent to --partial --progress
  -z, --compress              compress file data
  -C, --cvs-exclude           auto ignore files in the same way CVS does
  -P                          equivalent to --partial --progress
  -z, --compress              compress file data
  -C, --cvs-exclude           auto ignore files in the same way CVS does


@@ -534,7 +535,7 @@ 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, --compare-dest, and
+the file), but conflicts with --partial-dir, --compare-dest, --copy-dest, and

 --link-dest (a future rsync version will hopefully update the protocol to
 remove these restrictions).
 
 --link-dest (a future rsync version will hopefully update the protocol to
 remove these restrictions).
 


@@ -808,31 +809,38 @@ 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.
 
 transferred on the receiving side.  The default behavior is to create
 the temporary files in the receiving directory.
 

-dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on
+dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on

 the destination machine as an additional directory to compare destination
 files against when doing transfers if the files are missing in the
 the destination machine as an additional directory to compare destination
 files against when doing transfers if the files are missing in the

-destination directory.  This is useful for doing transfers to a new
-destination while leaving existing files intact, and then doing a
-flash-cutover when all files have been successfully transferred (for
-example by moving directories around and removing the old directory,
-although this skips files that haven't changed; see also --link-dest).
-This option increases the usefulness of --partial because partially
-transferred files will remain in the new temporary destination until they
-have a chance to be completed.  If DIR is a relative path, it is relative
-to the destination directory.
-
-dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
-also will create hard links from em(DIR) to the destination directory for
-unchanged files.  Files with changed ownership or permissions will not be
-linked.
+destination directory.  Files that are identical to one of the specified
+directories are not transferred.  This is useful for creating a sparse
+backup into a new hierarchy.  If em(DIR) is a relative path, it is relative
+to the destination directory.  See also --copy-dest and --link-dest.
+
+dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but
+rsync will also copy unchanged files found in em(DIR) to the destination
+directory (using the data in the em(DIR) for an efficient copy).  This is
+useful for doing transfers to a new destination while leaving existing
+files intact, and then doing a flash-cutover when all files have been
+successfully transferred.  If em(DIR) is a relative path, it is relative to
+the destination directory.  See also --compare-dest and --link-dest.
+
+dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but
+unchanged files are hard linked from em(DIR) to the destination directory
+(The files must be identical in ownership and permissions--if those items
+are being preserved--in order for the files to be linked together.  If
+em(DIR) is a relative path, it is relative to the destination directory.

 An example:
 
 verb(
     rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
 )
 
 An example:
 
 verb(
     rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
 )
 

-Like bf(--compare-dest) if DIR is a relative path, it is relative to the
-destination directory.
+If more than one --link-dest option is specified, rsync will try to find an
+exact match to link with (searching the list in the order specified), and
+if not found, a basis file from one of the em(DIR)s will be selected to try
+to speed up the transfer.  See also --compare-dest and --copy-dest.
+

 Note that rsync versions prior to 2.6.1 had a bug that could prevent
 --link-dest from working properly for a non-root user when -o was specified
 (or implied by -a).  If the receiving rsync is not new enough, you can work
 Note that rsync versions prior to 2.6.1 had a bug that could prevent
 --link-dest from working properly for a non-root user when -o was specified
 (or implied by -a).  If the receiving rsync is not new enough, you can work


@@ -893,7 +901,7 @@ it is more desirable to keep partially transferred files. Using the
 make a subsequent transfer of the rest of the file much faster.
 
 dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to
 make a subsequent transfer of the rest of the file much faster.
 
 dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to

-put a partially transferred file into DIR instead of writing out the
+put a partially transferred file into em(DIR) instead of writing out the

 file to the destination dir.  Rsync will also use a file found in this
 dir as data to speed up the transfer (i.e. when you redo the send after
 rsync creates a partial file) and delete such a file after it has served
 file to the destination dir.  Rsync will also use a file found in this
 dir as data to speed up the transfer (i.e. when you redo the send after
 rsync creates a partial file) and delete such a file after it has served


@@ -904,7 +912,7 @@ rsync is sending files without using the incremental rsync algorithm).
 Rsync will create the dir if it is missing (just the last dir -- not the
 whole path).  This makes it easy to use a relative path (such as
 "--partial-dir=.rsync-partial") to have rsync create the partial-directory
 Rsync will create the dir if it is missing (just the last dir -- not the
 whole path).  This makes it easy to use a relative path (such as
 "--partial-dir=.rsync-partial") to have rsync create the partial-directory

-in the destination file's directory (rsync will also try to remove the DIR
+in the destination file's directory (rsync will also try to remove the em(DIR)

 if a partial file was found to exist at the start of the transfer and the
 DIR was specified as a relative path).
 
 if a partial file was found to exist at the start of the transfer and the
 DIR was specified as a relative path).