File: android-deltas-sync/_etc/content-rescue.txt
=========================================================================== Rescuing Phone and Proxy Content =========================================================================== This plain-text note provides additional usage tips for the Android Deltas Sync package, and augments the main ../_README.html usage guide. --------------------------------------------------------------------------- How Things Can Go Wrong --------------------------------------------------------------------------- In response to recent user feedback, a friendly callout seems in order for your content's sake: in normal usage, please be careful to update the content copies on both your proxy and phone with this system's scripts only. If you don't follow this rule, your phone is apt to grow out of sync with your PC, and may not reflect your PC again until a full and time-consuming PC-to-phone recopy or phone-to-PC export. This unhappy state can arise subtly from well-intended actions: Direct Mergealls: As noted in the "Quick Start" of ../_README.html, you should not normally change the content copy in your proxy-drive folder except by running this system's scripts, else change detection won't work. For instance, syncing the proxy by running Mergeall directly, whether by its script or GUI, will indeed make the proxy match the PC, but will also make it impossible for this system's scripts to sync the phone: the scripts will find no remaining PC-to-proxy differences to propagate to the phone, leaving its content copy out of sync with PC and proxy. Invalid propagations: As also noted in the section named "Sync Rollbacks" in ../_README.html, sync backups are by default disabled for proxy-to-phone syncs, in the name of speed on recent Android's shared storage. This means that once a deltas set is applied to the phone, there is no automatic way to back out just the latest changes set. Delta applies do not normally go awry, but pushing out an incorrect set of changes (e.g., from the wrong device) could wreak havoc in your phone, with no rollbacks possible. Phone-only changes: As finally noted in "Skew Caveat: Proxy vs Phone" of ../_README.html, you normally should not change content on your phone alone, because the mod will not be detected as a difference between your PC and proxy, and hence will evade deltas scripts and remain as perpetual skew on your phone. You can mitigate this by exporting the phone copy back to your PC and proxy with an indirect backsync per ../README.html (see "Update: Phone Exports"), but it's a relatively slow procedure, and probably best use only occasionally for larger content folders. Acts of content gods: Beyond user actions, storage devices can have flaws, and do have limited lifespans. While better devices can maintain content and handle syncs for many years, they all fail eventually. Storage demise usually reveals itself as inexplicable content skew or error messages in sync logs and messages. This is rare and may be a minor event for proxy drives, but it can be terminal for a PC or phone. The upside is that it also qualifies as an excuse to upgrade. --------------------------------------------------------------------------- How to Rescue Your Content --------------------------------------------------------------------------- If you unintentionally desync your phone or proxy content copies by steps like those above, all is not lost; your content is still alive and well on your PC, after all (and/or on the redundant backups that are a part of your content-management routine, right?). But you'll need to restore the syncability of your devices before using this system's scripts. How to proceed depends upon the damage: If you need to reset both your PC and proxy to match your phone: As of version 1.2, you can export your phone's content to both your PC and proxy, by running the new export scripts pair. See "To Export Phone Changes or Content" in ../README.html for this backsync option if your phone's content has been changed, or remains the only usable copy. This can also be used to export phone content in full to either or both destinations; simply use empty content folders on PC and/or proxy. If you need to reset just your proxy to match your phone: If you inadvertently ran a direct PC-to-proxy Mergeall, you can repair the damage by simply exporting your phone's content and unzipping it on your proxy. To export from phone to proxy, first do this on your phone--it creates a zipfile of your phone's content and asks you to copy it to your proxy drive: $ python3 verify-content-part1-phone.py Then, run the following on your PC to unzip the phone-content zip on your proxy drive and restore it as a phone stand-in for future syncs (in this, the $X refer to settings in your config_pc.py file, the ziptools program nested in Mergeall does cross-device unzips, and your verify run retained the phone-content zipfile on the proxy): $ cd $TO # go to the proxy drive's root $ rm -rf $STUFF # delete the proxy's content-copy folder $ python3 $MALL/test/ziptools/zip-extract.py PHONE.zip . You can also reset the proxy with the next item's remedy, but that's unnecessary work and slower if only the proxy is askew. If you need to reset your proxy and phone to match your PC: If your proxy drive and/or phone are unusable in general, you can always rerun the initial-copy procedure. To do so, run the two steps in "To Copy Content to Your Phone" in ../_README.html's "Quick Start"; the first runs on your PC and the second on your phone, and both will first remove existing copies as needed. This pushes content from PC to proxy and phone. It may seem like overkill if just the proxy is damaged, but pushing content to the proxy alone may leave the phone out of sync if it lacks changes made on the PC since the latest successful sync. If your phone's content copy is corrupt or skewed: Your best recourse is to rerun a full initial copy step per the preceding item. This will reset the content copies on both proxy and phone to match that on your PC. This may be time consuming for large content collections (hours are not impossible), and is probably best avoided except as an emergency content rescue. Exception: if you _intentionally_ changed your phone's copy alone, you can export its content to your PC and proxy to make all three copies match again. See "Update: Phone Exports" in ../_README.html, and "To Export Phone Changes or Content" in the same file in 1.2. If you've enabled backups on your phone: It's possible to rollback changes made by a sync gone bad, but this may not suffice. Backups are always on for the proxy by default, so both devices can be restored to pre-sync states with commands of the form described in "Sync Rollbacks" of ../_README.html. Keep in mind, however, that this won't rollback any changes you've made manually on your phone, outside the scope of this system and Mergeall. And while you can rollback changes made to your proxy by direct Mergeall runs this way, all bets are off if you've propagated additional changes on to your phone after an inadvertent and direct PC-to-proxy Mergeall (see the remedy above). Other options: It's also possible to perform some recoveries by running just the first part of other script pairs in this system. Running the first initial-copy script on your PC, for instance, will recreate the proxy's content copy. Still, this is usually overkill, because the scripts perform extra steps not required in rescue contexts. Study the scripts' code for more ideas. --------------------------------------------------------------------------- Wrap-up --------------------------------------------------------------------------- As you can see, content rescue is possible, but can be tricky. The best policy in normal use cases is to maintain your phone content with this system's scripts exclusively. Your phone and proxy will both match your PC, and you'll be immune from content-algebra problems like those above. At least, that is, until the inevitable content-storage disasters strike. For more tips, open the ../_README.html usage guide in a browser.