File: android-deltas-sync/_etc/examples/_README.txt
TL;DR: see x-1.2-export-example/ for a current and comprehensive demo. This folder hosts example runs of this package's scripts in various contexts, which you can emulate on your devices. For reference, each demo folder includes: - Config files used, in configs/ - Logfiles generated, in logs/ - Console output on PC and phone, in runs/ - A _readme.txt with additional notes Console outputs demo user interaction with this package's scripts; the basic* folders' phone config files give both shared and app-specific storage examples; and the PC config file in the windows* folder shows multiple ways to handle '\' backslashes in Windows paths. Also at the top level here: - _config-diffs.txt is a diff summary of the examples' settings - all-operational-switches-off.txt is a simple self-contained demo - x-1.1-verify-example demos a verify run on a large content set - x-3-devices-with-pc-as-phone shows a deltas sync to a Windows PC - x-1.2-export* demos an export run, along with all other scripts Except for folders windows*, linux*, and x-3*, all demos here were run on a macOS MacBook Pro running Catalina (the PC), and a Galaxy Z Fold3 running Android 11 (the phone). The windows* and linux* demos instead ran the PC scripts on a Dell laptop running Windows 10 and Ubuntu Linux, and x-3* syncs from macOS to Android 10 and 11 phones and Windows 11 PC. Update: the x-1.2-export* demo was run on an Android 12L Galaxy Fold4, and may be the most comprehensive demo of the set (see its _readme.txt). It runs an initial copy, sync, verify, and export in a single demo. This is the only demo run by 1.2; all other 1.1 results are unchanged. Update: the basic-appprivate-storage demo was added in Nov-2022 and was also run on an Android 12L Galaxy Fold4. This demo uses Termux's home folder for both content and zipfiles, and requires an Android File explorer with SAF-based access to this folder (e.g., Fx, AOSP). The most unusual demo here may be x-3-devices-with-pc-as-phone/ which syncs to 3 devices including a PC, though large-shared-storage/ uses a larger content set, and x-1.2-export* test all scripts in the system. Note that config files here use Termux's app-specific storage for this storage type. To use Pydroid 3's app-specific storage instead, use its path: /sdcard/Android/data/ru.iiec.pydroid3. Also note that all doc strings have been stripped from the example config files here, because they kept falling out of date. See the top-level config files for the docs stripped, with full edit details. Some "#" comments also change; see top-level configs for the latest. RUNNING DEMOS To rerun the basic* and linux* demos: before running each demo, copy the demo's configs/ file to the package root on PC and phone, and copy file _test-ads.zip here to the demo's configs/config_pc.py FROM folder on PC and unzip it there to create test data. Be sure to delete any prior test-ads/ folder before unzipping. Change items in the unzipped folder before running the sync scripts (logs show what was changed: one file was copied and deleted, and two text files were edited). For the windows* demo, unzip _test-ads-windows.zip on Windows instead. This is a version of _test-ads.zip with its filenames first run through the filename-fixer script on Unix (macOS). This matters, because unfixed names may be handled by ziptools on Windows differently (e.g., '\' will generate subfolders in ziptools, but will be changed to '_' in the fixer). It's best practice to fix names copied to Windows, even in manual zips. The large*, *verify*, and x-3* demos all use a 208G/180k-file personal content collection which is naturally not included in this package. This content has ~160K files without its backups folder, and ~180K with it. CONTENT NOTE Please note: some demos use atypical items like symlinks and nonportable filenames, just to illustrate how these are handled. You probably should not propagate symlinks to most Android storage types or FAT32 and exFAT drives; probably should use the filename-fixer offered automatically on Unix; and probably will use simpler files and folders in any event. And if you don't know what a symlink is, you probably don't need to care. DECEMBER 2021 RERUNS Most examples here were rerun and regenerated under the new Mergeall 3.3 (which shortens and clarifies run logs for deltas), and with the current preset configs in 1.1 (which disables sync backups on the phone for speed). Examples not rerun under 3.3 say so in NOTEs in their _readme.txt files. In more detail: 1) Mergeall 3.3, now required by this package, changed run-log format after those saved here formerly (which reflected 3.2). In particular, unique (and irrelevant) TO items are not listed in deltas applies, and __added__.txt items are reported on deltas creations and labeled more coherently as "listings". 2) Prior results here were made with the phone config file's BackupChanges set to True (really, before this switch was even available). As shipped in 1.0 and 1.1, this switch is preset to False in the phone config file to avoid long delays for pruning __bkp__ backup folders in shared storage. This makes the speed of syncs in shared storage and app storage much closer, at the expense of being able to rollback syncs in shared storage. In terms of the demos here, this just means that the prior "....pruning" and "....backing up" messages in logfiles for phone-side delta applies in sync logs/ won't appear with the preset, and phone syncs may run faster than formerly shown. This mostly applies to the large* demos which had existing __bkp__ folders, and the preset's speed differs noticeably only in the phone sync captured in large-shared-storage/runs/4*. See "../../_README.html#Sync Rollbacks" for more details. MARCH 2022 UPDATES All the run and log files in this folder were updated to reflect recent output changes in the current release of Mergeall 3.3. Namely: - Unicode normalization messages in logs are now silenced everywhere here with the Mergeall "-quiet" flag (they may be numerous in some contexts, and are prone to be excessive). - The "uniqueto" count in the Differences section of mergeall.py summary reports now shows as "n/a" for "-restore" deltas and rollback runs (this was a pointless and confusing tally of TO items not in deltas, which could be in the thousands, and had no relation to change counts). - The "Changed:" label in mergeall.py's summary report is now "Saved:" for deltas.py runs (nothing is changed in TO in this context). - The "**There are error messages in the log..." summary-report error indicator line has been restored (but appears only in linux-pc-example/). These mods were applied manually, but reflect Mergeall's current results. Per the DEC-2021 note above, a few examples were never regenerated with Mergeall 3.3, though their outputs are largely representative anyhow. OCTOBER/NOVEMBER 2022 UPDATES The new x-1.2-export* demos export scripts added in 1.2, as well as all primary scripts in this system. Study this example if you have time for just one. All prior examples were updated for 1.2 in this release. Though 1.2's main functional change is the addition of export scripts that don't impact former tools, its rebranding as "Android Deltas Sync" does impact all existing examples' outputs. To minimize confusion, examples were changed to display the new name globally. This used a Python search-and-replace script (../_rebrand-oct22.py), which isn't the same as rerunning examples, but the examples are already known to work as shown. The basic-appprivate-storage/ demo was added in Nov-2022 to show how to use the Termux app-private home folder; see its _readme.txt.