From b127c1dc58aa90ac3dc132a31ea01a1ecdb63303 Mon Sep 17 00:00:00 2001 From: Wayne Davison Date: Sat, 27 Nov 2004 17:52:42 +0000 Subject: [PATCH] Document --copy-dest and the support for multiple --*-dest options. --- rsync.yo | 50 +++++++++++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/rsync.yo b/rsync.yo index de1af7f8..a8a5d480 100644 --- 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 - --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 @@ -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 -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). @@ -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. -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 -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/ ) -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 @@ -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 -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 @@ -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 -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). -- 2.34.1