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