Implement --tweak, --no-tweak, --no-tweak-hlinked options.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 9c3e1d9..8852adf 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -329,6 +329,8 @@ to the detailed description below for a complete description.  verb(
      --inplace               update destination files in-place
      --append                append data onto shorter files
      --append-verify         --append w/old data in file checksum
+     --no-tweak              recreate dest files rather than tweak attrs
+     --no-tweak-hlinked      ... if they are hard-linked
  -d, --dirs                  transfer directories without recursing
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            transform symlink into referent file/dir
@@ -723,9 +725,12 @@ receiving user.
 dit(bf(--append)) This causes rsync to update a file by appending data onto
 the end of the file, which presumes that the data that already exists on
 the receiving side is identical with the start of the file on the sending
-side.  Any files that are the same size or longer on the receiving side
-are skipped.  Files that do not yet exist on the receiving side are
-transferred, regardless of size.  Implies bf(--inplace),
+side.  If a file needs to be transferred and its size on the receiver is
+the same or longer than the size on the sender, the file is skipped.  This
+does not interfere with the updating of a file's non-content attributes
+(e.g. permissions, ownership, etc.) when the file does not need to be
+transferred, nor does it affect the updating of any non-regular files.
+Implies bf(--inplace),
 but does not conflict with bf(--sparse) (since it is always extending a
 file's length).
 
@@ -740,6 +745,33 @@ bf(--append-verify), so if you are interacting with an older rsync (or the
 transfer is using a protocol prior to 30), specifying either append option
 will initiate an bf(--append-verify) transfer.
 
+dit(bf(--no-tweak)) If a corresponding source file and destination file
+are determined to have identical data (or symlink target path, etc.) but differ
+in preserved attributes, rsync's default behavior (which can be explicitly
+requested via bf(--tweak)) is to tweak the attributes of the destination file
+in place.  bf(--no-tweak) makes rsync recreate the destination file instead.
+
+You can use bf(--no-tweak) to avoid the race inherent in
+bf(--no-tweak-hlinked) if the destination is subject to concurrent
+modification.  It may also be useful to ensure that, if multiple attributes
+of the destination file need updating, the attributes visible at the
+destination path change simultaneously.  (Caveat: In the current
+implementation, the abbreviated extended attributes of the recreated file
+may be set after it is moved into place.)
+
+This option conflicts with bf(--inplace) and with bf(--append) because those
+combinations don't make sense.
+
+dit(bf(--no-tweak-hlinked)) Like bf(--no-tweak) but only affects destination
+files that have more than one hard link.
+You can use bf(--no-tweak-linked) to safely update a backup that has files
+hard-linked from a previous backup if you are not worried about concurrent
+modification to the destination.
+
+This option currently conflicts with bf(--inplace) and bf(--append).  In
+the future, it might selectively disable those options for multiply linked
+destination files.
+
 dit(bf(-d, --dirs)) Tell the sending side to include any directories that
 are encountered.  Unlike bf(--recursive), a directory's contents are not copied
 unless the directory name specified is "." or ends with a trailing slash
@@ -1048,8 +1080,8 @@ call failures); if it isn't, that's a bug.  Other output is the same to the
 extent practical, but may differ in some areas.  Notably, a dry run does not
 send the actual data for file transfers, so bf(--progress) has no effect,
 the "bytes sent", "bytes received", "literal data", and "matched data"
-statistics are too small, and the "speedup" value is equivalent to a run
-where no file transfers are needed.
+statistics are too small; and the "speedup" is not printed at all because it
+is meaningless.
 
 dit(bf(-W, --whole-file)) With this option the delta-transfer algorithm
 is not used and the whole file is sent as-is instead.  The transfer may be
@@ -1677,7 +1709,9 @@ quote(itemization(
   it() A bf(c) means either that a regular file has a different checksum
   (requires bf(--checksum)) or that a symlink, device, or special file has
   a changed value.
-  it() A bf(s) means the size of the file is different and will be updated
+  Note that if you are sending files to an rsync prior to 3.0.1, this
+  change flag will be present only for checksum-differing regular files.
+  it() A bf(s) means the size of a regular file is different and will be updated
   by the file transfer.
   it() A bf(t) means the modification time is different and is being updated
   to the sender's value (requires bf(--times)).  An alternate value of bf(T)