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.
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.
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)
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).
The latest man page has more warnings earlier in the description for --append and --append-verify.
Thanks. Could you point to a commit where this has been changed please?