Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 61 ยท Publishing and Maintenance

Version Control and Team Workflows

Manage a Shopify theme with Git: GitHub integration, one branch per theme, theme pull and push, .shopifyignore, and merging merchant edits to JSON files.

A theme is a folder of text files, so it belongs in Git. The catch is that a Shopify theme has two kinds of authors. You change Liquid, CSS and JavaScript. The merchant changes settings_data.json and the JSON templates every time they press Save in the theme editor. If you ignore that second author, one careless push can wipe out a week of their work.

This lesson shows how a healthy workflow looks: where Git is the source of truth, how branches map to themes, how the CLI moves files in both directions, and how to merge the files you share with the merchant. It builds on Setting Up: Dev Store, Partner Account and Shopify CLI and the folder tour in The Theme File Structure.

The commands and configuration below are real Shopify tooling and are read-only here, because the site cannot reach a store. The live examples are JavaScript stand-ins that mimic the merge logic and the ignore rules, and say so. Menus and flags change over time, so check shopify theme push --help on your own machine for the current options.

Who owns which file

Not every file has the same owner. Knowing this tells you what Git must protect.

File or folder Usually changed by Risk when overwritten
sections/, snippets/, blocks/, assets/, layout/ developers none, this is your code
locales/*.json developers (and sometimes merchants) lost translations
config/settings_schema.json developers none
config/settings_data.json merchants (theme editor) lost colors, fonts, content
templates/*.json and section groups both lost page layouts

The two merchant-owned rows are the whole difficulty. A JSON template records which sections a page has, in what order, with which settings and blocks. When a merchant drags the testimonials section above the footer, your repository does not know.

Strategy 1: GitHub integration

Shopify offers a built-in GitHub integration. In the admin you open the theme library, choose to connect a theme from GitHub, authorize the Shopify GitHub app for a repository, and pick a branch. From then on that theme and that branch are linked:

  • A commit pushed to the branch updates the theme files on Shopify.
  • A change the merchant saves in the theme editor is committed back to the branch.

This gives you history for free, including the merchant's edits, with commit messages generated by Shopify. Because a branch maps to exactly one theme, the natural layout is one branch per theme role:

flowchart LR
  A["feature/new-footer<br/>developer branch"] --> B["staging branch"]
  B --> C["main branch"]
  B -.-> D["Staging theme<br/>unpublished"]
  C -.-> E["Live theme<br/>published"]

Branches feed Git; each long-lived branch is connected to one theme in the store.

Keep the connected branches few and boring: typically main (the live theme) and staging (a duplicate used for review). Do feature work on short-lived branches that are not connected to a theme, then merge them. Connecting every feature branch to its own theme works, but you quickly hit the limit on how many themes a store can hold.

One more rule: the files in the repository should mirror the theme folder structure, so the folders sections, templates, config and the rest sit where Shopify expects them. Do not nest your theme inside extra build folders unless a tool you trust copies it back out before deployment.

Strategy 2: Git plus the CLI

Many teams prefer to drive everything from the command line and a CI server. The Shopify CLI has the commands for that.

Terminal
# Start a local preview on a temporary development theme
shopify theme dev --store my-dev-store.myshopify.com

# Download the files of a theme into the current folder
shopify theme pull --theme 123456789012

# Upload local files to a theme (an unpublished one)
shopify theme push --theme 123456789012

# See your themes and their ids
shopify theme list

pull copies files from Shopify to your disk. push copies files from your disk to Shopify and, by default, can delete remote files that do not exist locally, so read what it plans to do. Both accept --only to restrict a run to files that match a pattern, and --ignore to skip some. push also has --nodelete to keep remote files that are missing locally, and it refuses to touch the published theme unless you add an explicit flag, which is a deliberate safety catch. Your own commits are the "source of truth" for code; the merchant's saved settings are the thing you must pull before you push.

A practical rule: never push to the live theme from a laptop. Push to a staging theme, check it, then promote it as described in Testing, Publishing and Going Live.

A pull before push routine

Before you start a task that touches templates or settings, fetch the merchant's current state into a clean branch:

Terminal
git switch main
shopify theme pull --theme 123456789012 --only config/settings_data.json --only "templates/*.json"
git diff              # what did the merchant change since our last sync?
git add -A && git commit -m "Sync merchant edits from live theme"

Now your history shows exactly what the merchant changed and when, and any feature branch you cut from main starts from reality.

.shopifyignore

A file named .shopifyignore in the theme root lists paths that the CLI should skip when it pushes, pulls or watches files. Each line is a pattern, and lines starting with # are comments.

TEXT
# Merchant-owned data: never overwrite from our repo
config/settings_data.json
templates/*.json
templates/customers/*.json
sections/*-group.json

# Local tooling that must not reach Shopify
*.map
node_modules/**

This is the cleanest protection for a code-only workflow: the repository deploys Liquid, CSS and JS, and the merchant keeps their settings and layouts. The price is that brand-new JSON templates and new default settings you add will not reach the store either, so you must deliver those deliberately (see the merge section next).

Pattern details, such as exact glob support, can differ between CLI versions. Test a new pattern with a small push to a throwaway theme before trusting it.

Merging merchant edits

Git merges JSON line by line. That is a poor fit for the files that both of you edit, because a reordered section or a changed color can produce conflicts that look random. Three habits keep this manageable:

  1. Keep the files small and sorted. The theme editor writes JSON in a stable order, so avoid reformatting the files by hand.
  2. Sync often. The longer you wait, the larger the difference between your copy and the live one.
  3. Decide a winner per type of change. Usually the merchant wins on content and colors, and you win on new settings and structure.

That decision is a three-way merge: compare your version and the merchant's version with their common ancestor (the last time you synced). If only one side changed a value, take that side. If both changed it the same way, fine. If both changed it differently, that is a true conflict that a person must resolve.

JS Stand-in: a three-way merge of settings_data.json

Press Run (or Ctrl + Enter) to see the console output here.

No output.

This is a stand-in: real settings files contain more types of values, and Git does not do this merge for you. But the logic is exactly what a good merge tool applies. Notice that the new cart_type setting you added arrives in the result, the merchant's announcement text survives, and only accent needs a human decision.

Stand-in: what .shopifyignore protects

The second example reads a list of ignore patterns and shows which files a push would send. It supports only *, ** and exact names, which is enough to see the idea. The real CLI's matching is its own implementation.

JS Stand-in: which files would a push send?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Working with merchants' live edits

Some practical situations come up in every long-running store:

  • The merchant edits the live theme while you build a feature. Pull their JSON files before you start, and again before you release. Your feature branch is judged against the live state, not against last month's.
  • You add a new section that should appear on a page. Adding the Liquid file is safe. Putting it into a JSON template is a change to merchant-owned data, so deliver it as a note ("add the Reviews section on the product page") or merge it with the three-way logic above.
  • Two developers share one store. Each uses their own development theme from shopify theme dev, which is temporary and private to the person who started it. Never share a single development theme.
  • A merchant hand-edits code in the admin. The code editor in the admin still exists. Tell the team to avoid it, or connect GitHub so that those edits are committed and visible.

If you are building a theme to sell rather than for one store, there is no merchant data to protect while you develop, but the same discipline applies to the update process described in Maintaining Themes: Updates and API Versions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which theme file is most likely to be changed by a merchant in the theme editor?

    The editor writes the merchant's saved values to settings_data.json. Pushing your own copy over it erases those choices.
  2. 2. What does connecting a GitHub branch to a theme do?

    The integration syncs both ways. It does not publish by itself; publishing a theme is a separate decision.
  3. 3. What is the purpose of a .shopifyignore file?

    It only affects the Shopify CLI. It is not a Git feature and it does not change what shoppers see.
  4. 4. In a three-way merge, what should happen when only the merchant changed a value since the last sync?

    If one side is unchanged from the common ancestor, the other side's change wins without a conflict. Only differing changes by both sides are true conflicts.

Summary

  • Developers own code files; merchants own settings_data.json and, in practice, many JSON templates. Protect the second group.
  • GitHub integration links one branch to one theme and syncs in both directions; keep connected branches few and use short-lived feature branches.
  • Use shopify theme pull before you start and push only to an unpublished theme; never push to the live theme from a laptop.
  • .shopifyignore keeps merchant-owned files out of a push, and a three-way merge combines changes when both sides edit.
  • Give every developer their own development theme.

Next, take the finished work through review and release in Testing, Publishing and Going Live.