![[image]](usbsync.png)
This page provides an in-depth guide to all the options available in the app's GUI (graphical user interface), and goes into usage details along the way. All of its sections begin with a box of links to screenshots from each of the four supported platforms, to help you relate the concepts covered here to the GUIs you'll be using.
This page is mostly about the fine points, and is partly meant to work as a reference after you start using the system. For a higher-level look at app usage, see Usage Overview, and for app start-up info, see App Packages.
This app's GUI organizes its functionality into separate screens selected by tabs. At the top of the GUI, you'll find a bar of buttons which allow you to quickly switch between the tabs' screens with a tap or click. This bar scrolls horizontally on narrow displays if needed.
Tabs also factor into app closes. An Android Back (and a PC Escape key) in any tab other than Main will take you back to the Main tab quickly. A Back (or escape) in the Main tab closes the app, unless a Main-tab action is running. Because killing a running action may not be desired, close requests while one is in progress trigger either a verify dialog, or info on how to shutdown both app and action (e.g., with a Recents swipe on Android). There's more on Main-tab actions in the next section.
When you first open the GUI, it will prompt you to enable storage permissions on both Android (where the prompts differ for Androids 8-10 and 11+), and macOS. Please grant the permission to allow this app to process your content folders on your device and USB drives. You'll also approve notifications on Android and some folder access on macOS as you start using the app. See the app's About tab for its privacy policy, and the App Packages doc for more on permissions.
The remainder of this page covers specific parts of the app's GUI, and is organized by tabs; because the Main-tab's folder chooser is crucial info, it gets its own section here too:
New: see also the app videos that demo concepts covered here.
This is the primary tab you'll use to process your content. Here, you will run an action by:
After running an action here, you'll usually proceed to explore its results in the Logs tab (covered ahead). The Main tab's options are grouped by sections in the GUI. The following coverage details them, from top to bottom on this tab.
The blue FROM and TO buttons at the top left of this section open a folder-chooser popup where you'll pick the content folders which will be processed by this tab's green action buttons covered in the next section.
The folder chooser displays folders in the available storage areas on all your devices. At its top, you'll find a red button for each storage area. This row's buttons identifying storages by name; open storage roots when tapped; scroll to reveal all your options; and act as radio buttons: the current selection's type is darker to let you know what's being displayed. They also vary by device type, and merit separate coverage ahead.
Back on the Main tab, to the right of the blue FROM and TO buttons, the white text fields both display the paths of the folders you select, and allow you to edit them with your keyboard as desired. All the usual edits work, including control-c/v to copy/paste, and long and double taps on Android to select and copy/paste. Whatever is in these fields when a green action button is tapped is what will be processed. For tips on scrolling and selecting these path-display fields, see the News post.
As a convenience, the app automatically saves the white path fields' contents whenever you run a green-button action, and restores them when you restart the GUI. Because of this, you usually won't need to re-select folders on each run; if you normally process the same FROM and TO folders every time, they'll be preloaded into the white text fields and ready to go.
This section hosts the app's main actions, which you run by tapping the green buttons on the left. All the actions here continue running if they are in progress when you navigate to another app or program, or the screen is turned off on Android. All actions here also ask you to confirm their run in a popup that describes their intents.
New: as of 1.1.0, action-confirmation popups also show you the paths to be processed, along with their storage/drive names; and the popups issued at action exits present a brief summary of logfile details. These enhancements can avoid additional user operations in some contexts (e.g., logfile inspection may not be necessary). For more info, see this and this.
In more detail than their in-GUI summaries, here's what the green action buttons do, from top to bottom:
Operationally, SYNC launches a sync from FROM to TO, which updates TO only for the ways it differs from FROM. Put another way, this propagates changes made to FROM since the last SYNC to TO. FROM's changes are detected quickly using file timestamps and sizes along with folder-tree structure, and propagated to TO with file operations. The net effect makes TO the same as FROM.
In practical terms, this same tool can be used to both:
In the latter mode, all three devices' content copies are the same after the two-step process—source, USB, and destination—and the USB drive in the middle serves as an extra backup copy.
To audit the changes made by a SYNC, either inspect the action-exit popup, or go to the Logs tab when the run finishes, and either TAIL or OPEN the most recent logfile which is automatically selected in the tab. Near the end of the logfile, you'll find a summary of differences found and changes applied; the counts for each are often enough to verify SYNC results. There's more info on reading logfiles in Tech Notes.
If enabled in the Config tab, SYNC will save backup copies of every item it changes in TO, so that the SYNC can be rolled back with the UNDO button. This is enabled by default, and explained more fully ahead at UNDO.
To view differences after a SHOW run, either inspect the action-exit popup, or go to the Logs tab and TAIL or OPEN the most recent logfile automatically selected there. The popup gives a summary or message. The full logfile gives a summary with counts for all difference categories, with more detailed info on individual differences above the summary.
Because SHOW compares with timestamps, sizes, and structure just like SYNC, it's much faster than the full reads of DIFF (ahead). It also puts less stress your devices and drives, which helps extend their lifespans. Use this for most verifications.
UNDO is useful if a SYNC is run incorrectly, or goes awry due to hardware or software failures. While it should be rarely (if ever) required, it provides an emergency-rescue feature for your content when needed. UNDO can also be run multiple times, and each successive run will roll back successively older SYNCs. This is more rarely needed than UNDO itself, but can be used to restore a content copy to its state at an arbitrary point in the past, by rolling back each SYNC run since then.
SYNC backups rolled back by UNDO are saved in each TO folder's auto-cleaning
__bkp__ folder, in a subfolder labeled by date and time. You can control how many
backups are retained in the Config tab to balance
space used against rollback longevity, and can manually inspect or use __bkp__
contents freely. As a convenience, the
Help tab includes a button for exploring TO's __bkp__
folder automatically.
Important: UNDO can be used only if its latest SYNC was run with backups enabled, and is generally prohibited in the app's GUI otherwise. Without backups, there is nothing for UNDO to roll back. This rule also applies to consecutive UNDO runs: they work only if all the SYNCs you wish to UNDO were run with backups enabled.
SYNC backups are enabled by default in the Config tab, but can be disabled there to save space or boost speed. As guidelines, their extra space and time requirements are generally modest because they save changed items only, but pruning prior backup folders can be slow in some Android contexts. Keep in mind, though, that disabling them precludes using UNDO for SYNC; unless you're sure you won't need them later, SYNC backups are strongly advised.
Note that COPY always creates FROM's folder inside TO, so in this action you're
really selecting the TO folder to host the content-folder, not the content folder itself.
For example, if FROM is a path a/b/c and TO is x/y, COPY
will create x/y/c to be a complete copy of a/b/c.
Be sure to select the new subfolder before running a SHOW or DIFF on it to
verify the COPY; the prior path selection is one level too high.
COPY also ensures that you don't inadvertently copy a folder into itself, which would loop and fail. See the 1.1.0 improvement for more details.
To view differences after a DIFF run, either inspect the action-exit popup, or go to the Logs tab and TAIL or OPEN the most recent logfile automatically selected there. The popup gives a summary or message. The logfile includes both a summary with counts for categories, along with a full and searchable report above the summary (e.g., look for "*UNIQ" to find unique items).
This is a much deeper comparison than the SHOW action's timestamp-based check (above), and, though very rare, may catch things that a timestamp comparison misses. Its depth, however, also makes DIFF much slower; you should generally use this only occasionally, to verify that FROM and TO are truly the same.
Besides comparison depth, DIFF also differs from SHOW by always noting
__bkp__ folders as differences. SHOW and SYNC simply skip
these folders because they normally differ and are not in scope for content
syncs (see UNDO above for more on backup folders).
By contrast, DIFF applies to folders of all kinds.
There additional notes about DIFF messages in
Tech Notes.
Nit: while DIFF is a deeper comparison than SHOW, it still does not compare exotic or platform-specific metadata like file attributes and permissions. Since content is about file bytes, however, this action suffices for all content collections you're likely to compare.
Tip: Mergeall includes a command-line tool that helps you inspect individual file differences reported in a DIFF logfile. See and fetch it here.
Sidebar: DIFF differences are also usually your first indicator of device errors. All drives have limited lifespans, and stop accurately recording content eventually. If a handful of files differ in odd ways as indicated by DIFF, it probably reflects bad device sectors, and it's likely that your device's storage is starting to fail and should be replaced soon.
Specifically, the tool replaces any of the ten characters
\x00 / \ | < > ? * : " with a single underscore _,
in the names of all files, folders, and symlinks in the entire FROM tree.
This mod satisfies the naming rules on all devices this app supports.
It's recommended when transferring content from Unix (e.g., macOS or Linux) to
Windows, removable drives using Windows filesystems (e.g., exFAT or FAT32),
or Android shared storage
(labeled PHONE in choosers).
Because this action's changes have no undo (rollback), you can opt to run it in either report or update mode in the confirmation dialog. Report mode lists FROM's nonportable filenames in the logfile, but does not change them. Update mode proceeds to change all nonportable filenames in FROM as described. You should usually run this tool in report mode before update, to verify that all its proposed name changes are harmless; it's possible that some files are named nonportably on purpose, though they won't work across all devices unchanged.
In general, this tool never must be run on Windows, as that platform already prohibits nonportable characters. Windows enforces filename rules by its win32 API, independently of filesystems. This option is not grayed-out when this app is run on Windows, only because atypical software might allow nonportable names to be created (conceivably, though it's unknown if win32 is ever subverted). As a guideline, ignore NAME on Windows unless you know that filename constraints may not be enforced on a given drive, and use report mode if you're unsure; if change counts are zero in the logfile, no mods are needed.
By contrast, this tool is useful and recommended for content on Unix (macOS and Linux), as well as Android app-specific storage (APP in choosers), because both have filename rules that are more flexible than Windows'. Android shared storage (PHONE) follows Windows' rules, and generally doesn't require NAME runs (though Android devices are highly variable). See the folder-chooser popup coverage ahead for more on Android storage. Like all actions, NAME reports its results in an action-exit popup and logfile.
The tool run by NAME is also available on the web, for use in command-line mode (e.g. in Termux on Android, and Terminal or Command Prompt on PCs). Fetch or inspect it here. At the same site, you can also find a tool for adjusting timestamps on FAT32 drives, as well as a tool to locate (though not fix) nonportable symlinks, and an overview of the timestamp issue for time changes on FAT32.
Tip: if you don't fix nonportable filenames with NAME, these files will fail when copied by SYNC and COPY, and be skipped with error messages in logfiles. Some platforms (e.g., macOS) silently change such names to allow copies, but this hack may fail in later usage contexts. Using NAME before SYNC and COPY is your best bet for content that may span multiple platforms and devices. See also the Usage Overview's related coverage of symlinks.
Finally, the image at the bottom of the Main tab animates when an action is in progress, and stops when the action ends to give you a simple visual indicator for action status. Because some Main-tab actions may run for a long time on larger content folders, this lets you check in on status periodically.
On Android, actions by default also give status by posting a notification while they are running; please allow notifications when prompted on the first run, and see your notification pulldown or top-of-phone status bar. In addition, the Logs tab's TAIL and WATCH actions allow you to check the status of running actions in more detail; we'll see how after the brief look at the Main tab's folder chooser up next.
When you tap a blue FROM or TO button in the Main tab, you'll open a popup window in which you can pick a content folder on one of your devices. From top to bottom in this popup, you'll find:
In the second to last of these, parent folders, denoted by ../,
allow you to move up in the folder hierarchy, until you reach the top of
the storage area. When you tap this popup's Pick to select a folder,
the folder's path is copied to the Main tab's white fields, where it can
be edited as desired.
Most of this popup's content is self-explanatory, but the red storage-type buttons at the top warrant a few more words. These buttons scroll horizontally to reveal all your drives and options, if they don't all fit on your display; always open storage type root folders when tapped, even if already selected; and work as radio buttons: the darker button always denotes the storage being displayed below it, whether it was picked by you, or preselected for the initial path on popup open.
The red storage-type buttons also identify storage by name—which may be a logical category name, or device volume label that you create for removable drives. The set of buttons (and hence names) available will vary by host device, and depend on the drives you've attached. By hosts:
Removable-drive buttons use your drives' volume labels for their names (e.g., MYSSD), and may include both USB flash and SSD drives, and microSD cards. You'll find one removable button for every drive attached, including each plugged into a hub. You can usually store content folders anywhere on removable drives, but see the special case below if your device mix includes Android 10 or earlier.
In addition, Linux may display an OS button on dual-boot systems to give access to your Windows drive; optical drives (e.g., BDRs) may be selected as FROM when attached to your PC; virtual machines may display access points to other systems; and network drives will appear if mounted to standard folders on Unix or mapped to drive letters on Windows, though USB is generally preferred for portability, speed, and privacy.
Removable-drive buttons may include your USB drive's name (e.g., MYSSD), the names of all drives plugged into an attached USB hub (rare but supported on Android), and the name of a removable microSD drive inside your phone. You can usually store content folders anywhere on removable drives, but see the special case for Android 10 and earlier below.
For a first take on the difference between PHONE and APP on-phone storage on Android, please see the Usage Overview. In short:
Because it may be deleted on data clears and app uninstalls, APP is a use-with-care option. If it's not something you wish to leverage (or risk), APP can be turned off altogether in the Config tab and omitted from the popup. The good news is that PHONE shared storage is about to grow much faster, as UFS 4 storage rolls out to new phones (though the speed of USB access may dominate syncs for all storage types on some phones).
For related info, see also the User Guide's coverage of storage concepts here and here.
When you select a folder in the popup, you'll probably notice that the first part of its path copied to the Main tab looks different than the labels on the popup's red storage-type button you used to select it. For example:
/storage/emulated/0,
and removable-drive paths with either /mnt/media_rw or
/storage (depending on your Android)
followed by an /xxxx-xxxx drive ID.
APP paths are nested in PHONE, in an Android/data subfolder
and named for the app—here, com.quixotely.usbsync.
C:\,
/Users, or /home, and removable-drive paths with
D:\, /Volumes, or /media—all on
Windows, macOS, and Linux, respectively, and followed by your user ID,
a drive name, or nothing. ROOT paths may be just / on
Unix or a drive letter on Windows, and mapped network drives on Windows
use UNC paths of the form \\server\drive.
This just reflects the fact that the app's user-friendly
storage-button labels (like PHONE and MYSSD)
are meant to abstract—and spare you from—some of
these gory device-specific details. For a deeper dive, try Mergeall's path overviews
here
and
here.
Also remember that the app saves your path selections every time you run a Main-tab action. Because you'll normally use the same paths in most of your runs on a given device, you can usually use the saved paths restored on future app opens, and skip the chooser selection step altogether.
New: as of 1.1.0, the app also displays storage names along with folder paths in action-confirmation dialogs, to help you remember the devices that correspond to your chosen paths. More info here.
On Android, this app's support for locations hosting your content on removable drives varies by Android version. Removable drives include both USB drives and embedded microSD cards. These drives are read by PC-to-phone syncs, and updated by both phone-to-PC syncs and phone backups. The rules for these operations depend on your phone's Android:
Details: on Android 10 and earlier, updates to removables work only in the
com.quixotely.usbsync subfolder nested in the drive's
Android/data folder.
This app folder is
created automatically when you use this app's folder chooser with your
removable drive attached. Like on-phone APP storage described
above, it is also automatically removed
on uninstalls and app-data clears on these Androids if your drive is
attached; use with care.
In practical terms, this means that if you're using Android 10 or earlier, you should host content in this app-specific folder on removable drives if it will be either backed up from your phone, or synced from your phone to your PC. Content used only in other roles (e.g., in PC-to-phone syncs) need not follow this rule, and Androids 11 and later are exempt from it altogether.
This constraint reflects an unfortunate convolution in Android (in short, removable-drive updates on earlier Androids require proprietary Java APIs which are not viable for portable POSIX programs), but it impacts only updates to removable drives on Android 10 and earlier. Removable reads are unrestricted on all Androids, and Androids 11+ do not constrain removable updates.
In case you forget this schism, the app will warn you on older Androids if you select an invalid removable folder for a Main-tab action that may update the folder. The action will be cancelled because all its updates would fail with error messages in the log. If you get this warning, please relocate your content to the app-specific folder as needed and retry the action. Where possible, you might also consider upgrading to a newer Android with less draconian rules.
Related: some phones running Android 10 and earlier may report removable drives in this app's folder chooser both before they are fully mounted, and after they've been unmounted but before their cable is detached. The app will display inaccessible-storage error dialogs in both cases, and you can safely ignore the ghost entries: wait till mounting is finished, and pull the cable to fully unmount. This is arguably a bug on earlier Androids, and Androids 11 and later create no such ghosts.
Each of the Main tab's green-button actions creates a logfile to let you know what it did, and these logfiles are an important part of this system. You should almost always inspect a run's logfile, or at least its summary, to verify that it didn't run into problems. The Logs tab provides tools that let you easily monitor and review the actions' logfiles easily. Here, you can:
The next sections provide more details on this tab's tools, from top to bottom.
The top of this tab lists your logfile folder's path (chosen automatically per platform), and all the logfiles in that folder. Scroll the logfiles vertically and tap to select one to process. Because you'll usually want to process the most-recent logfile, the app automatically preselects it whenever you open this tab; this lets you proceed to one of this tab's green action buttons right away.
On all platforms, logfiles are stored in a subfolder named for the
app and nested in your primary storage's Documents folder
(located in storage type PC on PCs
and PHONE on Android, covered
above).
This subfolder is auto-cleaning to avoid taking up too
much space; you can set the number of logfiles to keep in the Config
tab, but the preset default normally works well.
Beside vertical scrolls, the Logs tab's logfile list also scrolls horizontally if needed, though this normally does not kick in above the GUI's minimum usable size. That is, the large fonts and narrow displays required to make these horizontal scrolls useful may also render other parts of the GUI difficult to view or operate. Still, logfile lists scroll both ways where required for space.
As of 1.2.0, logfile selections in this list apply to the TAIL and OPEN actions covered below, but not to WATCH or EXPLORE. TAIL and OPEN are alternative ways to view a specific log's contents, while WATCH always monitors the current run's logfile, and EXPLORE opens a file-explorer on the entire folder.
As of 1.1.0, you can also double and triple tap logfile-name buttons in this list to quickly run a TAIL or TAIL+OPEN, respectively, but we need to move on to see what these actions do.
Note that while an action is in progress, TAIL can be used to check in on status, but the end of the file it shows is transitory (it will change as the action runs, invalidating the display). Because of that, this action may be more useful after a run finishes. For dynamic file-tail updates, use WATCH instead; TAIL generally shows more content, but WATCH updates automatically per the next item.
New: as of 1.1.0, a TAIL can also be run by double-tapping a logfile-name button directly, instead of single-tapping to select a file and then tapping TAIL. This works only if WATCH is not running. More details here.
This action works as a toggle, and disables TAIL, because WATCH gets control of the text-display area until it ends. Because WATCH makes sense only if an action is running, it refuses to start (with a popup message) at other times. Because it also makes sense only to watch the currently running action's logfile, WATCH always uses this file and ignores any logfile selected in the GUI.
WATCH does not significantly slow the watched action. It may add roughly 10% to the total runtime of the watched action on some PCs, but may actually make the watched action run up to 10 times faster on some Android devices due to Android's task-scheduling policies (though this boost does not occur on all phones).
Because it can slow progress and drain batteries on some devices, though, WATCH is turned off automatically if it's left on for 60 seconds. To restart the WATCH, simply tap it again. You can also tap TAIL when you just want to spot-check status, and both the Main tab's animated GIF image and notifications for Android services can also be checked if you just want to see if an action is still running.
New: the above description of WATCH refelects a redesign in release 1.2.0. Prior to that, WATCH used the logfile selected in the GUI, but only the running action's log was valid for this action. With 1.2.0, selections in the GUI are ignored, and the app instead uses the internally known logfile of the current run. This frees you from ensuring a correct GUI selection, and sidesteps issues that can arise when the host's clock is set to a time in the past. More details here.
New: as of 1.1.0, an OPEN can also be run by triple-tapping a logfile-name button directly, instead of single-tapping to select a file and then tapping OPEN. OPEN can be launched this way even if a WATCH is running, and triple taps also run a TAIL along with the OPEN (details).
The bottom of this tab displays logfile text for the TAIL and WATCH actions above it. The text scrolls text both vertically and horizontally (and truncates abnormally long lines to avoid errors). You can set the colors of this area and change font sizes globally as you prefer in the Config tab—per the next section.
As a convenience, TAIL auto-scrolls to the bottom left of this area's text when new text is loaded. WATCH auto-scrolls to the bottom on each text load. WATCH also scrolls to the left when the watched action ends, but not on text inserts; this allows you to stay positioned on the right of watched text, so you view the end of long messages and paths.
This tab allows you to customize both app behavior and appearance. Most of its settings are applied either immediately, or when their subject is next used; global font size is applied with an Apply tap to avoid jarring changes. This tab also lets you both save all your settings to be reused in future runs, and restore setting defaults to start over without having to reinstall the app.
Settings are persisted by this app in two different ways:
All persisted settings are automatically restored and reapplied on future runs, but are not directly editable in their saved format, and are stored in locations that vary per platform:
~/Library
folder in a subfolder named for the app, and never deleted on app
removals.
settings.pkl in the app's
install folder next to the executable; save and restore this
to retain your settings across app deletions.
For more info on each platform's settings policies, please see platform data coverage in the App Packages guide.
This section is a quick rundown of the settings you can customize in the Config tab, from top to bottom in the tab:
Tip: don't confuse SYNC backups enabled here with backing up your content folders to a USB drive in general. The former records just the changes made during a SYNC in the TO folder; the latter is a broader usage mode you perform with SYNC. Put another way: SYNCs run during backup operations will back up their changes in TO if this toggle is on, so the backup operation can be rolled back with UNDO.
.DS_Store files and ._*
AppleDouble files that litter removable drives used on that platform,
as well as common clutter files on Windows and Linux, and Python bytecode
files that are better recreated than propagated on destination devices.
Note that this toggle does not apply to nonportable items in general: symlinks and nonportably named files, for example, are still processed as usual (per this overview). This toggle applies only to proprietary, single-platform items that are undesirable in content that spans many devices.
You should generally leave this toggle on everywhere, but for more details on the items that this filters out, see the Mergeall overview here. Cruft is formally defined at the end of this code file; there is no way to redefine cruft in this app, because that has not proven useful in a decade of Mergeall usage.
There is no significant performance penalty for using foreground services (and they may avoid app kills, as noted here), so you should generally leave this toggle on for Android. It's forced off on Android 8, because that Android (alone, among the Androids 8..13 tested) doesn't support this app's foreground-service code. Threads are also available as a fallback option if the services default ever stops working in the future; this is not expected, but Android's rapid morph warrants precaution. Toggle off to use the threads alternative if needed.
This setting is preset to on to disable timeouts and screen savers, so users have time to view info in popups and logfiles. To change this permanently (and hence enable screen timeouts and savers), simply toggle this setting to off and save your settings with the bottom-of-display Save button. This setting was added in 1.1.0; see its News post.
__bkp__
folder. See the Main tab's UNDO for more info.
Backups are normally small, because they include
only items changed or deleted in TO, along with a record of
items added. Higher values here use more space, but also
allow UNDO to roll back SYNCs further in the past.
#rrggbbaa hex-values string and applied to the text.
The color string is display only; please use Pick to set it with the chooser.
#rrggbbaa hex-values string and applied to the text.
The color string is display only; please use Pick to set it with the chooser.
Finally, the two buttons at the bottom of the Config tab let you process its settings as a set:
This tab's main section is a plain-text, scrollable rendition of the content in this online guide's Usage Overview. It's available in the app for off-line reading and reference.
Also on this tab is a bank of buttons for addition information and resources, most of which open online web pages. From left to right and top to bottom:
In closing, the About tab's text provides logistical information about the app: version info, copyright statement, privacy policy, and more. You'll also find links for fetching this app from the Play store and its website at the bottom of the tab.
Notable here: be sure to see this tab's usage caution. While this app's core Mergeall code has been used for a decade, and the app itself has been well tested, things can and do go wrong in both the software and hardware realms. As mentioned above, enabling SYNC backups for UNDO goes a long way towards mitigating your risks.
More importantly, when used well, the content backups that this app generates by nature go even further towards ensuring the longevity, privacy, and safety of your valued content.
You've reached the end of this GUI guide, but there are more help resources for this app. If you haven't read the general overview yet, you may want to browse it now. And if you're ready to install and run the app, check out the App Packages guide next.
