X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/0d78a2789347d092a56b48dcee2c1bcb3b2e1227..5deb19e4ea1c04cac93f39d60a3a8f891a6fff74:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 20162727..17e9025f 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.
@@ -881,6 +890,17 @@ bf(--force) or bf(--delete) is in effect).
 See also bf(--keep-dirlinks) for an analogous option for the receiving
 side.
 
+bf(--copy-dirlinks) applies to all symlinks to directories in the source.  If
+you want to follow only a few specified symlinks, a trick you can use is to
+pass them as additional source args with a trailing slash, using bf(--relative)
+to make the paths match up right.  For example:
+
+quote(tt(rsync -r --relative src/./ src/./follow-me/ dest/))
+
+This works because rsync calls bf(lstat)(2) on the source arg as given, and the
+trailing slash makes bf(lstat)(2) follow the symlink, giving rise to a directory
+in the file-list which overrides the symlink found during the scan of "src/./".
+
 dit(bf(-K, --keep-dirlinks)) This option causes the receiving side to treat
 a symlink to a directory as though it were a real directory, but only if it
 matches a real directory from the sender.  Without this option, the
@@ -904,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
@@ -1005,8 +1031,8 @@ The source and destination systems must have compatible ACL entries for this
 option to work properly.  See the bf(--fake-super) option for a way to backup
 and restore ACLs that are not compatible.
 
-dit(bf(-X, --xattrs)) This option causes rsync to update the remote
-extended attributes to be the same as the local ones.
+dit(bf(-X, --xattrs)) This option causes rsync to update the destination
+extended attributes to be the same as the source ones.
 
 For systems that support extended-attribute namespaces, a copy being done by a
 super-user copies all namespaces except system.*.  A normal user only copies