Version Control with Git

When you ran shopify theme init, the CLI initialised a Git repository inside your theme folder without making a big deal about it. If you’ve never used Git before, that might not mean much yet. This page covers enough of it to make your theme work meaningfully safer, without going into the full depth of what Git can do.

The short version: Git lets you take snapshots of your theme at any point in time. If you push a change that breaks something, or spend two hours going in the wrong direction, you can get back to a known-good state rather than trying to remember what you changed and undo it manually.

1. You already have a repository

Run git status from inside your theme folder and you’ll see a list of files described as “untracked”.

git status

Untracked just means Git is aware the files exist but isn’t recording changes to them yet. Once you start adding and committing, it will be.

The .git folder in your project root is where Git stores everything. You don’t need to open it or touch it.

2. The basic workflow: add and commit

The basic Git workflow is two steps: add, then commit.

git add stages a file, which is Git’s way of saying “include this in the next snapshot”. git commit then takes that snapshot and saves it with a message you write.

git add sections/header.liquid
git commit -m "Update header font size"

To stage everything that’s changed at once:

git add .
git commit -m "Your message here"

On commit messages: keep them short and specific. “Update header font size” is useful. “changes” is not. You’ll thank yourself when you’re reading back through the history months later trying to work out what you did and when.

A commit doesn’t have to capture every individual line change. The right time to commit is when something is complete and working, not after every edit.

3. Branching before risky changes

A branch is a separate line of development where you can make changes without affecting the main version. The habit worth building: before starting any significant edit, create a branch. If it works out, merge it back. If it doesn’t, delete the branch and nothing on main was ever touched.

git checkout -b new-header-design

Work on the branch, commit as you go, then merge it back when you’re happy:

git checkout main
git merge new-header-design

This is worth doing even when working alone. Anything touching theme.liquid or the layout folder is a good candidate for a branch, since those files affect every page on the store.

4. Rolling back

git log shows your commit history. Each commit has a hash, a timestamp, and the message you wrote.

git log --oneline

If your most recent commit broke something, git revert HEAD creates a new commit that undoes it. This is the safe option because it doesn’t rewrite history, it just adds a correction on top.

git revert HEAD

If you haven’t committed yet and just want to discard changes to a specific file and get back to how it was at the last commit, git restore does that:

git restore sections/header.liquid

The rule of thumb: use revert for committed changes, restore for things you haven’t committed yet.

5. The settings_data.json question

settings_data.json stores the values a merchant has saved in the Theme Editor: their brand colours, font choices, the content inside sections. It updates every time someone hits save in the editor.

The question is whether to commit it. The risk of committing it is that a future push could overwrite a merchant’s saved settings with whatever values happened to be in the file when you last committed. For most situations, especially when working on a client’s store, that’s not something you want.

The safest approach is to add it to .gitignore, which tells Git to leave the file alone entirely. Your code changes are what matter; the settings values are store-specific data that Shopify manages.

echo "config/settings_data.json" >> .gitignore
git add .gitignore
git commit -m "Ignore settings_data.json"

6. What’s next

That’s enough Git to work safely as a solo developer on a Shopify theme. There’s a lot more to it: remotes, GitHub, pull requests, working with a team. But that’s beyond the scope of this section.

The next page covers section schema and settings, which is where you’ll start to see how Liquid and the Theme Editor actually connect.