-This would make the transfer to the directory /local/files~new~ and then
-swap out /local/files at the end of the transfer by renaming it to
-/local/files~old~ and putting the new directory into its place. The
-/local/files~old~ directory will be preserved until the next update, at
-which point it will be deleted.
+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.