I'd like to suggest a change to the manpage making --append-verify
clearly pointing out that it is not suitable to mirror/backup
directories and should not be used apart from very specific edge cases.


I've seen now several time in the wild the expectation that
--append-verify would allow partial transfers and append to files after
it verified the contents BUT not change the behaviour for the rest of
the files!!! So the expectation is that by adding this switch you just
ADD functionality (that sounds very cool, like
only-append-after-verifying-existing-contents), not that you make rsync
do something completely different.

So you see a lot of backups / web deployments in the wild that look
like: rsync -a --partial --append-verify ./ receiver:/PATH/

I think this is crucial as this misunderstanding is causing quality and
security problems. When the "bug" is pointed out it makes rsync look bad.



CURRENT STATE:
       --append-verify
              This works just like the --append option, but the existing data on the receiving side is included in  the  full-file  checksum  verification               step,  which  will cause a file to be resent if the final verification step fails (rsync uses a normal, non-appending --inplace transfer for               the resend).

              Note: prior to rsync 3.0.0, the --append option worked like --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 --append-verify transfer.



To grasp the functionality, you are required to read --append section and catch this part of the 2nd sentence.

       --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. 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**.   ... 




I SUGGEST: (mind that I am not an English-native speaker)

--append-verify
              Makes rsync only work on growing files (just like the --append option), but the existing data on the receiving side is included in  the  full-file  checksum  verification step,  which  will cause a file to be resent if the final verification step fails (rsync uses a normal, non-appending --inplace transfer for the resend).