Git Basics for Theme Projects

You’ve been making changes to your theme, and things are going well. Then you try something ambitious, break everything, and desperately wish you could go back to “the way it was before.” Sound familiar?

Git solves this problem. It’s a version control system that tracks every change you make, lets you experiment safely, and makes collaboration possible. Every professional developer uses it, and you should too.

Why Version Control Matters

Without Git, theme development is risky:

• No undo history: One bad change can break your theme
• No collaboration: Working with others means overwriting each other’s work
• No experimentation: Trying new ideas feels dangerous
• No backup: If your laptop dies, your work dies with it

With Git:

• Every change is tracked: Roll back to any previous state
• Safe branching: Experiment without affecting your main work
• Team collaboration: Multiple people can work on the same theme
• Distributed backups: Push to GitHub and your work is safe forever

Installing Git

Git might already be on your machine.

Check If Git Is Installed

git --version

If you see a version number, you’re good. If not:

Install Git

macOS:

# Via Homebrew
brew install git

# Or install Xcode Command Line Tools
xcode-select --install

Windows:

Download from git-scm.com and run the installer.

Linux:

# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

Configure Git

Set your identity (used in commit history):

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Initializing a Repository

A Git repository (repo) tracks changes in a directory.

Starting Fresh

Navigate to your theme folder and initialize:

cd my-shopify-theme
git init

You’ll see:

Initialized empty Git repository in /path/to/my-shopify-theme/.git/

Git creates a hidden .git folder that stores all version history.

Your First Commit

After initializing, create your first snapshot:

# Stage all files
git add .

# Create the commit
git commit -m "Initial theme setup"

Congratulations! Your theme’s current state is now saved forever.

Creating a .gitignore File

Not everything should be tracked. Create a .gitignore file in your theme root:

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

# OS files
.DS_Store
Thumbs.db

# Editor directories
.vscode/
.idea/
*.swp
*.swo

# Dependencies (if using build tools)
node_modules/

# Logs and temp files
*.log
tmp/
temp/

# Shopify CLI files
.shopify/

Why Ignore settings_data.json?

This file contains store-specific customizations:

• Section positions
• Color choices
• Content entered in the theme editor

Each store should have its own settings. Tracking this file causes conflicts when working across multiple stores or with a team.

Add .gitignore to Your Repo

git add .gitignore
git commit -m "Add gitignore for Shopify theme"

Core Git Workflow

Here’s the daily workflow you’ll use:

1. Check Status

See what’s changed:

git status

Output shows:

• Untracked files: New files Git doesn’t know about
• Modified files: Changed since last commit
• Staged files: Ready to be committed

2. View Changes

See exactly what changed in a file:

git diff sections/header.liquid

Or see all changes:

git diff

3. Stage Changes

Tell Git which changes to include in the next commit:

# Stage a specific file
git add sections/header.liquid

# Stage multiple files
git add sections/header.liquid snippets/icon.liquid

# Stage all changes
git add .

4. Commit Changes

Save a snapshot with a descriptive message:

git commit -m "Add mobile menu toggle to header"

5. View History

See past commits:

git log

For a compact view:

git log --oneline

Writing Good Commit Messages

Commit messages are notes to your future self (and teammates). Make them useful.

Bad Messages

git commit -m "changes"
git commit -m "fix"
git commit -m "update"
git commit -m "stuff"

These tell you nothing when you’re looking back.

Good Messages

git commit -m "Add sticky header on scroll"
git commit -m "Fix product image aspect ratio on mobile"
git commit -m "Update footer links to use new navigation"
git commit -m "Remove deprecated announcement bar section"

Message Format Tips

• Start with a verb: Add, Fix, Update, Remove, Refactor
• Be specific: What changed and why
• Keep it short: Under 72 characters ideally
• One change per commit: Don’t bundle unrelated changes

Branching for Features

Branches let you work on features without affecting your main code.

Why Branch?

Imagine you’re adding a mega menu. It takes three days. Meanwhile:

• A bug appears on the live site
• The client needs a quick text change
• You want to try a different approach

Without branches, all this work is tangled together. With branches, each task is isolated.

Creating a Branch

# Create and switch to a new branch
git checkout -b feature/mega-menu

# Or in two steps
git branch feature/mega-menu
git checkout feature/mega-menu

Listing Branches

git branch

The asterisk shows your current branch:

  main
* feature/mega-menu

Switching Branches

git checkout main

Branch Naming Conventions

Use descriptive names:

• feature/mega-menu
• fix/mobile-cart-bug
• update/footer-links
• experiment/new-pdp-layout

Basic Merge Workflow

When your feature is complete, merge it back to main.

Step 1: Commit Everything on Your Branch

git add .
git commit -m "Complete mega menu implementation"

Step 2: Switch to Main

git checkout main

Step 3: Merge Your Branch

git merge feature/mega-menu

If there are no conflicts, Git combines the changes automatically.

Step 4: Delete the Branch (Optional)

git branch -d feature/mega-menu

Handling Merge Conflicts

Sometimes Git can’t automatically merge. You’ll see:

CONFLICT (content): Merge conflict in sections/header.liquid

Open the file and look for conflict markers:

<<<<<<< HEAD
<h1>{{ shop.name }}</h1>
=======
<h1 class="site-title">{{ shop.name }}</h1>
>>>>>>> feature/mega-menu

Edit the file to keep what you want, remove the markers, then:

git add sections/header.liquid
git commit -m "Resolve merge conflict in header"

Hosting on GitHub

GitHub (or GitLab, Bitbucket) provides:

• Remote backup: Your code lives in the cloud
• Collaboration: Share with team members
• History visualization: Browse commits in a nice UI
• Pull requests: Review code before merging

Pushing to GitHub

1. Create a repository on GitHub (don’t initialize with README)
2. Connect your local repo:

git remote add origin https://github.com/yourusername/your-theme.git

3. Push your code:

git push -u origin main

Pulling Updates

If changes were made on GitHub (or by teammates):

git pull origin main

Recovering from Mistakes

Git’s superpower is undoing things.

Undo Uncommitted Changes

Discard changes to a file:

git checkout -- sections/header.liquid

Discard all uncommitted changes:

git checkout -- .

Undo a Staged File

Remove from staging (keep the changes):

git reset sections/header.liquid

Undo the Last Commit

Keep changes, undo commit:

git reset --soft HEAD~1

Discard changes and commit:

git reset --hard HEAD~1

Warning: --hard permanently deletes changes!

View a Previous Version

See how a file looked before:

git show HEAD~3:sections/header.liquid

Restore a File from History

Bring back an old version:

git checkout HEAD~3 -- sections/header.liquid

Git + Shopify CLI Workflow

Here’s how Git fits with your Shopify workflow:

Starting a Project

# Pull theme from Shopify
shopify theme pull --path ./client-theme

# Initialize Git
cd client-theme
git init
git add .
git commit -m "Initial pull from production"

Daily Development

# Create feature branch
git checkout -b feature/new-header

# Start dev server
shopify theme dev

# Make changes...

# Commit regularly
git add .
git commit -m "Add logo to header"

# More changes...
git add .
git commit -m "Add navigation links"

Deploying

# Merge to main
git checkout main
git merge feature/new-header

# Push to Shopify
shopify theme push --theme [production-id]

# Push to GitHub
git push origin main

Quick Reference

What’s Next?

You now have the fundamentals of Git for theme development. As you get comfortable:

• Learn about git stash for temporarily saving work
• Explore GitHub pull requests for code review
• Set up branch protection for team projects

Next up: Theme Check and Linting. Catch errors before they reach production!