From 58a79f4b44593996e53a9bfc94b56006ea86c2ec Mon Sep 17 00:00:00 2001 From: Matt McCutchen Date: Thu, 19 Nov 2009 00:18:23 -0500 Subject: [PATCH] Amplify the man page description of --hard-links (see bug 3693), and improve that of --inplace while I'm at it. --- rsync.yo | 55 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/rsync.yo b/rsync.yo index ebc61f37..f8ac4bd5 100644 --- a/rsync.yo +++ b/rsync.yo @@ -761,17 +761,26 @@ its data needs to be updated: instead of the default method of creating a new copy of the file and moving it into place when it is complete, rsync instead writes the updated data directly to the destination file. -This has several effects: (1) in-use binaries cannot be updated (either the -OS will prevent this from happening, or binaries that attempt to swap-in -their data will misbehave or crash), (2) the file's data will be in an -inconsistent state during the transfer, (3) a file's data may be left in an -inconsistent state after the transfer if the transfer is interrupted or if -an update fails, (4) a file that does not have write permissions can not be -updated, and (5) the efficiency of rsync's delta-transfer algorithm may be -reduced if some data in the destination file is overwritten before it can -be copied to a position later in the file (one exception to this is if you -combine this option with bf(--backup), since rsync is smart enough to use -the backup file as the basis file for the transfer). +This has several effects: + +quote(itemization( + it() Hard links are not broken. This means the new data will be visible + through other hard links to the destination file. Moreover, attempts to + copy differing source files onto a multiply-linked destination file will + result in a "tug of war" with the destination data changing back and forth. + it() In-use binaries cannot be updated (either the OS will prevent this from + happening, or binaries that attempt to swap-in their data will misbehave or + crash). + it() The file's data will be in an inconsistent state during the transfer + and will be left that way if the transfer is interrupted or if an update + fails. + it() A file that does not have write permissions cannot be updated. + it() The efficiency of rsync's delta-transfer algorithm may be reduced if + some data in the destination file is overwritten before it can be copied to + a position later in the file. This does not apply if you use bf(--backup), + since rsync is smart enough to use the backup file as the basis file for the + transfer. +)) WARNING: you should not use this option to update files that are being accessed by others, so be careful when choosing to use this for a copy. @@ -915,17 +924,23 @@ to modify your receiving hierarchy. See also bf(--copy-dirlinks) for an analogous option for the sending side. dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in -the transfer and link together the corresponding files on the receiving -side. Without this option, hard-linked files in the transfer are treated +the source and link together the corresponding files on the destination. +Without this option, hard-linked files in the source are treated as though they were separate files. -When you are updating a non-empty destination, this option only ensures -that files that are hard-linked together on the source are hard-linked -together on the destination. It does NOT currently endeavor to break -already existing hard links on the destination that do not exist between -the source files. Note, however, that if one or more extra-linked files -have content changes, they will become unlinked when updated (assuming you -are not using the bf(--inplace) option). +This option does NOT necessarily ensure that the pattern of hard links on the +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 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. +)) Note that rsync can only detect hard links between files that are inside the transfer set. If rsync updates a file that has extra hard-link -- 2.34.1