Skip to main content
Tutorial

Resolving Merge Conflicts When You Upgrade a Theme

When UltraCart releases a new version of your theme, the upgrade merges the new theme code into your theme and keeps the template edits you made. Usually that merge happens on its own. When you and the theme developer changed the same lines of the same file, UltraCart cannot choose for you. That is a merge conflict, and you resolve it in a three-pane editor.

This tutorial walks through a real upgrade of the Hero theme from version 1.25 to 1.26 with three conflicts, one for each kind of decision you will make: take the new code, combine both changes, and take the new code and re-apply your own change. It also covers how to back out if the result is wrong.

Merchants who skip conflicts tend to stop upgrading altogether, and their theme falls many versions behind on fixes and security updates. Each conflict is usually a single line and takes a minute or two once you know what the three panes mean.

Before you start​

  • Read the theme's revision log so you know what the new version changes.
  • Know which template files you, or a developer, edited by hand. The upgrade check lists them for you.
  • Settings, theme attributes, and override.css survive upgrades cleanly. Only hand edits to template files can conflict. See Customizing a theme.

Step 1: Run the upgrade check​

  1. Go to Main Menu → StoreFronts, select your StoreFront, then select Themes under Appearance.
  2. Select the theme tab, then select the orange Upgrade to x.xx banner on the theme image.

The Theme Upgrade - Check dialog appears. It reads your theme before changing anything and shows one of three results.

No modified files. Nothing you edited is affected, and the upgrade can go ahead.

The Theme Upgrade - Check dialog saying all theme files are unmodified or will merge without conflict, with a Proceed button

Modified files that will merge. You edited these files, but in places the new version did not touch. UltraCart merges them for you. You type upgrade to confirm.

The Theme Upgrade - Check dialog listing two modified files that will merge during the upgrade, with a field to type the word upgrade

Modified files that will conflict. You and the new version changed the same lines. The dialog lists each file. You resolve them after the upgrade, before you activate the theme.

The Theme Upgrade - Check dialog listing three files that will result in a merge conflict, outlined in red

Write down the files in the list, then select Cancel. Back up the theme before you continue.

Step 2: Back up the theme​

A duplicate of the theme is your undo button for the whole upgrade.

  1. Hover over the theme image and select the Duplicate icon.
  2. Leave the StoreFront as it is. Enter a folder name that says what it is, such as HeroBackup125 for Hero version 1.25. Letters and numbers only.
  3. Select duplicate and wait for the copy to finish. Do not leave the page while it runs.

The StoreFront Theme Duplicate dialog with the theme folder set to HeroBackup125

The backup appears as its own tab on the Themes screen. Do not upgrade or edit it. It stays on the old version so you can return to it.

The Themes screen with a new Hero tab for the /themes/HeroBackup125/ folder next to the original Hero tab

If the theme is your active theme, resolve the conflicts on a copy rather than on the theme your live site is running. When the pre-upgrade check finds conflicts, it offers Duplicate and Upgrade: the copy is upgraded, you resolve the conflicts in the copy, and you activate the copy when it is right. Your live site keeps running the old version in the meantime.

Step 3: Run the upgrade​

  1. Select Upgrade to x.xx again.
  2. Type upgrade in the confirmation field and select Proceed.

The Theme Upgrade - Check dialog with the word upgrade typed in the confirmation field and the Proceed button enabled

The upgrade writes the new files, recompiles containers, and recalculates template metadata. Keep the tab open until it finishes.

The Theme Upgrading dialog showing a progress bar at Recompiling containers, 190 of 231

Step 4: Find the files in conflict​

When the upgrade finishes, UltraCart emails you a StoreFront Theme Upgrade notification. It names the StoreFront, the theme, and the new version. Under Merged with Conflicts, it lists each customized file that needs your attention.

Keep that email until every listed file is resolved. If you closed the browser tab during the upgrade, the email is your list of files to fix.

  1. Go to File Manager.
  2. Select the merge conflicts icon in the toolbar. It searches the whole StoreFront.

The File Manager toolbar with the merge conflicts icon outlined in red and three files listed in the results

Each file in conflict shows [merge conflict] next to its version number. Select a file name to open it.

A banner at the top of the editor confirms the file has conflicts. Select it to dismiss it, then select the full screen icon at the right of the toolbar. The panes are much easier to read full screen.

The file editor with a banner at the top reading This file contains merge conflicts, and the Merged File header showing 1 conflict to resolve

Step 5: Read the three panes​

The full screen merge editor showing the New Theme File, Merged File, and Your Modified File panes side by side

PaneWhat it is
New Theme File (left)The new version of the file from UltraCart.
Merged File (middle)The file you are building. This is what gets saved. Its header counts the conflicts left.
Your Modified File (right)Your version of the file, with your edits.

Edits of yours that did not conflict are already in all three panes. In this example the brand font link added near the top of the file merged by itself.

Each conflict shows in the middle pane as one line:

<<<<<<< choose code for this merge conflict >>>>>>>

A close-up of the middle pane with the conflict line in green between the two outer panes

The arrow in the gutter between two panes copies that side's lines into the merged file:

  • The arrow between the left and middle panes takes the new theme code.
  • The arrow between the right and middle panes takes your code.

You can also type directly in the middle pane. You need to for a combined fix.

Step 6: Decide each conflict​

Ask one question for each conflict: what was the new version trying to fix, and what was my edit for? Then pick one of these three resolutions.

Take the new code, and move your change to a setting​

Use this when the new version now does what your edit did, usually through a setting.

In this example the merchant had hard-coded a custom favicon path in document_top.vm. The new version fixed a broken default favicon and reads the favicon from the StoreFront Favicon setting.

  1. Select the arrow between the left and middle panes. The new lines replace the conflict line, and the header changes to 0 conflict(s) to resolve.

    The merge editor after taking the new theme code, with the Merged File header showing 0 conflicts and the Save button enabled

  2. Select Save.

    The merge editor after saving, with the Save button greyed out and a new last modified time

  3. Put your custom value where the new code reads it. Here that is the StoreFront Favicon setting on the General tab. See Set a favicon.

Combine both changes​

Use this when both sides matter. This is the most common case, and it matters most when the new version is a security fix.

In this example the merchant had added a CSS class and an icon to the info message line in info_messages.vm. The new version wrapped the message in $i18n.escape() so that message text is always displayed as plain text.

The info_messages.vm file with one conflict, showing the new line on the left and the merchant's changed line on the right

  1. Select the arrow between the right and middle panes to bring in your line.

    The header now says 0 conflict(s), but the new escaping is gone. The left pane still highlights the line as different. Zero conflicts does not mean the file is correct.

    The merge editor after taking the merchant's line, with 0 conflicts but the left pane still highlighting the new line as different

  2. In the middle pane, edit the line to add the new code. Here, change $!msg to $i18n.escape($!msg).

    The middle pane scrolled right, showing the finished line with the icon and $i18n.escape($!msg)

  3. Select Save.

A correctly combined line looks different from both the left and right panes. That is expected.

Take the new code, then re-apply your change​

This gives the same result as combining, starting from the other side. It is the safer choice when the new version changed a lot on the line and your edit was small.

In this example the merchant had made the wholesale signup form default to United States. The new version escaped the country values.

The wholesale_signup_application.vm file with one conflict on the country option line

  1. Select the arrow between the left and middle panes to take the new line.

  2. In the middle pane, make your edit again on top of it.

    The middle pane after taking the new country option line, with 0 conflicts and the Save button enabled

  3. Select Save.

When to keep only your version​

Rarely. Keep only your version when the new code does not apply to your store and the revision log shows the change is cosmetic. Never drop a change the revision log describes as a security, escaping, or checkout fix. Combine instead.

Step 7: Check your work​

  1. Run the merge conflicts search in the File Manager again. It should return no files.

    The File Manager merge conflicts search returning There are no files in this directory

  2. Run the files with compile errors search (the warning triangle icon). A resolved file with a typo will show up here.

  3. Preview the upgraded theme before you activate it. See Preview a theme before activating it. Check the pages that use the files you resolved, and place a test order if you resolved a checkout file.

  4. Activate the theme when it is right.

Back out if something is wrong​

Undo one file​

Every save is kept in the file's version history. Select the file's version number in the File Manager to open it.

The File History dialog for document_top.vm with five versions, the Merged With Conflicts version outlined in red

An upgraded file with a conflict has a history like this, newest first:

CommentWhat that version is
(none)Your resolved file
Merged With ConflictsWhat the upgrade produced, with the conflict lines in it
Theme - new versionThe new theme file exactly as UltraCart ships it
(none)Your edit, before the upgrade
Theme - old versionThe file exactly as UltraCart shipped the old version
  • Select diff to compare any version with the current one.
  • Select revert on Merged With Conflicts to start the file's resolution over.
  • Select revert on the new theme version to drop your edit and use UltraCart's file as shipped.

A revert saves a new version, so you can undo it too.

Undo the whole upgrade​

Activate the backup theme you made in Step 2. Your StoreFront goes back to the old version immediately. Delete the upgraded copy later, or keep working on it until it is ready.

Was this page helpful?