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 Dploy.io (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 Bitbucket.org 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 http://whatthecommit.com/ – 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!
