Background:

Last week we released the open source social network Lovd By Less. Almost immediately we had requests for people wanting to add code back into Lovd. Lovd had been housed in a private svn repository and distributed via a zip file. This was really good for me, but not so for people that want to take the current version, build on it and later merge whatever newer version of Lovd is available into their app. Although I hadn’t yet tried git I knew that it made this sort of branching a lot easier than subversion, so I decided to try it.

Getting started with Github:

Github is the new cool git repository website (social network for geeks). I asked a friend for an invite and got started. Creating a github account and repository is really easy. The instructions are well laid out. The last step is to export your svn repo into the git directory and then commit and push. I’ve been told that if anyone needs a git invite to let me know and I’ll be given invites to send out. So let me know.

Now what?

So now I had my git repo setup on github and I started sending out the repo’s public address. And before I know it I had my first patch. Now what? I read Dr. Nic’s blog post about git when it came out, so I went back and read it again. After reading a few times I realized two things: (1) That git is very complicated and (2) Dr. Nic is a way bigger StarWars geek than I ever gave him credit for. I called my friend Josh Owens (of the Web 2.0 Show) and asked for some help. Josh talked me through my first merge and push, but I still didn’t quite get it. The next day I was trying to merge another patch (branch) and since Josh wasn’t around I went into #github where Tom Preston-Werner (mojombo) helped sort me out quite a bit.

Disclaimer:

I am still new at git so I may have things wrong, so if you find an error or omission, please say so in the comments.

Git explained (I think):

Understatement: Git is very different from Subversion. Git is a distributed source control system, which means you can work disconnected from the main repo (branch) and still commit. But you commit to your local repo (branch). The basic flow is (some crucial steps have been left out for now. I’ll fill those in later. Don’t use the following as a step by step guide, that comes later):

1. git clone. This basically tells your local git to go out an pull the files from the server.
2. Make your changes.
3. git commit. This commits your files to your LOCAL repository, not the one on the server.
4. git push. This “pushes” you committed changes up to the server.

OK, so far so good. This feels a lot like svn. So much that it’s time to get overconfident and think we get git. But we don’t. And our confidence is about to be shaken like a dry martini.

But I have my own repo and people are trying to commit to me. What do I do, how does that work?

You are the master:

In git everything revolves around branches (github calls them forks¹). When you create a git repo, that main branch is called “master.” Your master branch is kind of like what trunk is in svn. When someone wants to fork/branch your master, they go to your page in github and click the fork button. Now they have a fork/branch of your master branch. When they are ready for you to check out their changes and merge theirs back into your master they’ll send you a message via git hub. You’ll get this message in your inbox and have no idea what to do with it. Cool.

The first thing to notice is that the url for their branch looks a lot like the url to your master. My “public clone url” is git://github.com/stevenbristol/lovd-by-less.git. Dr. Nic’s looks like this: git://github.com/drnic/lovd-by-less.git. The similarities matter.

To get Dr. Nic’s branch and merge it into my master I do the following (let’s assume I have my master cloned to /lovd):

NOTE: Put the contents of this pastie in the top of your ~/.bash_profile file to see which branch you are currently working in. This is demonstrated in the examples below. The part in parens is the branch. (Another version of the same thing.) (After changing your ~/.bash_profile file you’ll either have to restart terminal or source the file to see the changes.)

1. /luvd(master) $ git remote add drnic git://github.com/drnic/lovd-by-less.git
2. /luvd(master) $ git pull
3. /luvd(master) $ git checkout -b drnic/master
4. /luvd(drnic/master) $ git pull drnic master
5. [look at the files, rake, test, etc]
6. /luvd(drnic/master) $ git status
7. /luvd(drnic/master) $ git checkout master
8. /luvd(master) $ git merge drnic/master
9. /luvd(master) $ git status
10. /luvd(master) $ git commit -a
11. /luvd(master) $ git push

• Step 1 tells my local git repo to add a new remote repository. This means that the same repo can pull and push to two different server². There is nothing analogous in svn. The syntax is “git remote add {name} {url}.” I am naming this remote “drnic,” because I am going to pull his branch.
• Step 2 simply pulls my local master. This is like doing an svn up. I do this because I gave commit rights to someone else and I want to make sure I have the latest changes in my local master. Step 4 also does a pull, but there we have to specify where we are pulling from. Here it defaults to the “origin,” which is my git master on github.
• Step 3 is a bit confusing because I am not doing anything like an svn checkout. A git checkout basically changes the branch I am working with. The -b switch means to create the new branch³. Notice that in steps 1 -3 I was in branch master (master) but after I “git checkout drnic/master” I am in branch drnic/master (drnic/master⁴). Get ready: Rather than have each branch in a different directory on the file system, all the branches live in the same directory. What? Exactly. Try this: Open Textmate and open a file that you know has changed between the two branches. Now go in to terminal and “git checkout {other branch}.” Go back to Textmate and notice that the file did actually change. What? Exactly. Isn’t this cool? But it means you must use the .bash_profile hack to know what branch you’re working in. Other wise you will go crazy. You can also do “git branch” which will tell you what branches are available locally and which one you are in.
• Step 4 just says pull all of the files from the remote repo named “drnic” (which we created in step 1) and the branch, in this case “master.” Syntax: “git pull {name of remote} {name of branch}.” This is kind of like an svn checkout.
• Step 6 shows which files have modifications. If you didn’t change anything then you can go on to step 7, otherwise you might have to git commit to your local branch of drnic’s branch of your master. (Don’t feel bad if you have to reread that a few times :)
• Step 7 puts us back in the context of our master branch.
• Step 8 merges the local drnic branch into our master branch.
• Step 10 commits all unadded files to the local master repo. Unadded? Yes, in git a file with local modifications needs to be added back into the repo for committing. You can do this with “git add {file}” or just git commit all the added and unadded files.
• Step 11 pushes your local changes back to your origin (master branch on github). Now other may fork/branch your master and start again. Easy right?

You just want to patch some else’s repo:

This is really simple. Here are the steps:

1. Go to github and click the “fork” button.
2. git clone git://github.com/stevenbristol/lovd-by-less.git
3. cd lovd-by-less
4. Make your cahnges
5. git status
6. git commit -a
7. git push
8. go back to git hub and click the “pull request” button.

I’m guessing that by now this is really clear.

1. Step 1 will create you own fork of the repo where you can make your changes. Click this on the person’s page you want to fork from.
2. Steps 2-7 you should understand by now. (I hope. :)
3. Step 8 will send a message to the person notifing them that you have something for them to see. Click this from your repo page.

References:

• cheat git
• http://drnicwilliams.com/2008/02/03/using-git-within-a-team/
• http://github.com/guides/
• http://wiki.sourcemage.org/Git_Guide
• http://git.or.cz/gitwiki/QuickStart

Notes from Dr. Nic:

¹ Technical not correct. “Within a repository/clone you can have branches. A fork is a clone of a repository. Its a conceptual thing.” He continues, “I could manually create a fork by cloning 1+ branches from a target repository, then push that repository to my own remote repository. At this stage, I’ve theoretically got a remote clone of your remote repo. “Forking” is a nice word for this.” This is how someone can take Lovd, put it in their own private repo, build their app on top of Lovd, and easily get the latest patches from Lovd into their new killer app.

² “A “remote” repo and a “local” repo contain the same information about the commits etc. The difference is that a “local” repo has a checkout of one branch plus a .git folder containing all the commit info. The remote repo just contains the commit etc information, but no checkout (see “git checkout—bare” I think creates a remote repo that you could host on from your laptop’s ~/Sites folder for example.”

³ ””git checkout -b drnic/master” – I tend to use “local/drnic/master” now – using local/ as a namespace to separate it out from any clashes with the remote repo. I think this is different from my original blog post.”

⁴ “The -b switch means to create the new branch, based on the current branch.”