Yesterday, I was honored to speak at WordCamp Portland about using Source Control systems with WordPress. The talk was meant as little more than a 10,000 ft view of some of the reasons you might want to consider using source control, and some of the possibilities that it presents. As always, the 10,000 foot view is good for a comic introduction to something, but not for any real understanding. Thus, I wanted to write a series of posts detailing the whys and hows of source control in WordPress- written for people who don’t know anything about Source Control.
Firstly, let me say this: I’m not making a statement on Git vs. Subversion vs. Source Safe vs. CVS vs. the weird text-based logging system you developed 10 years ago and haven’t ever changed. I’m making a statement about using source control period, and using Git as an example because that’s what I use.
The Whys of Source Control
Why? Because you’re going to wish you had in about 3… 2…
Seriously, things happen, you break stuff, you need to look at an older version, you want to try something and are not sure whether it’s going to break, you want to share your code with others, or take advantage of the code of others, you want to share code with yourself, etc. Source control is part of a broader development strategy that is valid whether you are a serious programmer or just modifying themes for yourself or clients. There are dozens of reasons why source control is A Good Thing™.
The main one is that catastrophe is going to happen, and it’s going to happen in 3… 2…
Source Control for Smarties
Enough of the whys. Let’s get to some hows.
I won’t insult you by telling you this is Source Control for Dummies, but I don’t want you thinking that you can’t learn how to use it if you don’t want to. Like anything, it takes some getting used to.
Git vs. Github
Right off the bat let’s clear up Git vs. Github.
- Git is source control management software (the way that WordPress.org is blogging software)
- Github hosts Git repositories (the way that WordPress.com hosts blogs)
- Git is software that allows you to track the changes that you make to individual files
- Github is a company providing a nice looking website to help do that, well as other neat things
If you haven’t already done it, go to Github right now and sign up for an account. It’s free, they are full of awesome sauce, and you can then fork some of the examples I’m going to give you.
Oh, and you will want to install Git too.
The Fast Install Guide
- If you’re on a Mac, use Homebrew (i.e. “brew install git”)
- If you’re on Linux, use the package manager (e.g. “apt-get install git”)
- If you’re on Windows, buy a Mac (i.e. “ba dum CHING!”)
Okay, seriously, Here are the Github help pages for installing Git on Windows, Linux and Mac. It’s really beyond the scope of this post to detail exactly how that’s done. If enough people get lost, I’ll write a detailed post on just that. For now here are some guidelines:
- Install Git
- Create an SSH key
- Go to a terminal window and type “ssh-keygen”
- In Windows, don’t use the normal “Command” window, use Start->Programs->Git->Git Bash and type that. If you installed Git using the directions above, it should work.
- Create your Github account if you haven’t, then go ahead and set your username and email on your local system according to these instructions.
-
Sample SSH key public file
Copy the SSH public key
- Copy the contents of the file ~/.ssh/id_rsa.pub (or id_dsa.pub) to the clipboard
- In Windows, this file is in C:Documents and Settings{User Name}.ssh
- This file’s contents look something like the file to the right
- Important! Don’t copy the id_rsa file, copy the id_rsa.pub file (the .pub ending means it’s a public file- never ever give out the other one)
- Go your SSH key settings in Github and paste the public key
Now you have Git installed, and have a Github account that you can access directly from your computer.
Fork it!!
Okay, now that we’re all set up with our source control system, let’s take a really quick tour. As a note: I’m going to do this with the command line, not with any graphical system. I’m doing this both because it’s how I do it, and because it will help illustrate what the commands actually do. Feel free to get a graphical Git program if you’d like, the commands should be the same.
First, we’re going to give you a functional repository, so go to my Github repository of the WordPress TwentyTen theme. In the upper right, under the User/Account/etc menu and under the Search menu are some buttons, hit the one that says “Fork.” Now, head over to my thirty ten repository and fork that. Thirty Ten is the child theme developed by Aaron Jorbin and he graciously offered the code as well as an excellent blog post describing its development. I’m going to use Aaron’s child theme a lot in this series.
Snapshot of a repository on Github
What forking does is copy the repository to your account, but does so in such a way that it “knows” that it came from somewhere else. That way if I change my repository, you can pull the changes, and if you change yours, I can pull those changes if I want. Head over to your account and look at the Thirty Ten repository now. You’ll notice that it shows a list of files and directories showing a message next to each of them. You’ll also see that I am the user listed at the top. That means that I was the last person to “commit” my changes. Committing means making changes to files and telling Git that you want those changes, well, committed to the repository. Lastly, scroll to the bottom of the page and notice that Github is telling us that we have no README file. If there was a README file in this directory, the contents of that file would be displayed here.
Now, go to a command line and type:
$ mkdir themes
$ cd themes
$ git clone git@github.com:USERNAME/twentyten.git
$ git clone git@github.com:USERNAME/thirtyten.git
These commands make a “themes” directory on your local system, and then inside that theme directory they clone the TwentyTen and ThirtyTen. Cloning means making a copy of the repository that’s on Github (Replace USERNAME with your Github username, obviously). Now, all of the files that are in the Thirty Ten repository on Github are also on your local system. You have two identical copies of the Thirty Ten repository.
Modifying code in a repository
Now let’s go into the Thirty Ten repository and make a small change by creating a README file (feel free to do this using a graphical file manager and/or text editor):
$ cd thirtyten
$ echo "This is a child theme based on TwentyTen, the default WordPress 3.x theme." > README
That creates the file README and puts some basic text in it. Next, we’re going to play with some Git commands. Type the command git status and you’ll see:
$ git status
# On branch master
# Untracked files:
# (use "git add ..." to include in what will be committed)
#
# README
nothing added to commit but untracked files present (use "git add" to track)
This is telling us that you have one “untracked” file- a file that you haven’t told Git about. We’re going to “add” that file to our repository:
$ git add README
This command tells Git to add the file README to the repository. As a shortcut, if you have all files and want to add them all, you can use something like:
$ git add .
The dot tells Git to add “the current directory.” Since README is the only file that hasn’t already been added, it’ll only add that file. Let’s look at the status again:
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD ..." to unstage)
#
# new file: README
#
Notice that “Untracked files” became “Changes to be committed.” This is the only thing we’re doing right now, so we’re going to commit this change (i.e. tell Git that you’re sure, and want this change save, tracked, and logged.)
$ git commit -m "Add a readme file"
The “-m” switch tells Git that we want to add a message on the commandline, instead of adding it separately. Now our changes are committed to our repository and logged and we can make more changes:
$ git status
# On branch master
nothing to commit (working directory clean)
Let’s go and make another change. Let’s add a special css file that we can play around with later. We’ll go ahead and add this directly to the repo.
$ touch special.css
$ git add special.css
$ git commit -m "Add a blank special.css file to play with"
Now we have two changes committed to our repository. They are saved, tracked, and logged. But our laptop might be stolen, so let’s “push” them to a “remote” repository for safe keeping. A remote repository is a mirror of the repository you’re using. The repository on Github is a remote repository with the name “origin.”
$ git remote
origin
Pushing means “Take the changes that have been committed to this repository and commit those same changes to a remote repository.” Since you only have one remote repository, you don’t even have to tell it which one:
$ git push
will push the changes to Github. Now go ahead and browse to your Thirty Ten repository on Github and look at it. You’ll notice that the user is now listed as you, with your last commit message. Scrolling down to the file list, you’ll see that your commit messages are listed next to the files that you changed.
Coda
There it is, the bare minimum you need to get started with Github, and some sample repositories to boot. In the next post, we’ll create a child theme from scratch, and use the great FTP software Filezilla to copy our changes to our WordPress server after we check them into source control.
I’m John Metta, writer, hydrologist, programmer, Irish flute and banjo player, cyclist, brewer, and a digger of all things tech, and all around friendly guy. Nestled snugly in the Columbia River Gorge in a town called Hood River, I survey the world as my own personal playground. 
