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]
![[Home page]](../../PythonPowered.gif "Home page"){kind=small}