Index of /mergeall-products/unzipped (original) (raw)

• Parent Directory
• .nomedia
• UserGuide.html
• _README.txt
• __sloc__.py
• __version__.py
• _publish.sh
• android-scripts-and-gui/
• autoflush.py
• backup.py
• build/
• cpall.py
• deltas.py
• diffall.py
• dirdiff.py
• docetc/
• fix-fat-dst-modtimes.py
• fix-nonportable-filenames.py
• fixfrozenpaths.py
• fixlongpaths.py
• fixunicodedups.py
• guimaker_pp4e.py
• icons/
• launch-mergeall-Console.py
• launch-mergeall-GUI.pyw
• mergeall.py
• mergeall.py-devdocs.txt
• mergeall_configs.py
• nuke-cruft-files.py
• rollback.py
• scandir_defunct.py
• skipcruft.py
• test/

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]