Baby Steps into Version Control with WordPress

Version control. You’ve probably heard of it and you may even be cringing with guilt at this very moment because you’ve read one too many articles that tell you that you need to be using it.

Well, unclench for a second. Yes, clearly this article is designed to persuade you to jump on board. But my goal is to ease you into it. The world of version control can appear very overwhelming and it does certainly have its complexities. But you can actually get started with it and dip your toes in without too much pain (spoiler alert – no command line required!)

What is version control and why does it matter to you?
For the purpose of this article, I assume you are like me: an individual developer that primarily works on projects solo. One of the big selling points of version control is that makes collaborating with other developers infinitely easier. So why should you bother?

Well, at its most basic, version control is a system that tracks all the changes you make to your files. This is helpful even for solo developers for a variety of reasons. It provides a complete log of all your changes so that you can hunt for bugs easier, revert changes, and, if you revisit a project a few months down the line, it’ll be easier to pick up where you left off because you documented your own thought process.

Most of us have unwittingly developed our own primitive method of version control. Let’s say you have a file that you want to make a change to, but you don’t want to overwrite the original in case it doesn’t work out. Chances are, you’ll make a copy of that file and name it something like index-backup.php or index-original.php. We all have our own methods for this, but it gets out of hand very quickly if you wish to preserve multiple versions of that file. Version control eliminates the need for all that. You have one set of files and all your changes are tracked separately.

Additionally, storing your code in an online repository gives you an extra backup of your work beyond what’s on your local computer. Version control makes experimentation a little less scary. How many times have you experimented with code, trying to find the right solution to a problem, but have trouble keeping track of all the variations you tried and which one worked best? Version control can help with this too.

 So there are clear advantages even if you are not working on a team.

Now you know why, let’s look at how. Trust me, it’s not as hard as you might think.

Getting Started

If you’re nervous about jumping in the deep end, a good way to get your feet wet with some of the tools is to check out a previous post I wrote about how you can run a bleeding edge WordPress local environment. It introduced some of the tools we’ll use here, so it’s a safe place to start.

Tools & Assumptions
This guide is geared specifically toward using Git as the version control system of choice (as opposed to others you may hear of like SVN, Mercurial, etc). I personally develop WordPress sites, so there’s some specific language around that, but version control and this workflow applies to any code – it is definitely not WordPress-specific.

Your Setup:

1) Ideally, you have a local development environment on your computer.
The workflow outlined here will work best when you have a local dev environment setup. It’s not crucial, but it is helpful. If you’re using WordPress, I highly recommend using Desktop Server for this.

2) A code repository
This is a cloud-based storage place for your code. Two of the main ones you’ll hear referenced are Github and Bitbucket. I like Bitbucket because their pricing scales according to number of users, not repos. Since I’m mostly working by myself, without the need for other users, I can use it for free. Also, they default to private repositories rather than public, which is what I prefer. You could also use Github instead, but their model is the reverse – their default is public repos. If you use Github (or any other), the overall version control workflow is still the same.

 3) Command line or GUI tool
Purists will tell you to use the command line, but I personally don’t. Maybe that’s the future, but I think a GUI-based tool is a much friendlier way to get started. My personal preference is SourceTree because it’s free for both Mac and PC and is fully featured, removing the need for the command line.

4) A deployment service
I’ve personally used both DeployHQ and FTPloy since they both offer a free level of service. There are several others include (by the makers of Beanstalk, an integrated repo host and deployment service).

If you want to follow along with this tutorial, I recommend setting up a free account at and downloading SourceTree so you have them ready to go!

Set Up Your Code Repository

Once you’ve set up your basic Bitbucket account, click the Create button in the toolbar at the top. The only thing you really need to fill in on the next screen is the name field. The other defaults are just fine for what we’re doing. For the purposes of this guide, I’m assuming that the project we’re working on is a  WordPress theme – that could be creating one from scratch or modifying an existing one.

Your next step will depend on whether you are starting your theme project from scratch, i.e. you haven’t written any code yet, or whether you are already working on some files. Both next steps are below.

a) Starting a project from scratch
Click Clone in SourceTree – this will open SourceTree and let you choose where you want to save the repo on your computer. You need to start with an empty folder (which is why this isn’t the step to take if you already have existing project files).


So now you have a brand spanking new version controlled workspace on your computer that looks like this:

The destination folder you created is now under version control, meaning SourceTree is watching it for files and changes. So you can create your first file and save it to that folder. It will then show up in your SourceTree workspace in the Unstaged list.

 At this point you can skip down to the Stage / Commit /Push section below.

b) If you already have an existing set of files that you need to bring into version control
A sample use case might be that you have already created a local dev site on your computer using Desktop Server (or other) and you want to start applying the version control process to a theme you have created there. In this case, the easiest route is to bring your existing code under version control, then send it up to your BitBucket repo:

  • In SourceTree go to File  > New /Clone.

  • Add Existing Local Repository.

  • Navigate to the appropriate folder – typically the theme or child theme folder.

  • Make sure the type is set to Git and then click Create.

  • Your repo has been added to SourceTree, so now double click on it from the bookmarks panel.

  • You’ll see your working copy in SourceTree and all the files in that folder will be listed under Unstaged.

If you’ve been following along, you have already created your remote repo at Bitbucket. Now it’s time to connect your local repo with the remote.

  • In SourceTree go to:

    • Repository > Repository Settings.

    • Make sure Remotes is selected and then click Add.

    • For the remote name, the standard is to use: origin.

    • The URL / path  you will get from Bitbucket – it is literally the URL in the address bar when you view your repo in Bitbucket.

Stage / Commit / Push

So at this point you have one, or some, files sitting in Unstaged in SourceTree. We need to get them into Bitbucket. It’s basically a three-step flow to get files from your local repo up to your remote repo. In Git terms these are:

Stage > Commit > Push

  • Check Unstaged. This selects all the files and moves them up to the Staged section. This is an intermediary area, which is where your files go when you’re getting ready to Commit them.

  • Next, type a commit message in the field below. With the rare exception, perhaps of this very first one which can be a simple “initial commit,” your commit messages should be descriptive of the changes you made in your code so you can easily identify steps along the way. Something like “changed header color to blue” will be much more useful to your future self than something vague like “made a change.” And if you’d like a little nerdy comic relief, check out – hilarious and real commit messages.


  • Now click Push. The first time you Push, you will be asked for your Bitbucket login credentials and then your files will be uploaded to your Bitbucket repo.

You can verify that the Push worked by going to your Bitbucket account and refreshing your repo page.

Under Overview, look at Recent Activity on the right and you’ll see your initial commit and commit message.


If you go to Source you’ll see all the files you committed.

So, this is the basic process of working in version control. You write code, save it, then stage it, commit it, and push it to your repo. If you check the “Push changes immediately to origin/master” box at the Commit step, you can combine the last two steps, saving you some clicks and time. I typically have this checked. As a solo developer I haven’t found a reason not to utilize this.

Working In SourceTree

Just a few notes on some basic terminology that you’ll see. On the left side of your project window in SourceTree, you’ll find File Status and, just underneath, Working Copy (make sure to click Show next to File Status if you don’t see Working Copy). This simply shows you when you have made changes to files that have not yet been pushed. So, use this area to Stage and then Commit files.

Branches > master
This refers to primary development path of your project. Additional branches can be created to test out different ideas, but the use of branches is beyond the scope of this guide. Typically, master is the main branch that you’re working on. When you click it, you’ll see a log-style view of all your commits.

Remotes > origin
This refers to your remote repository at Bitbucket – we named it origin in a previous step. The goal is generally to keep the origin and the master in sync. SourceTree will alert you if you do something that gets them out of sync, as you’ll see below.

How To Fix An Oopsie

Version control has tons of features and uses, but a simple one we can look at here is what to do when you write and commit some code that breaks your site (as an example) and you want to rollback to your working code. Version control makes this easy to do:

  • Click on Branches > Master on the left. This gives you a log of all your commits.

  • Right-click on the one you want to get rid of and choose “Reverse Commit.”

  • Click OK when prompted – Are you sure you want to reverse selected changes?

  • You will then see a notification “Master 1 ahead.”

  • This is an alert that your local branch (master) is 1 change ahead of your remote (origin). To get them back in sync, simply hit Push and all will be right with the world.

There are more complex ways of experimenting with code beyond simply reverting. That’s what branches are for. Here’s some more advanced reading on that. They refer to command line but you can perform those same commands using SourceTree.

Deploy Code To Server

So, now you have your code all nicely stashed in Bitbucket. Your work is backed up and version controlled. But it’s still not live on a website yet. So, how do we get from Bitbucket to your server? That’s where a deployment service comes in. Your previous workflow likely involved FTP-ing files to the server, but FTP can be unreliable. Not to mention that with a deployment service we get smooth integration with our code repo host and a nice history log of deployments. You no longer have to remember which files you need to upload, so everything stays nicely in sync.

I’ve used both DeployHQ and FTPloy. Both have free levels of service but I think FTPloy’s free level is a little more generous, so I would lean toward using them.

Once you’ve created your basic account, you’ll be asked right away to connect with either your GitHub or BitBucket account. That’s a simple authentication process where you input your bitbucket username and password.

Once you’ve done that, you’re prompted to start a new project which is a simple matter of selecting your repository from the list.

You’ll want to switch on ‘deploy now’ if you already code ready to go in Bitbucket.

Next, fill out your server credentials. This is essentially your FTP info. The server path means the path directly to the folder which you want to deploy. Once you’ve got this set up, you’re good to go. FTPloy deploys automatically each time you commit and push to Bitbucket. This is a huge time saver but the cautious might only want to use this feature when pushing to a staging server rather than a live site. However, if you’ve been developing locally and testing your code there, you’ll probably feel more confident about pushing your commits directly.

If you don’t want this feature at all, I would go with DeployHQ since the auto deploy is not on by default.

For a little more detail on best practices for deployment and workflow, I recommend this guide. It is geared toward team use, but the notes about testing locally before deploying to staging, and then live, are still applicable.

Feeling Good?

Right about now you should be feeling like a rockstar since you’re officially using version control!

This tutorial merely scratches the surface of what you can do with version control, but now you’re on the right path! I used the example of working with a theme folder for this guide, but if you want to learn more about the nuances of working with a complete WordPress site within version control, there’s been a lot written on that. This might be a good start.

Feel free to share your own experiences in the comments!


  • parachuteapps

    A great post, wish I had this post about 3 years ago :-)

    • Thanks parachuteapps! Glad you enjoyed it ^AR

    • Thanks! Better late than never?!

  • Fascinatingly it was literally two days ago when I did this but I used Beanstalkapp (, I can’t believe this workflow isn’t more mainstream, it makes such a difference. Great post, now I can refer friends to it!

  • Hète

    how do you manage WordPress database (sync with the production vs devel) ?

    • I also have problem with this. One “solution” that i’ve found is not to manage databse sync. If something have to be in production, just put directly in production. There are tools to manage databases but they are way too expensive.

  • Thanks for a great post Lucy! This really makes GIT less scary for users that are weary of breaking things with command line!

  • Jacob Hopson

    Thank you for this post. Taking all my project into the world of version control now! Without you it would not be happening!

    • Jacob,

      I hope it’s a successful transition!

  • Great article, helped me a lot as a solo front end developer to start with version control with a new and an existing wp theme projects, Now I’m feeling good! 😉

  • I searched for DAYS for articles on how to properly set up version control using Bitbucket with WordPress. Finally landed on your post and could not be more thankful! Thank you a million times!

  • Great explainer and the potential complexity makes us grateful for the upcoming solution from Versionpress (and probably more once the floodgates open)

  • Debbie Labedz

    I just started developing a site locally (using MAMP), but I’d really like to start implementing the workflow shown here with this build. Can I do that? Would I have to adjust any of the steps?

  • Debbie Labedz

    I just started building a site locally (using MAMP), but I’d like to implement this workflow with this build. Can I do that? Do I need to revise some of the steps since I’m not starting with a fresh site?

  • John Callanan

    Great overview!

  • John O’Loughlin

    So where does this leave us with clients (this is most clients) who insist on sticking with their current host, which usually doesn’t have git and won’t install git or allow the required permissions?

  • A very well written and thorough tutorial on Git …. took me a while to first get my head around it all, push and pull, branches, forks, trees and what not …. this certainly explains it in the most simplest way I have seen anywhere on the web yet. Well done. A good simple article like this but on database syncing between a live and staging site would be most welcome because I am loathe to use something like VersionPress which is in its infancy and Revisr is good but am not sure how it can handle conflicts between a live and staging site database if changes happened on both sides.

Related Articles