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:

1. Install Git
2. Create an SSH key
   1. Go to a terminal window and type “ssh-keygen”
   2. 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.
3. 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.
4. 

   Sample SSH key public file

   Copy the SSH public key

   1. Copy the contents of the file ~/.ssh/id_rsa.pub (or id_dsa.pub) to the clipboard
   2. In Windows, this file is in C:Documents and Settings{User Name}.ssh
   3. This file’s contents look something like the file to the right
   4. 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)
5. 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.

1. Flame war: The un-winnable situation in which everything I do is amazing and everything you do sucks. I don’t care what source control system you use- and think that it’s a bad idea to use Git if another one is better suited to your needs. Still, if you’re not using any system, you may as well choose Git because then this article will be easier to follow. Yes, I could give examples in Subversion and Mercurial, but this is not a book, it’s a blog post.
2. Also, sometimes it seems like setting something up and learning how to use it is more trouble than just dealing with the problem when it comes up all the time. Only you can make that decision, but I guarantee that the amount of time you spend learning this will offset the amount of time you spend working (and recovering from failure) if you don’t.

Like tomato sandwiches, Celtic music, beer, and programming- Github is something that, try as I might, I just can’t make myself sick of.¹

Recently, I took the Git survey, and it contained an interesting question along the lines of “What do you use Git for?” The answers were things like “configuration files” and “large binary files.”

I use Git and Github for a lot- configuration files are one use (I love the “raw” path), but it was only a small percentage of what that list suggested, so I started wondering how else I could use it.

Today, I thought of an interesting way: Github as a CDN.²

If you know what a Content Delivery Network (CDN) is, you don’t want me to explain. If you don’t, then it’s good enough to say that it’s a way to server up pictures or other content from another server. It’s often used to, say, serve the main portion of an html page from a webserver, but serve the images, CSS files, etc. from something like Amazon to speed things up.

I recently finished work on The Great John Metta Branding Project and, like with so many projects, stored the images in Dropbox. Then, deciding I might want to version them, I stored them in Github. Then, just as I was starting to begin the rather annoying process of copying all these logos and textmarks to my various sites throughout the web and updating all the image tags, I thought to myself “Hey, if these are already in Github, and I can access the raw files, why don’t I just use that as the image source?” But I don’t want to have to remember the URL each time. What if it was somewhat dynamically generated?

A RESTful CDN system for a logo

This is exactly why I made johnmetta.com a Rails project, to play with stuff like this and then have a place to have it be live if I wanted to use it.

I’ve got a lot of different styles that my logo can take. Stacked, Icon only, textmark only, icon one-color grey, textmark one-color blue, etc. Ideally, I wouldn’t have to remember the path to each, I could type something like http://johnmetta.com/brand/icon/blue/transparent/logo.png³ and have the app return the image that is strictly the icon (no words) with blue coloring and transparency inside the logo (instead of the normal white).

Since none of these actual images is created on the fly, I created a sensible directory structure and embedded all the files in this structure, naming them all logo.png and putting the default logo in the top level. So the above image would be {base}/full/logo.png, while a version with the icon on top would be {base}/full/stacked/logo.png. A one-color version of only the icon might be {base}/icon/blue/logo.png

So I created a Brander class which would turn arguments into an appropriate path and added some new routes such as “brand/:type/:color/logo.png” and created a call to brander in the controller’s “brand” action that ends with a redirect to the returned URL.

It’s all really simple, but it allows me to have a url like http://johnmetta.com/brand/icon/logo.png and supply my logo, and http://johnmetta.com/brand/stacked/blue/logo.png for a one-color blue stacked logo. Then, if I update the colors (move the files, whatever) they update automatically. At a maximum, I just check in the changes and make minimal changes to the routes- but don’t have to copy files to servers.

A Good Illustration

Right now, the Brander class is pretty dumb- little more than a way to translate a route into the correct external URL. It was built up not as an illustration of how to accomplish “Github as a CDN,” but merely as a toy to test one way that it might be done on a small scale. It might be better done as a class where instance attributes make more sense, and I’ll clean it up a bit, but not much more than that.

Also, it’s cool to know that stuff like this can be set up so easily, and for my uses- where bandwith might reach a whopping few requests per day, it’s useful while being low impact. But for a real CDN, you’d still want to use something like AWS- or at least talk to the Github guys before swamping their webservers.

1. I’ve tried for the past two summers to make myself sick of eating tomato sandwiches. I just can’t.
2. The title is with Rails because that’s what I used, but it would take 2.4 minutes to make this a “With Django” or “With Lift” example
3. Actually having “logo.png” is unnecessary, however, sometimes the software using the URL will depend on that, so I just made it convention so that I don’t have to think about when sometimes is.

“Sure, Ruby’s fun, but it’s not really useful. It’s a cute scripting language, but it can’t scale.”

Until recently, this was an opinion that I agreed with. Hell, it was actually something I told other people.

One day, I realized why I agreed with it.

Now it’s just an opinion that makes me want to smack someone.

Geeks are Dumb

I don’t really know where the whole “Ruby can’t scale” argument comes from, but I have my suspicions.

The main suspicion is that, as a general rule, programmers are geeks, and geeks spend a great deal of their childhood development getting beaten up by non-geeks.¹ Thus, we child-geeks tended to focus our efforts on something we knew that we did better than the wrestlers and football players. That something was generally not wrestling or football. It was academics.

We geeks are smart.

Think about the football player who spends his entire school day like a stupid monkey, proving that he’s tougher and plays football better than the other stupid football playing monkeys.

Geeks aren’t stupid monkeys. Geeks have a brain.

And we use that brain to spend our entire school day like a stupid monkey, proving that we’re smarter and use our brain better than the other stupid brain-using monkeys.

Oop. There it is.

Truth Hurts

Oh stop being dramatic! You know it’s true! You’re just too busy being a stupid brain-using monkey to want to admit it!

You can’t name a single geek-dominated situation that wasn’t essentially a “I’ll take your obsure science fiction reference and raise you an obscure Dungeons and Dragons reference” chest-pounding war of the stupid monkey-brained geeks.

No, you can’t. Stop trying.

The point is, it’s all about being the übergeek. And the competition of übergeek is a constant struggle of

“No, I was the smartest person in my class! So if you say something smart, I have to say something smarter!”

And so when someone tells me that they are programming in some hot, trendy new language, I can’t say something like

“Oh, it’s great that you’re moving forward and trying something new… I’ve been feeling a bit old lately, kind of in a rut, and was somewhat scared to learn that shiny new language.”

Yeah, right.

Imagine a geek actually admitting weakness! HA!

No, when I hear someone say they’re programming in some hot, trendy new language, I say:

“But hot and trendy are stupid, like that hot girl who wouldn’t date me in high school. And your new language is stupid too! And I think I overheard someone say that it has a defect, and so even though I don’t know anything about your new language, I’m going to spout out this defect to prove that I’m better than you for not using it. There! I win!”

Fun fact: Geeks, as a general rule, are freakin’ terrified of anything that carries the descriptor “trendy,” because if we knew what that word meant, we wouldn’t be geeks, we’d be popular.

Datapoints

This may seem harsh, but stop being all “must not admit weakness”-y and use that monkey brain to actually think about it.

Here’s a nice datapoint: Twitter.

(I already hear you, by the way)

“But Twitter was down all the time! Because Ruby can’t scale! That’s why they moved to Scala!”

Was it? Was it really? Is that smart monkey brain actually working? Saying Twitter was down all the time is like saying that the United States Postal Service is not a good choice to carry mail because it’s inefficient and looses a lot of mail.

But, but, they lost a letter of mine once!

Yeah, sure. And they deliver on the order of a billion freakin letters every day! Did your super smart übergeek brain never actually grok percentages?

Do you have any idea what kind of traffic Twitter had when they moved to Scala? Saying Ruby can’t scale because Twitter had a freakin’ failwhale every once in a while is like saying that the space shuttle’s not a real spacecraft because it only goes into near space.

It goes into freakin space… and you don’t have jack shit that’s ever going to be any better.

Why are you even talking?

Coffee Shop Critics

The truth of the matter is that the people saying that Ruby can’t scale are not the developers from Twitter, or from 37 Signals, or from Github. They are not the developers from the companies that have built ridiculously freakin’ big web applications in Ruby.

No, they are the developers who are sitting in coffee shops– secure in the knowledge that if someone just knew how smart they were, they wouldn’t have to sit in that coffee shop and talk about their amazing idea. If someone only knew their greatness, they could be a contender!

It’s simple. The people who are busy having the “my language is better than your language” battle in coffee shops are pretty much guaranteed to not be the same people who are actually building large-scale applications. Why?

Because those people are too busy actually building large-scale applications to get into stupid chest-pounding arguments with monkey-brained nitwits.²

Look, none of us likes to admit weakness. Me worst of all. All I’m saying is that admitting weakness can make us stronger.

And saying something like “Ruby can’t scale–” especially when you’ve never programmed in Ruby and are just spouting stupid shit that you heard someone else say just so you can say something– is weak.

Unless you actually have something built– and that something is so freakin “oh my god we have more data than Twitter”-big that you actually know that it couldn’t be done in Ruby– then you’re full of shit, you know you’re full of shit, I know you’re full of shit, so you might as well just admit that you’re full of shit. Because if you don’t then you just look stupid.

And no true geek wants to look stupid.

Sometimes I think I may slap the next coffee shop critic that tells me Ruby can’t scale.

Me: “I’m learning Ruby”

Monkey: “But Ruby can’t scale”

Me: “Hrm. I guess you’re right. By the way, what do you use for Source Control”

Monkey: “Github.”

Me: <SMACK!>

See?

Duck typing with Duct Tape

I’m learning Ruby. I’m programming web applications in Ruby on Rails.

Moreso, I’m programming web applications that absolutely must scale.

“But why are you using Ruby? Ruby can’t sc–”<SMACK!>

Because let me tell you something: Having a “0.01% of users sometimes complain that it’s broken, can’t really scale because it worked for Twitter just fine” webapp is much better than having… oh, say nothing!

I’m not going to fool myself. Maybe Ruby can’t scale beyond a certain point. Who knows? I sure as hell don’t, because I’m not at that point. And the person telling me that Ruby can’t scale isn’t at that point either, I’ll bet.

We’re not at the point where we have 25 million users.

We’re not at the point where VC firms are dumping $15 million dollars in our laps.

We’re at the point where we are so busy talking that we’re not actually doing anything.

I’m in a freakin coffee shop, with a maybe good idea. And with a really fun language… one that’s powerful enough for Github and which scaled well enough to bring VC firms to Twitter after 25 million users came!

And with enough freakin’ bravery to at least want to admit weakness– that I don’t know what the hell I’m talking about when someone mentions the next trendy language that I’m too scared of, or too lazy to learn, or simply not really interested in.

I’m in a coffee shop, and I’m ready to use duck typing, or freakin’ duct tape if I have to, if that’s what it takes to actually stop spouting bullshit about scaling issues and actually accomplish something…

…and get the hell out of this damn coffee shop!

1. That was pretty much my childhood, anyway, so maybe I’m projecting a bit.
2. Oh stop being dramatic! I don’t have anything to show either. I’m in a coffee shop writing a freakin’ blog post instead of actually accomplishing something.

Still, we could always improve, and there’s one particular improvement that would be a dream come true for me (and insure that, following my 30 day trial, I actually purchase the software rather than moving on to something else to try in my new found romance with Ruby). That feature is true integration between RubyMine, PivotalTracker and Github.

It’s actually something that I’m surprised doesn’t already exist, considering that, by all accounts, the PivotalTracker team actually uses RubyMine. Furthermore, PivotalTracker’s new API has great integration with GitHub’s service hooks. Telling me that surely this problem has been bumped into before.

In fact, it’s such an obvious need, and I’m so convinced that a solution has to exist, that I pretty much want someone to just point me to the plugin! A free pint at Double Mountain Brewery in Hood River for anyone who can point me to that plugin!

My current workflow is disconnected because, while I can easily create a commit message that starts/finishes a PivotalTracker story, I still have to go to the PivotalTracker website to get the story number, which involves a lot of window switching and mouse clicking. And as anybody knows, the moment I switch the window, my mental context goes right out the window.

Hell, at that point, I may as well see who’s complain about the new Apple announcement on Twitter. In order to use RubyMine and PivotalTracker, I have to check on Twitter a lot.

Current workflow

1. Working on feature A, but realize that there’s a need for fix B as a consequence. Want to add fix B as a story?
   1. Go to PivotalTracker website, add story, then go back. Or stage story somehow, but something so that you don’t forget.
2. Back to RubyMine to finish feature A development. Commit using PivotalTrack’s Github integration?
   1. Back to PivotalTracker website to look up story, copy story ID to clipboard
3. Back to RubyMine (or terminal) to add story ID to commit message. Want to start working on fix B?
   1. Back to PivotalTracker website to start story for fix B
4. Work on fix B, but realize that there’s a desire for feature C…
   1. Back to PivotalTracker website…
5. Lather, rinse, repeat…

Realizing that this is a simplified workflow, but it illustrates the point of the contextual switching needed to use both of these tools. Because of this, I often end up just thinking of stuff and forgetting it and/or dumping a long list of stories at once that may or may not be relevant. Ideally, I’d be quickly and easily able to add stories to the icebox that can later be assessed for need and added to the project’s iteration quickly. Plus, I’d be able to quickly pull a story to start/finish it from within RubyMine.

Desired Workflow

1. Working on feature A, but realize a need for fix B. Keyboard shortcut to add feature in (modal?) window and save with <enter> closing window and cursor is right where it was.
2. Finish feature A and keyboard shortcut to stage/commit with optional alternative keyboard shortcut to bring window of “active stories” that I can cursor down to and hit <enter> (add story to commit message) type commit message and hit <enter> (again, closing window and returning with cursor placed)
3. work on fix B…
4. M-I-C-K-E-Y without using my M-O-U-S-E

Want that beer?

Someone tell me how to do this. Let me buy you that pint!

I know we’ve got to be able to do this, because, well, why the heck wouldn’t we?¹ What I want to know is what is the PivotalTracker team itself using?

What are you using? I’ve searched for a solution to no avail. Is there a better way to add stories and get the story id into a commit message? Or am I just being ridiculous?

Give me this, JetBrains, and I will buy RubyMine today.

1. The usual answer to this is “because my lazy ass hasn’t coded it up yet.” To which I have no real response. <cough><cough>it’s commercial software<cough>

Now, they’ve gotten better with the release of version 3 of their API:

This Pivotal Tracker update allows you to see GitHub or other SCM commits in your stories, your project activity in your team’s Campfire chat room, and introduces the first wave of integrations with other bug/issue tracking applications including JIRA, Lighthouse, and Satisfaction.

This update allows me to add a post-commit hook to my Github account by going to the Profile Page on Pivotal Tracker and creating a new API token, then going to the service hooks page of my Github Repository and adding the following line:

https://www.pivotaltracker.com/services/v3/github_commits?token=PIVOTAL_API_TOKEN

as a post-commit URL.

Now, say I have a story for my recent small Ruby on Rails secret learning project, and that story is #2288984. I can create a commit messages like so:

Ullr:tweetscore john$ git commit -a -m "[#2289377] Add profile/login links back to main navigation"

And that story will be started. I can finish a story by committing with the message:

Ullr:tweetscore john$ git commit -a -m "[Fixes #2289377] Add profile/login links back to main navigation"

The great thing about this, is that if you send “fixes” on a story that’s not started, it will start and finish it.h

I haven’t yet played with Get Satisfaction connectivity yet, and don’t use Campfire or Lighthouse, but this is enough to excite me. It makes a killer workflow.

Now, if only someone would create a Quicksilver plugin for Pivotal Tracker…