CubeCart Upgrade Builder

A macOS utility that automates upgrading CubeCart installations while preserving your customisations. It detects your current version, downloads the latest release from GitHub, and intelligently merges your custom changes into the new version.

What It Does

1. Detects your current CubeCart version and admin folder/file names from an existing installation
2. Fetches the latest CubeCart release version from GitHub
3. Downloads both your current and latest version archives (if not already downloaded)
4. Extracts both versions and renames the admin folder/file to match your installation
5. Copies your live installation as a source reference
6. Generates patches showing:
   • The stock upgrade diff (your version → latest)
   • Your customisations diff (stock version → your modified source)
7. Applies your customisations to the latest stock version automatically
8. Reports which customisations applied cleanly and which need manual merging

Requirements

• macOS
• curl, diff, patch, rsync, unzip (all included with macOS)
• An existing CubeCart installation accessible via the filesystem

Installation

Option A: Build the macOS App

1. Clone this repository:

   git clone https://github.com/cubecart/upgrade-builder.git

2. Open Script Editor (Applications → Utilities → Script Editor)
3. Open main.applescript from the cloned repository
4. Go to File → Export…
5. Set File Format to Application
6. Save as CubeCart Upgrade Builder.app to your Applications folder
7. Copy prepare_comparison.sh into the app bundle:

   cp prepare_comparison.sh "/Applications/CubeCart Upgrade Builder.app/Contents/Resources/"
   chmod +x "/Applications/CubeCart Upgrade Builder.app/Contents/Resources/prepare_comparison.sh"

Option B: Run the Shell Script Directly

No installation needed — just clone and run:

git clone https://github.com/cubecart/upgrade-builder.git
cd upgrade-builder
chmod +x prepare_comparison.sh

Usage

Using the macOS App

1. Double-click CubeCart Upgrade Builder.app
2. Select your CubeCart installation folder when prompted
3. Enter a prefix/domain name (e.g. example.com) for organising the output folders
4. Wait for the process to complete

Using the Shell Script

./prepare_comparison.sh /path/to/cubecart example.com

Or run interactively (you will be prompted for each value):

./prepare_comparison.sh

Arguments:

Argument	Description	Example
INSTALL_PATH	Full path to your CubeCart installation	/var/www/html/shop
PREFIX	Domain or label for organising output folders	example.com

Output

All output is created under ~/Downloads/<prefix>/:

~/Downloads/example.com/
├── 6.4.0/                    # Extracted stock FROM version
├── 6.5.0/                    # Extracted stock TO version
├── source/                   # Copy of your live installation
├── upgraded/                 # Stock TO + your customisations applied
├── upgrade_6.4.0_to_6.5.0.patch        # Stock upgrade diff
├── customisations_6.4.0.patch           # Your customisations diff
└── upgrade_6.5.0_to_upgraded.patch      # Final diff vs stock TO

Understanding the Results

• All customisations applied cleanly: The upgraded/ folder is ready to deploy. Review the changes, then replace your live installation.
• Some conflicts detected: Clean patches are applied automatically. Conflicting files are listed in the output and need manual merging. Use the generated patch files to guide your merge.
• No customisations detected: Your installation matches stock CubeCart. Simply use the latest stock version as your upgrade.

How It Works

The tool uses diff and patch under the hood:

1. A customisation patch is generated by diffing stock CubeCart (your current version) against your live source. This isolates only your changes.
2. The customisation patch is then applied to the latest stock release, effectively rebasing your changes onto the new version.
3. Line-ending differences (CRLF vs LF) are normalised before comparison to avoid false positives.
4. Only files present in the stock distribution are compared — cache, uploads, and other non-application files are ignored.

Licence

See LICENCE for details.