Skip to content

Branch Management#

Branch Management in Miva Merchant provides a powerful version control system for your store’s templates, CSS/JS resources, and theme components. Using branches, developers can safely experiment, develop, and test changes in an isolated environment before promoting them to the live storefront.

What Is a Branch?#

A branch is an isolated copy of your store’s templates and assets. Every Miva store has at least one branch — the primary branch — which serves live traffic. Additional branches act as sandboxes where you can develop and preview changes without affecting the live site.

Each branch has:

  • A unique name and color chip for visual identification in the admin
  • A preview URL (using a BranchKey query parameter) for testing changes before going live
  • A changeset history tracking every discrete set of changes made to the branch

There are two special branch states:

State Description
Primary Branch The branch currently serving live traffic to your customers
Working Branch The branch you are currently editing in the admin interface

The Branch Status Box#

The Branch Status Box is located in the upper-left corner of the User Interface panel. It displays the name and color of your currently active (working) branch and is the entry point for all branch operations.

Clicking the Branch Status Box opens the Branch Controls Menu, which provides access to:

  • Create New Branch — Create a new branch from an existing one
  • Switch Branch — Change your active working branch
  • Merge — Selectively apply changesets from one branch to another
  • Copy — Replicate a full branch history up to a specific changeset
  • Set as Primary — Promote a branch to serve live traffic
  • Delete — Remove an unused branch

Changesets#

A changeset is a discrete, named record of one or more changes made to a branch. Every time you save changes to templates, CSS/JS resources, or theme components, those changes are grouped into a changeset.

Changesets are the units of work used during Merge and Copy operations. They allow you to:

  • Track exactly what changed, when, and by whom
  • Add descriptive notes and tags for documentation
  • Selectively pick which changes get promoted to another branch

A changeset can contain any combination of:

  • Template changes — Page and global template source updates
  • CSS Resource changes — Stylesheet source updates
  • JavaScript Resource changes — Script source updates
  • Managed Property changes — Theme component settings (banners, navigation sets, content sections, etc.)

Managing Branches#

Creating a Branch#

When you create a new branch, Miva duplicates an existing branch as the starting point. All templates and assets from the source branch are available immediately in the new branch.

Steps to Create a Branch:

  1. Navigate to User Interface > Templates in the Miva admin.
  2. Click the Branch Status Box in the upper-left corner.
  3. Select Create New Branch from the Branch Controls Menu.
  4. Enter a Name for the new branch.
  5. Choose a Color to visually identify the branch.
  6. Select the Branch to copy from as the starting point.
  7. Click Create.

Benefits of Creating Branches:

  • Isolate new feature development from the live site
  • Allow multiple developers to work on different features simultaneously
  • Provide a safe environment for major redesigns or template overhauls

Switching Branches#

You can switch your active working branch at any time without affecting the live site. Switching branches changes the templates and assets you see and edit in the admin, but does not change what customers see.

Steps to Switch Branches:

  1. Click the Branch Status Box in the upper-left corner.
  2. Select the branch you want to work in from the branch list.

The Branch Status Box updates to reflect the newly selected working branch.

Previewing a Branch#

Each branch has a unique preview URL that lets you view the storefront as it would appear if that branch were live. This is useful for reviewing changes before merging or setting a branch as primary.

The preview URL format is:

https://yourdomain.com/storefront.html?BranchKey=<unique_branch_key>

The BranchKey is a unique identifier assigned to each branch. You can share this URL with stakeholders for review without impacting live traffic.

Merging Changesets#

Merge allows you to selectively apply specific changesets from one branch into another. Only the changesets you explicitly select are applied — giving you fine-grained control over what gets promoted.

Steps to Merge Changesets:

  1. Click the Branch Status Box and open the Branch Controls Menu.
  2. Select Merge and choose the target branch (e.g., the primary/production branch).
  3. Select the changesets you want to merge from the changeset list.
  4. Add a description to document the merge.
  5. Confirm the merge to apply the selected changes.

Key Considerations:

  • Only the selected changesets are applied — other changes on the source branch remain unaffected
  • Merge smaller, focused changesets to reduce risk and simplify review
  • Always use the preview URL to verify changes before merging into the primary branch

Copying a Branch#

Copy replicates a branch’s entire changeset history up to and including a specific changeset. Unlike Merge (which is selective), Copy brings over all changes from the source branch up to the chosen point, overwriting the destination branch.

Steps to Copy a Branch:

  1. Click the Branch Status Box and open the Branch Controls Menu.
  2. Select Copy and choose the source branch to copy from.
  3. Specify the changeset up to which you want to copy.
  4. Confirm to overwrite the destination branch with the copied history.

When to Use Copy vs. Merge:

Operation Use When
Merge You want to selectively apply specific changesets to another branch
Copy You need a full, point-in-time snapshot of a branch (e.g., creating a staging branch from production)

Setting the Primary Branch#

The primary branch is the branch live customers see. You can promote any branch to primary at any time, making it the live version of your store.

Steps to Set the Primary Branch:

  1. Click the Branch Status Box and open the Branch Controls Menu.
  2. Select Set as Primary for the branch you want to make live.
  3. Confirm the change.

Warning

Setting a branch as primary immediately affects your live storefront. Always preview the branch thoroughly before promoting it.

Deleting a Branch#

Unused branches can be deleted to keep your branch list organized. The primary branch (marked as immutable) cannot be deleted.

Steps to Delete a Branch:

  1. Click the Branch Status Box and open the Branch Controls Menu.
  2. Select Delete next to the branch you want to remove.
  3. Confirm the deletion.

Note

Deleting a branch permanently removes all its changesets and template history. This action cannot be undone.

Template Version History#

In addition to branch-level changesets, Miva Merchant tracks version history for individual templates. Every time a template is saved, a new version is recorded automatically.

Key Features:

  • Automatic Versioning — Every save creates a restorable version snapshot
  • Revert to Previous Versions — Restore any template to an earlier state
  • Version Details — Each version includes a timestamp, author, and diff view highlighting what changed

How to Access Template Version History:

  1. Open any template in the admin editor.
  2. Click the Version History icon within the template editor.
  3. Browse the version list and select a version to preview or revert to.

Gotchas and Common Pitfalls#

Resource Groups Are Global#

Resource Groups are not branch-specific — they exist globally across all branches. This has two important consequences:

  • Assigning a CSS or JavaScript resource to a resource group affects every branch immediately, not just the one you’re working in.
  • Deleting a resource group removes it from the entire store across all branches. There is no branch-level isolation for this action.

Danger

Deleting a resource group is a global, irreversible action. Always confirm that no other branch depends on the resource group before deleting it.

When working with CSS and JS resource group assignments as part of a changeset, be aware that the group structure itself is shared — only the resource versions (source content) are tracked per branch.

Branch-Specific Templates: What Varies Per Branch#

Not all content in the admin is controlled by templates in the usual sense. The following areas do render based on the active working branch, meaning what you see (and what customers see via the preview URL) will reflect the branch-specific version:

Area Notes
Header Template The global header template is branch-specific — changes are isolated to the branch until merged
Footer Template The global footer template follows the same branch-specific behavior
Product/Category Header Template The product/category-level header template is branch-specific
Product/Category Footer Template The product/category-level footer template is branch-specific
Category Images Category images are stored and served based on the working branch — image updates made in one branch will not appear in other branches until the changeset is merged

This branch-specific behavior is intentional and allows you to safely preview template and image changes in isolation. However, it can cause confusion if you expect a change made in one branch to appear in another without an explicit merge.

Warning

If you update a category image or a header/footer template on a development branch and then switch to the primary branch in the admin, you will see the primary branch’s version of those assets — not your development changes. Always confirm you are in the correct branch before drawing conclusions about why a change isn’t showing.

Best Practices#

  1. Use branches for all significant work — Never develop directly on the primary branch. Always create a dedicated branch for features, redesigns, or experiments.

  2. Name branches descriptively — Use names like holiday-promo-2025 or homepage-redesign so the purpose is immediately clear to all team members.

  3. Keep changesets focused — Group related changes into a single changeset with clear notes. Smaller changesets are easier to review, merge, and roll back.

  4. Preview before promoting — Always use the branch preview URL to verify changes are correct before merging into the primary branch.

  5. Clean up finished branches — Delete branches once their changes have been merged and verified to keep the branch list manageable.

  6. Document your merges — Add meaningful notes when merging changesets so the change history is useful for future debugging.

Summary#

Branch Management in Miva Merchant gives developers a safe, structured workflow for managing storefront changes. By working in isolated branches and promoting changes through changesets, teams can collaborate efficiently and deploy updates with confidence.

Key Takeaways:

  • The primary branch serves live traffic; all other branches are sandboxes
  • Changesets record discrete groups of changes and are the units used for Merge and Copy operations
  • Merge selectively applies changesets; Copy replicates the full branch history to a point
  • The Branch Status Box in the admin is the central control panel for all branch operations
  • Template Version History provides per-template rollback independent of branch operations