Forking a template

Forking creates a workspace-owned copy of a global mapping template that you can edit freely. The original global template stays intact and keeps serving every other workspace.

When to fork

Fork when the merchant’s data needs a transform the global template doesn’t produce. Common triggers:

• A custom Magento attribute that needs to land in a specific Shopify metafield.
• An image CDN with a different host than the source store URL.
• Localized option values the global mapping doesn’t normalize.
• A bespoke discount-rule structure.

When not to fork

• The default looks slightly different but the merchant doesn’t care about the difference. Don’t fork to satisfy taste.
• The merchant wants a feature that should exist for everyone. File it as a request to improve the global template instead — every workspace benefits.
• You haven’t run an extract yet. Always fork against real data.

How to fork

Open the mapping and click Fork to edit in the editor header. One click does three things:

1. Copies the current default template’s version into a new template your workspace owns.
2. Repoints this migration’s mapping at that fork.
3. Leaves every other migration alone — they stay on the default.

You can’t edit a default template in place, so this is what the editor offers instead of a disabled Publish button. After forking, publishing writes into your fork’s version history.

Pulling in upstream changes

The global template will keep evolving. Forks don’t auto-update. To re-base a fork on a newer global version:

1. Open the fork. Note the upstream template + version it diverged from.
2. Manually apply the upstream changes you want — Version history in the editor diffs any earlier version against what you have open, line by line, which makes this tractable.
3. Publish it as a new version of your fork.

For now this is a manual step. Automated re-base is on the roadmap.