From e49f61f5fc5d43866aa442cde5309e7f6b33a44a Mon Sep 17 00:00:00 2001 From: Wayne Davison Date: Sat, 27 Nov 2004 22:09:33 +0000 Subject: [PATCH] Make some of the --*-dest comments clearer and more complete. --- rsync.yo | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/rsync.yo b/rsync.yo index a8a5d480..e4e498f2 100644 --- a/rsync.yo +++ b/rsync.yo @@ -537,7 +537,7 @@ bound. The option implies --partial (since an interrupted transfer does not delete 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). +remove some of these restrictions). WARNING: The file's data will be in an inconsistent state during the transfer (and possibly afterward if the transfer gets interrupted), so you @@ -810,36 +810,48 @@ 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 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. 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. +the destination machine as an additional hierarchy to compare destination +files against doing transfers (if the files are missing in the destination +directory). If a file is found in em(DIR) that is identical to the +sender's file, the file will NOT be transferred to the destination +directory. This is useful for creating a sparse backup of just files that +have changed from an earlier backup. + +Beginning in version 2.6.4, multiple --compare-dest directories may be +provided and rsync will search the list in the order specified until it +finds an existing file. That first discovery is used as the basis file, +and also determines if the transfer needs to happen. + +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. +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. +unchanged files are hard linked from em(DIR) to the destination directory. +The files must be identical in all preserved attributes (e.g. permissions, +possibly ownership) in order for the files to be linked together. An example: verb( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/ ) -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. +Beginning with version 2.6.4, 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. + +If em(DIR) is a relative path, it is relative to the destination directory. +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 -- 2.34.1