Mergeall — Backup and Sync Your Stuff Your Way Version: 3.3, October 16, 2022 (all-packages release) Author: © M. Lutz (https://learning-python.com), 2014-2022 License: Provided freely, but with no warranties of any kind. This program is open source and is yours to use and copy as you like for personal use. For quality and attribution purposes, any bulk redistributions must include in full and unaltered form this file, and file "UserGuide.html" and folders "docetc" and "test" from the top level of this package. Please note: Mergeall changes a destination folder in-place by design. It backs up items changed or removed during a run and supports rollbacks, but you should understand its purpose before running it on your content. Read section "Usage Cautions" in file "UserGuide.html" before using it. Fetch: From "https://learning-python.com/mergeall.html" download and unzip: - Mergeall.app.zip (macOS app) - Mergeall-64bit.zip (Windows executable) - Mergeall.zip (Linux executable) - Mergeall-source.zip (source code) All packages are Mergeall 3.3. The macOS, Windows, and Linux packages use Python 3.8 and were built on Catalina, Windows 11, and Ubuntu 20, respectively. See Package Usage Basics below for more install details. Start: To launch the program's GUI, run the unzipped folder or its file: - Mergeall.app (macOS app) - launch-mergeall-GUI.exe (Windows executable) - launch-mergeall-GUI (Linux executable) - launch-mergeall-GUI.pyw (source code) Besides its syncs GUI, Mergeall includes a system of scripts which may be run from a console command line: mergeall.py, deltas.py, diffall.py, cpall.py, and more. See Package Usage Basics below for more run details. Docs: Open UserGuide.html in any web browser to read the main user guide. Select 'Help' in the GUI to view that document in most distributions. Screenshots: See UserGuide.html or folder docetc/docimgs for GUI samples. Configs: Edit mergeall_configs.py to customize Mergeall's appearance and behavior. Backups: When backups are enabled, Mergeall saves all files deleted or changed by a run in the __bkp__ folder of the "TO" destination. See UserGuide.html. Tools: Mergeall is coded in Python, and uses tkinter/Tk for its GUI. macOS frozen apps are built with py2app; others use PyInstaller. For using the source package, Python 3.X is strongly recommended. Versions: 3.3, Oct-2022: normalization changes, all download packages rebuilt 3.3, Mar-2022: minor GUI changes, apps and executables rebuilt for 3.3 3.3, Dec-2021: major release - Unicode normalization for filename matching 3.2, Oct-2021: major release - deltas.py deferred-updates script and mode 3.1, Dec-2017: minor upgrade - folder modtimes, Linux flushes, "-u" 3.0, Jun-2017: major release - GUI redesign, macOS port, cruft skips, app/exes Versions 3.3 and 3.2 were initially released in the source-code package only, but 3.3 was later pushed out to all app and executable packages too. See docetc/MoreDocs/Revisions.html for all versions and changes. Upgrades: To install a new version of Mergeall in the future, save and restore any customizations you've made in mergeall_configs.py. Updates: Watch https://learning-python.com/post-release-updates.html for new-release announcements and additional usage pointers. ------------------------------------------------------------------------------ Package Usage Basics Mergeall is available as full source code, a macOS app, and executables for Windows and Linux. In brief, here are the formats' tradeoffs: Source code Pros: the ultimate in portability; may have more recent updates; may be run with a more recent Python and Tk; required on Android Cons: requires and dependent on a separately installed Python Apps and executables Pros: integrate better with your computer's GUI; do not require any additional install steps; generally immune to future changes in both the Python programming language and Tk they use Cons: not portable, may lose functionality over time as platforms morph Apps and executables are like most installed software and launch with a click, though source code can also be launched quickly with shortcuts. Also note that the source-code package may grow more recent that the apps and executables over time, and hence is generally preferred. The following sections give the fundamentals of each format's usage: - macOS App Package - Windows Executable Package - Linux Executable Package - Source-Code Package ------------------------------------------------------------------------------ macOS App Package The macOS (f.k.a. OS X) app runs only on Macintosh systems, but requires no Python install and better supports the Macintosh user experience. To install: Fetch file "Mergeall.app.zip", unzip it by a double-click (or other), and drag the resulting Mergeall.app to your /Applications folder in Finder to access it from Launchpad. You can also move Mergeall.app and create aliases to it anywhere else on your computer. To Run: Click "Mergeall.app" to start the program (or run the app any other way). Running Mergeall.app automatically launches Mergeall's GUI launcher, the same as running the source-code package's launch-mergeall-GUI.pyw. From the GUI, configure and run Mergeall to propagate your content. Clicking Mergeall's app icon or Dock entry while the program is running automatically deiconifies (unhides) its main window, and always lifts it above other windows on screen (handy to locate it in a busy session). Double-click the app and single-click the Dock to make this work. Files: Your mergeall_configs.py file is located inside the unzipped app's folder, at path: Mergeall.app/Contents/Resources Navigate to this nested folder in Finder by a right-click on Mergeall.app and Show Package Contents (or use "ls" in Terminal). Your UserGuide.html is in the same folder, but can also be accessed by the program's "Help" button. Scripts: All Mergeall scripts are frozen executables in the app's folder: Mergeall.app/Content/MacOS The scripts have no ".py" extension in this format, but otherwise run exactly as documented. No separate Python install is required to run these from command lines in Terminal. For example, if you've drug the unzipped folder to your /Applications, the following work in Terminal: CPALL: /Applications/Mergeall.app/Contents/MacOS/cpall dirFrom dirTo -skipcruft DIFFALL: /Applications/Mergeall.app/Contents/MacOS/diffall dir1 dir2 -skipcruft /Applications/Mergeall.app/Contents/MacOS/diffall dir1 dir2 -skipcruft -u > log.txt MERGEALL: /Applications/Mergeall.app/Contents/MacOS/mergeall dirFrom dirTo -report /Applications/Mergeall.app/Contents/MacOS/mergeall dirFrom dirTo -auto -backup -skipcruft LAUNCHERS: /Applications/Mergeall.app/Contents/MacOS/launch-mergeall-Console /Applications/Mergeall.app/Contents/MacOS/launch-mergeall-GUI (the same as an app click) OTHER: /Applications/Mergeall.app/Contents/MacOS/deltas /Applications/Mergeall.app/Contents/MacOS/rollback /Applications/Mergeall.app/Contents/MacOS/fix-fat-dst-modtimes folder -add /Applications/Mergeall.app/Contents/MacOS/nuke-cruft-files -help Note that source-code versions of these scripts are also included in the app's Contents/Resources folder for their documentation, but will not generally run in this form and location; use the frozen executables in Contents/MacOS instead. Versions: The macOS app was built on macOS (a.k.a. OS X) version 10.15 Catalina on an Intel-based system, using Python 3.8. It is expected to work on later macOS versions too regardless of chip architectures, though this remains to be verified, as does support for earlier macOS versions. Known issues: Due to limitations in the underlying software stack, some non-ASCII characters may be replaced for display; see the user guide for details. Due to the underlying Tk toolkit, messages may scroll slowly in the GUI. It may speed scrolling to minimize/restore the window to the Dock. macOS Mojave users: this iteration of macOS temporarily broke Tk GUIs for the sake of a dark-mode change. For a fix and work-around, see: https://learning-python.com/post-release-updates.html#macosmojavestartup. In the 3.3 app, widgets lose their active styling when the GUI window is minimized and restored; click elsewhere and back to reset. The 3.1 app's fix for this is disabled, as it no longer works and may abort. [This following does not apply to the 3.3 Feb-2022 macOS app.] Due to a flaw in the underlying Tk toolkit, closed windows may leave zombie items in Dock menus; these can be safely ignored. See also https://learning-python.com/post-release-updates.html#appexpose. ------------------------------------------------------------------------------ Windows Executable Packages The Windows executables run only on Windows systems, but require no Python install and better support the Windows user interface. NEW: as of the Feb-2022 executable for Mergeall 3.3, only a 64-bit build is provided online. Older references to a 32-bit build are now moot, but see "Versions" below for options on older machines. To install: Fetch file "Mergeall-64bit.zip" and unzip it on your computer Copy the unzipped folder to \Users\\Desktop or elsewhere to save it. Make Desktop shortcuts to the unzipped folder's executable (per the next section) for quick access as desired. To Run: Click on the unzipped folder's "launch-mergeall-GUI.exe" file to run. This automatically starts Mergeall's GUI launcher, the same as running the source-code package's script launch-mergeall-GUI.pyw. From the GUI, configure and run Mergeall to propagate your content. File "launch-mergeall-console.exe" runs the lesser-used console interface. Files: Your UserGuide.html, mergeall_configs.py, and utility-script exes are are all located at the top level of the same folder as the main ".exe" executable (the folder created by unzipping the download). Scripts: Mergeall's extra utility scripts in this package are all provided as executables that have a ".exe" extension instead of a ".py" and can be run without a local Python install, but otherwise work the same. For example, the source package's diffall.py and rollback.py become ".exe" executables in this package (the ".exe" in these is usually optional): Mergeall-64bit\diffall.exe folder1 folder2 -skipcruft Mergeall-64bit\rollback.exe Scripts' ".py" source files are also included for their in-file documentation, but some may not run in this form; use their .exes. See the macOS app's documentation above for more utility scripts. Versions: The Windows executable comes in only 64-bit form, as denoted by its zipfile name. This works only on 64-bit systems; to use Mergeall on older 32-bit machines, either run its source-code package, or build a 32-bit executable from Mergeall's build script in the build/ folder. The sole 64-bit executable was built on Windows 11 21H2, using Python 3.8; it should work on this and later Windows, though support for later and earlier Windows is unverified. Known issues: Due to limitations in the underlying software stack, some non-ASCII characters may be replaced for display; see the user guide for details. Startups may be briefly delayed due to PyInstaller folder extracts. An SSD system drive is recommended for quicker starts, but use the source-code package if this is problematic on slower machines. IMPORTANT: Tk GUIs like Mergeall's may have blurry fonts on some versions of Windows when first started. For a simple one-time fix, see this note: https://learning-python.com/post-release-updates.html#win10blurryguis. Antivirus programs can have a massive impact on Windows performance, in one measured case slowing a diffall.py run by a factor of 5 (1 hour versus 12 minutes). As usual, disable such programs for faster runs. ------------------------------------------------------------------------------ Linux Executable Package The Linux executable runs only on Linux systems, but requires no Python install and may better support the Linux user interface. To install: Fetch file "Mergeall.zip" and unzip it on your computer. Copy the unzipped folder to your home, desktop, or other folder to make it easy to access, and make desktop shortcuts to the executable as desired. To Run: Click on the unzipped folder's "launch-mergeall" file to run. This automatically starts Mergeall's GUI launcher, the same as running the source-code package's script launch-mergeall-GUI.pyw. From the GUI, configure and run Mergeall to propagate your content. File "launch-mergeall-console.exe" runs the lesser-used console interface. Files: Your UserGuide.html, mergeall_configs.py, and utility-script executables are all located at the top level of the same folder as the main executable (the folder created by unzipping the download). Scripts: Mergeall's extra utility scripts in this package are all provided as executables that have no extension instead of a ".py" and can be run without a local Python install, but otherwise work the same. For example, the source package's diffall.py and rollback.py become Linux executables in this package: Mergeall/diffall folder1 folder2 -skipcruft Mergeall/rollback Scripts' ".py" source files are also included for their in-file documentation, but some may not run in this form; use the executables. See the macOS app's documentation above for more utility scripts. Versions: The sole Linux executable was built on Ubuntu Linux 20.04 on a 64-bit system, using Python 3.8. It is known to work on this and other versions of Ubuntu and is expected to work on some other distributions of Linux, but this is to be verified. If it fails on your system, use the source-code Mergeall package instead. Known issues: Due to limitations in the underlying software stack, some non-ASCII characters may be replaced for display; see the user guide for details. Startups may be briefly delayed due to PyInstaller folder extracts. An SSD system drive is recommended for quicker starts, but use the source-code package if this is problematic on slower machines. exFAT is now in the Linux kernel but still maturing, and there are new notes on using FAT-32 and exFAT removable drives on your platform: https://learning-python.com/post-release-updates.html#mergealllinuxmodtimes. [This following does not apply to the 3.3 Feb-2022 Linux executable.] As of Dec-2020, the 2017 Linux executables are no longer recommended, due to font breakage resulting from platform morph. For details, see: https://learning-python.com/post-release-updates.html#linux2017executables. ------------------------------------------------------------------------------ Source-Code Package The source-code version of Mergeall runs on all flavors of macOS, Windows, and Linux, but requires a separately installed Python. The source-code also runs on all recent versions of Android. To Install: Fetch file "Mergeall-source.zip" and unzip it on your computer. Also fetch and install a usable Python 3.X if one is not already present. On macOS and Linux, also install the tkinter/Tk toolkit if needed. See the user guide's "Platform Basics" for details. To Run: Run "launch-mergeall-GUI.pyw" in the unzipped folder to launch the program's GUI, using any Python program-launching technique on your platform: Windows icon clicks, IDLE, command lines, macOS Python Launcher, etc. You can also run the file from within the PyEdit GUI (see learning-python.com/pyedit). Files: Your UserGuide.html, mergeall_configs.py, and utility scripts are all located in the same folder as the main scripts' file (the folder created by unzipping the download). Scripts: As this package includes full source code, all its non-GUI tools are available as script text files. Run its top-level mergeall.py, deltas.py, diffall.py, cpall.py, and the fix-*.py utilities from a console command line as usual. See scripts for argument details. Versions: Source code is platform-neutral and is not dependent on the version of your operating system. This package runs on all versions of macOS, Windows, and Linux in common use today. The source-code package does, however, require and assume a separately installed Python on your computer: download one for your platform from www.python.org/downloads if Python is not already installed. Mergeall's source code has been verified to run on all Python 3.X through 3.10, and has no third-party install requirements. Later Python versions are expected to work too, but 3.10 is the latest version verified. Due to its support, Python 3.X is strongly recommended for content with non-ASCII filenames. Known issues: Due to limitations in the underlying software stack, some non-ASCII characters may be replaced for display; see the user guide for details. On macOS, messages may scroll slowly in the GUI. It may speed message scrolling to minimize the window to the Dock and restore it later. On recent versions of macOS, widgets lose their active styling when the GUI window is minimized and restored; click elsewhere and back to reset. On macOS with older Pythons, due to a flaw in the underlying Tk toolkit, closed windows may leave zombie but harmless items in Dock menus. See https://learning-python.com/post-release-updates.html#appexpose. On Windows, you may need to "set PYTHONIOENCODING=utf8" to avoid errors for non-ASCII output messages, when using command lines and redirecting output to files. See UserGuide.html#pythonioencoding. On Windows, Tk GUIs like Mergeall's may have blurry fonts when first started on some versions. For a simple fix, see this usage note: https://learning-python.com/post-release-updates.html#win10blurryguis. On Windows, antivirus programs can have a massive impact on performance, in one measured case slowing a diffall.py run by a factor of 5 (1 hour versus 12 minutes). As usual, disable such programs for faster runs. On Linux, exFAT is now in the kernel but still maturing, and there are new notes on using FAT-32 and exFAT removable drives on this platform: https://learning-python.com/post-release-updates.html#mergealllinuxmodtimes. On Android, Mergeall scripts work normally in Termux or similar, and its GUI works in Pydroid 3 but requires code patches. See: https://learning-python.com/mergeall-android-scripts/_README.html, https://learning-python.com/using-tkinter-programs-on-android.html. On Android 11 and later, Mergeall does not have direct access to USB drives. To perform to-phone syncs on these devices, see this package: https://learning-python.com/android-deltas-sync/, https://learning-python.com/android-deltas-sync/_README.html. ------------------------------------------------------------------------------ [end]