This is part one of a three part beginner’s guide to Git with Shopify.
Check out part two of this series on states, branching, conflicts, and SSH keys »
A lot of people have heard of Git, but have never actually used it before. It can be an intimidating subject, and especially challenging for those who don’t have experience with the command line. It becomes more important to think about how to keep track of all the changes we make in our code as projects become more complicated, when we collaborate with other developers, or when we just want to know what’s been worked on or fixed in a project.
Git has a lot of magical powers, and admittedly, in every course I’ve ever taken on Git I always learn something new, because there are so many ways of using Git. This is because Git is vast – there’s so much to learn that it can be hard to know where to start. My intention with this series of articles is to help you understand what Git is, how to use it, and what that workflow can look like when working with Shopify themes.
So...what the heck is Git and why is it useful?
Git is a distributed version control system. What this means is that Git helps you track changes to your code and collaborate with other developers. Version control helps to keep track of every change to your code in a special kind of database, helping to ensure your changes are tracked to avoid terrible things from happening 🙈. For example, if a mistake is made, developers can turn back time and compare earlier versions of the code to help fix the mistake, while minimizing the effect on other team members.
It’s also great for collaboration — in the part two of this series we’ll discuss Git branches and what that means for collaboration. However, it’s important to note that using Git in your development workflow enables you to compare changes between different versions of the same code, as well as combine code changes between team members, and choose what to keep and what to discard if there are conflicts.
Common terminology 🤓
One of the most intimidating things about learning Git is all the fancy new terminology that comes with it. I’ve listed out a bunch of common definitions that I think will be useful for someone getting started with Git to understand:
Local refers to your own copy of the repository, or code that lives on your computer or server.
Remote refers to a copy of the repository, or code that lives on another computer or server.
Repository is the data structure and system that stores the history of your files and your code, for example a set of files or code in a directory that is tracked by Git, is considered a repository.
git init) turns a directory or folder into a repository, meaning that directory’s changes are tracked by Git.
git clone) grabs a copy of your code and all its history, often from another computer or server.
git commit) refers to saving the state of your files — think of a commit like a snapshot of what your code looks like at a particular moment in time.
git pull) gets the commits from a remote repository.
git push) sends your commits to a remote repository.
Revision refers to the version of a file (or files) in the Git history of a repository.
Branch refers to a copy of your code, with a series of changes that are different to the original copy.
Merge combines your changes to the code with another developers’ changes.
Now that you know some basic Git terminology, let’s get into installing Git and creating our first commit and repository!
1. Installing Git
Depending on your operating system, you’ll have to install Git in a slightly different way. You can use Git with the command line (Terminal on a Mac) and Git Bash on a PC, or use Github Desktop (which works on both platforms). There are also instructions for use with Linux on the Git website.
Open the Terminal application (aka. command line) and check for Git by typing the following and then hitting enter or return on your keyboard:
If you see a version number returned to you, it means that Git is already installed. However, if you see
-bash: git: command not found you’ll need make sure you have Xcode installed (an application on your Mac that comes with Git). You can do this from the App Store.
Sometimes after an update you might get an error that reads
Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo. What this means is XCode will already be installed on your Mac, but you just need to accept the user agreement before it will allow you to access the apps’ tooling and Git.
In older versions of XCode, you might need to install Command Line Tools by going to Preferences > Downloads > Command Line Tools.
You can download Git for Windows, and using Git Bash you can run all the same commands as if you were using Terminal on a Mac.
Lastly, if you don’t have much experience with the command line or want a GUI to use with Git, you could try out GitHub Desktop. Simply download it from the website, it’s free to use, and works with all platforms. Git Tower is also another popular GUI for tracking changes with Git, however you do need to pay for it, whereas GitHub Desktop is free.
2. Creating a repository to save your work
There are a lot of different options when it comes to backing up your repositories online. The most popular by far is GitHub, and if you’ve already chosen to use the GitHub Desktop app mentioned above, I highly recommend you signup for a GitHub Account.
There are also other sites like BitBucket and GitLab that are free to use, with paid plans for larger teams. GitLab has free private repositories and free unlimited collaborators, which I’ve used before for projects and that have been a great experience in the past. Just a note, GitLab’s API is a bit different than GitHub so if you want to do any kind of deployment integrations, the two don’t parallel perfectly as they have different features.
Create a GitHub account
To follow along with this tutorial, I suggest signing up for a GitHub account.
Create a new repository
Once you’ve made an account, create a new repository by clicking the + and then the New Repository link. You don’t need to initialize a README or add a licence in this repository, as we’ll be adding a Shopify theme to it eventually. Once your repository has been made, it will live at
github.com/yourusername/yourprojectname. Your newly created repository should be empty.
If you are using the GitHub Desktop application, you can skip this step.
You might also like: Using Git to Simplify Shopify Theme Deployment.
3. Working locally with Theme Kit, development stores, and your Shopify Partner Account
To be able to track changes to your theme effectively using Git, you’ll probably want to be working locally on your computer with Theme Kit when you make changes to your theme, instead of in the online code editor (otherwise the process of downloading the theme each time to commit changes to GitHub would be absolutely excruciating).
For this tutorial (and understanding how to commit your theme files with Git) you don’t need to set up Theme Kit just yet, but to do so, you’ll want to follow this tutorial on how to setup Theme Kit, and create a Shopify Partner Account in the process.
You might also like: A Beginner's Guide to Sass with Shopify — Part 1: Getting Started With Sass.
Download a copy of your theme to your computer
To get started, you’ll need to download a copy of your theme to your computer. You can do this by going to the Shopify Admin and clicking on Online Store > Themes > Actions > Download Theme File.
Alternatively, if you have already set up Theme Kit, you can run
theme download inside a newly created directory, and your theme will be downloaded into the directory you run the command in.
Important: Make sure that when you name your theme folder or newly created directory that you avoid spaces in the filename. I recommend
words-separated-with-dashes whenever naming files or directories.
4. ‘Syncing’ your changes to your Github repository
Set your identity for your global Git settings.
One of the first things you should do after installing Git is set your user name and email address — this is important because every Git commit uses this information. From the command line, run the following to set your user name and email globally:
git config --global user.name "John Doe" git config --global user.email email@example.com
Initialize your local theme directory with Git.
On your computer, you should already have a directory containing your theme. To open that directory in Terminal, you can simply drag it on top of the Terminal application and it should automatically navigate to the correct folder. Otherwise, you can type
pwd to print your working directory, and
cd to change directory to navigate to the correct place on your computer. For example:
Once inside your theme directory, initialize the directory with Git. Essentially you’re telling Git to watch these files for changes and turn this into a repository. From inside the theme folder run:
Now that you’ve initialized Git in the theme folder, type
ls -la to list all the files in your current directory, including files that start with
.. You should see a
.git directory in your initialized theme folder. The
.git directory is a hidden folder that contains all the information about your project that Git needs to work.
If you’re using GitHub Desktop, click Create a new repository or type
cmd N, which let’s you name the repository whatever you’d like it to be called on GitHub — this can be different from the theme directory name, however for consistency, I suggest being pragmatic with your naming from the beginning and naming both folders the same thing.
Link your local directory with your GitHub repository.
Now that you’ve initialized Git in the theme folder, you can link it to your GitHub repository, which you previously created. You might wonder, why would I bother doing this, Tiffany? And I would say, it’s because we don’t want our local directory to just live solely on our computer. Otherwise we’ll still run into the same issues of losing information if our computer explodes, or the folder gets deleted by mistake, even if it’s being tracked by Git. We are choosing to back it up to a second server (in this case GitHub) so that we can access it from anywhere with an internet connection, and it’s backed up in a safe place.
To tell Git where we want to link our local repository to, we set a
remote by running:
git remote add origin firstname.lastname@example.org:tiffanytse/example-project.git
In the example above, my GitHub username is
tiffanytse and the repository name is
example-project. You’ll be able to find this command in your empty GitHub repository that you created as part of the instructions.
If you’re using GitHub Desktop, click the Publish repository button at the top right of the app, which will run a few Git commands in the background. These not only set the
remote but also
push the directory to the master branch of your repository to GitHub. We’ll talk more about branches in the next article in this series.
Check the status, add files, and make a commit to master.
git status you can see which files have yet to be tracked by Git in your theme directory. To track those files, you can run the following command:
git add .
This tells Git to add all the files and directories, except those that are being deleted — make sure to include the
. at the end of the command.
Then we’ll make an initial commit to master, by running:
git commit -m "Add all initial theme files"
-am specifies that you want to add a commit message directly within this command (so you don’t have to try and use VIM in the command line to write your message) inside a set of quotes. I’ve written
”Add all initial theme files” as my message, but you could write whatever makes sense here for you. Often for the first commit, I’ve seen the message
”Initial commit”. The commit message is something that will tell you what changes you made at this particular snapshot in time. I've included some best practices for commit messages at the end of this article.
If you’re using GitHub Desktop, you can write your commit message in the Summary input on the left-hand of the app, and commit all the files you want to add to master (checked off files) by clicking the Commit to master button after you’ve typed a commit message.
Sync aka. push your changes to GitHub
When I say the word sync, what I really mean in Git terminology is to
push our commit to GitHub, essentially making sure that our local version of the repository is “synced” with the
remote repository. To push your theme files to GitHub run:
git push -u origin master
-u sets the upstream for your repository, meaning that later when you want to
pull changes from the repository you don’t need to specify a branch. In this command,
origin refers to the remote, and
master is the default branch name when you create a repository with
If you’re using GitHub Desktop, click the Publish repository button at the top right of the app to publish your repository on GitHub. After adding additional commits, this button will change to Push origin, and clicking that button will send any commit changes to your GitHub repository.
One thing to note, that we didn’t really discuss earlier, is how to ignore files. This is especially useful if there are specific files you don’t want to track with Git. For example, if you’re using a Mac you probably want to ignore the hidden
.DS_Store files that are automatically generated by the operating system in your file folders.
Additionally, if you’re using a compiler app like Prepros, you might not want to commit the
prepros.config file that’s automatically generated.
To ignore files with Git you need to create a text file called
.gitignore. Because files that start with
. are hidden from directories, you won’t be able to create it from Finder, unless you’ve specified that you want to show hidden files. The easiest way to create a
.gitignore is to do it directly from a text editor like Sublime, Atom, or Visual Studio Code.
Create a new file in your theme directory, and name it
.gitignore. In this file, add in the file types or specific files you’d like to ignore, with line breaks for each. For a Mac user, a typical
.gitignore would contain the following code:
._* .DS_Store Thumbs.db
Don’t forget to add and commit your
.gitignore file to your repository!
Learning when and what to commit
Make sure to commit often, and as soon as you’ve added a small function or significant piece of code. The main thing is to commit frequently, so you can keep track of the changes you are making in a systematic way.
When writing commit messages remember to use the imperative “Add”, “Fix”, or “Change”. I find it helpful to imagine you are completing a sentence like, “This code will”...
Add all new files to theme
Fix broken button hover state
Change menu system markup
Things to remember:
- Don’t create a commit for every new line of code.
- Don’t commit only once, at the end of a project, when everything is done.
- Your code doesn’t need to be “done” to commit.
- You should always commit when you add a new function, feature, or component.
- Think of your code in modular pieces, and your commits are even smaller pieces of that. If you were in a time machine, what places in your code would you want to be able to step back to. If you were playing a videogame, where do you want to save your progress before trying to beat the big boss?
"If you were in a time machine, what places in your code would you want to be able to step back to. If you were playing a videogame, where do you want to save your progress before trying to beat the big boss?"
Get started using Git today!
Even if you’re a bit uncomfortable with the command line, you can choose to use GitHub Desktop and be able to do most of the things you can do with typed commands. The great thing about Git is that you don’t need to know all its capabilities to start using it, and for it to be useful.
Stay tuned for part two of the beginner’s guide to Git with Shopify! In the next article, we’ll talk about states, branching, handling conflicts, and setting up SSH keys.
- Super simple guide to Git
- Git basics
- Command line basics
- In depth Git documentation and video tutorials
Have you tried using Git before? What was hardest thing for you to understand? Tell us in the comments below!