Mergeall — Backup and Mirror Your Stuff Your Way
Version:
3.3, December 2021 (source-code package release)
Author:
© M. Lutz (https://learning-python.com), 2014-2021
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 (Mac app)
- Mergeall-64bit.zip or Mergeall-32bit.zip (Windows executable)
- Mergeall.zip (Linux executable)
- Mergeall-source.zip (source code)
Apps and executables are currently version 3.1; source code is 3.3.
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 (Mac 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.
Mac frozen apps are built with py2app; others use PyInstaller.
For using the source package, Python 3.X is strongly recommended.
Versions:
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 released in the source-code package only.
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 Mac 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, as of version 3.3, the source-code package is now two
releases ahead of apps and executables, and hence generally preferred.
The following sections give the fundamentals of each format's usage:
- macOS App Package
- Windows Executable Packages
- Linux Executable Package
- Source-Code Package
------------------------------------------------------------------------------
macOS App Package
The macOS (f.k.a. OS X) app runs only on Mac systems, but requires
no Python install and better supports the Mac 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/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.11 El Capitan,
as a Mac universal binary. It has been verified to run on this as well
as macOS 10.12 Sierra through 10.15 Catalina, and is expected to work on
later macOS versions too (though emulation may be required for systems
using the newer Apple CPU architecture: TBD). Support for earlier macOS
versions also remains to be verified (feedback is welcome).
Known issues:
Due to limitations in the underlying Tk toolkit, emojis are replaced
for display only; see the user guide for details.
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.
Due to the underlying Tk toolkit, messages may scroll slowly in the
GUI. It may speed scrolling to minimize 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.
------------------------------------------------------------------------------
Windows Executable Packages
The Windows executables run only on Windows systems, but require
no Python install and better support the Windows user interface.
To install:
Fetch file "Mergeall-64bit.zip" or "Mergeall-32bit.zip" and unzip
it on your computer (see Versions below for the difference).
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 Mac app's documentation above for more utility scripts.
Versions:
The Windows executable comes in both 64- and 32-bit forms, as denoted
by its zipfile names. The former works only on 64-bit systems; the
latter works more broadly but may run slower on 64-bit systems. The
64-bit executable was built on Windows 7, and the 32-bit version on
Windows 8, but exes are known to work on Windows 7, 8, 10, and 11.
Known issues:
Startups may be briefly delayed due to PyInstaller folder extracts.
Use the source-code package if this is problematic on slower machines.
Due to limitations in the underlying Tk toolkit, emojis are replaced
for display only; see the user guide for details.
Tk GUIs like Mergeall's may have blurry fonts on some versions of
Windows when first started. For a simple fix, see this usage 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
*Per the last known issue ahead, source code is now preferred on Linux*
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 Mac app's documentation above for more utility scripts.
Versions:
The sole Linux executable was built on Ubuntu Linux 16.04, on a
64-bit system. 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.
Known issues:
Startups may be briefly delayed due to PyInstaller folder extracts.
Use the source-code package if this is problematic on slower machines.
Due to limitations in the underlying Tk toolkit, emojis are replaced
for display only; see the user guide for details.
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.
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 Mac,
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 Mac 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, Mac
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 Tk toolkit, emojis are replaced
for display only, on all platforms; see the user guide for details.
On macOS, closed windows may leave zombie items in Dock menus due
to a flaw in the underlying Tk toolkit; use Tk 8.6+ if possible. See
also https://learning-python.com/post-release-updates.html#appexpose.
On macOS, messages may scroll slowly in the GUI. It may speed
scrolling to minimize the window to the Dock.
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-scripts/,
https://learning-python.com/android-deltas-scripts/_README.html.
------------------------------------------------------------------------------
[end]
![[Home]](../../PythonPowered.gif){kind=small}