Connecting and Syncing Themes (Push/Pull/Publish)

Now that you have the Shopify CLI installed and a theme to work with, it’s time to master the most important skill in theme development: syncing your work between your local machine and Shopify’s servers.

Understanding Theme States

Before diving into commands, let’s clarify the three states a theme can be in:

Development Theme

Created automatically when you run shopify theme dev. These themes:

• Are hidden from customers
• Auto-delete after 3 days of inactivity
• Perfect for active development work
• Named “Development” with a number suffix

Unpublished Theme

A saved theme that isn’t live:

• Persists indefinitely until you delete it
• Can be previewed via a special URL
• Great for staging, client review, or backup
• You can have multiple unpublished themes

Published Theme

The live theme your customers see:

• Only one theme can be published at a time
• Changes here affect real customers immediately
• Treat with care. Always test before publishing

Pulling Themes from Shopify

The pull command downloads a theme from your store to your local machine.

Basic Pull

shopify theme pull

You’ll be prompted to:

1. Select a store (if you have access to multiple)
2. Choose which theme to download

Files are downloaded to your current directory.

Pull to a Specific Folder

Keep your projects organized:

shopify theme pull --path ./client-theme

Pull a Specific Theme

If you know the theme ID:

shopify theme pull --theme 123456789

Find theme IDs in your admin URL when viewing a theme, or list them:

shopify theme list

Selective Pulling

Only pull specific files or folders:

# Pull only sections
shopify theme pull --only "sections/*"

# Pull specific files
shopify theme pull --only "layout/theme.liquid" --only "config/settings_schema.json"

When to Pull

Common scenarios for pulling:

• Starting work on an existing client theme
• Getting updates made by someone else (or via the admin)
• Backing up before major changes
• Syncing settings changed in the theme editor

Pushing Changes to Shopify

The push command uploads your local files to Shopify.

Basic Push

shopify theme push

This pushes to your development theme by default.

Push to a Specific Theme

Target a particular theme:

shopify theme push --theme 123456789

Create a New Unpublished Theme

Upload as a new theme for review:

shopify theme push --unpublished

This creates a fresh theme you can share with clients or team members.

Selective Pushing

Push only what you’ve changed:

# Push a single file
shopify theme push --only "sections/header.liquid"

# Push a folder
shopify theme push --only "assets/*"

# Push multiple specific items
shopify theme push --only "sections/*" --only "snippets/*"

Ignoring Files During Push

Skip certain files:

shopify theme push --ignore "config/settings_data.json"

Publishing a Theme

When your theme is ready to go live:

Publish an Existing Theme

shopify theme publish --theme 123456789

You’ll be asked to confirm since this affects your live store.

Push and Publish Together

For a streamlined deployment:

shopify theme push --theme 123456789 --publish

Warning: Use this carefully! It immediately makes your changes live.

Managing settings_data.json

This file deserves special attention. It contains:

• All theme customizations made in the editor
• Section positions and settings
• Color schemes and typography choices
• Store-specific content

The settings_data.json Problem

When working with a team or on multiple environments:

1. You customize the theme in the admin
2. Your teammate pushes their local settings_data.json
3. Your customizations disappear

Solutions

Option 1: Always ignore it

Add to your push commands:

shopify theme push --ignore "config/settings_data.json"

Option 2: Use .shopifyignore

Create a .shopifyignore file in your theme root:

config/settings_data.json

Now it’s ignored automatically on every push.

Option 3: Track it carefully

If you need consistent settings across environments, track it in Git but communicate clearly with your team about who “owns” the settings.

My Recommendation

For most projects:

1. Ignore settings_data.json during pushes
2. Let the store owner manage settings in the admin
3. Only push code changes (sections, snippets, templates, assets)

Using .shopifyignore

The .shopifyignore file works like .gitignore but for Shopify syncing.

Creating the File

In your theme root, create .shopifyignore:

# Ignore settings (store-specific)
config/settings_data.json

# Ignore backup files
*.backup
*.bak

# Ignore temp files
temp/*
.tmp

# Ignore development files
notes.md
TODO.md

Common Ignore Patterns

Preview URLs for Stakeholder Review

Need to share your work before publishing?

Getting a Preview URL

After pushing to an unpublished theme:

shopify theme push --unpublished

The CLI outputs a preview URL like:

https://your-store.myshopify.com/?preview_theme_id=123456789

Sharing the Preview

Share this URL with:

• Clients for approval
• Team members for review
• QA testers

Note: Anyone with the URL can see the preview, but they can’t make changes.

Preview via Theme List

Get preview URLs for all themes:

shopify theme list

Or in the admin: Online Store → Themes → … → Preview

Safe Workflow Patterns

Pattern 1: Development Theme Flow

Best for active development:

# Start development server (creates dev theme)
shopify theme dev

# Work locally, changes sync automatically
# When ready, push to staging
shopify theme push --unpublished

# After approval, push to production
shopify theme push --theme [production-id]

Pattern 2: Feature Branch Flow

For larger changes:

# Pull the current production theme
shopify theme pull --theme [production-id] --path ./feature-branch

# Make changes locally
# Push as new unpublished theme for review
shopify theme push --unpublished

# After approval, push to production
shopify theme push --theme [production-id]

Pattern 3: Emergency Hotfix

When you need to fix something fast:

# Pull the live theme
shopify theme pull --theme [production-id]

# Make the minimal fix
# Push only the changed file
shopify theme push --theme [production-id] --only "sections/header.liquid"

Golden Rules

1. Never push directly to production without testing first
2. Always use --ignore for settings_data.json unless you’re certain
3. Create unpublished themes for review before publishing
4. Pull before pushing if others might have made changes
5. Use selective pushing to minimize risk

Quick Reference

Troubleshooting

”Theme not found” Error

Verify the theme ID:

shopify theme list

Make sure you’re authenticated to the right store.

Conflicts During Pull

If files have changed both locally and remotely:

1. Back up your local changes
2. Pull the remote version
3. Manually merge your changes back in

Push Seems Slow

Large themes take time. Use selective pushing:

shopify theme push --only "sections/*"

What’s Next?

You now know how to move themes between your local machine and Shopify. Next up:

• Version control: Learn Git basics for tracking changes and collaborating
• Linting: Use Theme Check to catch errors before they reach production
• Liquid fundamentals: Start writing real theme code

Master these sync commands, and you’ll have complete control over your theme workflow!