[Bug 13660] New: State clearly in manpage that --append-verify is an edge-case

[samba-bugs at samba.org]

https://bugzilla.samba.org/show_bug.cgi?id=13660

            Bug ID: 13660
           Summary: State clearly in manpage that --append-verify is an
                    edge-case
           Product: rsync
           Version: 3.1.3
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P5
         Component: core
          Assignee: wayned at samba.org
          Reporter: flightvision at gmail.com
        QA Contact: rsync-qa at samba.org

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

-- 
You are receiving this mail because:
You are the QA Contact for the bug.