- my($ret) = @_;
- my $fh = $ret ? *STDERR : *STDOUT;
- print $fh <<EOT;
-Usage: atomic-rsync [RSYNC-OPTIONS] HOST:SOURCE DEST
-
-This script allows you to pull some files into DEST on the local system
-(which must exist) in an atomic manner. It does this by first pulling
-files to DEST~new~ (using hard-links to unchanged files in order to keep
-the space requirements down), and then, at the end of the transfer, it
-renames DEST to DEST~old~ and renames DEST~new~ to DEST to effect the
-atomic update. The DEST~old~ hierarchy will be preserved until the next
-run of this script, at which point it will be renamed to DEST~new~ and
-used in the copy.
+ die <<EOT;
+Usage: atomic-rsync [RSYNC-OPTIONS] HOST:/SOURCE/DIR/ /DEST/DIR/
+ atomic-rsync [RSYNC-OPTIONS] HOST::MOD/DIR/ /DEST/DIR/
+
+This script lets you update a hierarchy of files in an atomic way by first
+creating a new hierarchy (using hard-links to leverage the existing files),
+and then swapping the new hierarchy into place. You must be pulling files
+to a local directory, and that directory must already exist. For example:
+
+ mkdir /local/files-1
+ ln -s files-1 /local/files
+ atomic-rsync -av host:/remote/files/ /local/files/
+
+If /local/files is a symlink to a directory that ends in -1 or -2, the
+copy will go to the alternate suffix and the symlink will be changed to
+point to the new dir. This is a fully atomic update. If the destination
+is not a symlink (or not a symlink to a *-1 or a *-2 directory), this
+will instead create a directory with "~new~" suffixed, move the current
+directory to a name with "~old~" suffixed, and then move the ~new~
+directory to the original destination name (this double rename is not
+fully atomic, but is rapid). In both cases, the prior destintaion
+directory will be preserved until the next update, at which point it
+will be deleted.
+
+In all likelihood, you do NOT want to specify this command:
+
+ atomic-rsync -av host:/remote/files /local/
+
+... UNLESS you want the entire /local dir to be swapped out!