Run a business? Check out LessAccounting, our bookkeeping system that'll save you hours per week.

Announcing:

We built the entrepreneur's bookkeeping system, it's called LessAccounting. You'll probably love it.

Got Git? HOWTO git and github

written by Steven on March 25, 2008

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):

  • git clone. This basically tells your local git to go out an pull the files from the server.
  • Make your changes.
  • git commit. This commits your files to your LOCAL repository, not the one on the server.
  • 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 forks1). 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.)

  • /luvd(master) $ git remote add drnic git://github.com/drnic/lovd-by-less.git
  • /luvd(master) $ git pull
  • /luvd(master) $ git checkout -b drnic/master
  • /luvd(drnic/master) $ git pull drnic master
  • [look at the files, rake, test, etc]
  • /luvd(drnic/master) $ git status
  • /luvd(drnic/master) $ git checkout master
  • /luvd(master) $ git merge drnic/master
  • /luvd(master) $ git status
  • /luvd(master) $ git commit -a
  • /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 server2. 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 branch3. 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/master4). 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:

  • Go to github and click the "fork" button.
  • git clone git://github.com/stevenbristol/lovd-by-less.git # cd lovd-by-less
  • Make your cahnges
  • git status
  • git commit -a
  • git push
  • go back to git hub and click the "pull request" button.

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

  • 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.
  • Steps 2-7 you should understand by now. (I hope. :)
  • 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:

Notes from Dr. Nic:

1. 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.

2. "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."

3. ""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." fn4. "The -b switch means to create the new branch, based on the current branch."

Business Owners: save hours per week with LessAccounting. It's like Quickbooks, just not total shit.

16 Comments

Josh Owens
Josh Owens said on March 25, 2008

Nice write-up Steve!

One thing to note, I would suggest branching if you fork a project and want to submit back. It is much easier for you to branch, push the branch, and then tell me to pull on the branch. If you don’t go this route, you might end up having to cherry pick the change out of all their changes.

Michael Whalen
Michael Whalen said on March 25, 2008

I would love a github invite :) I’m so sick of SVN and would love to give it a shot before getting down and dirty with configuration and all that jazz :)

Eric Anderson
Eric Anderson said on March 25, 2008

I looked at git about 6 months ago and found it terribly complex. I felt like I had to understand internals to understand how to use the thing. I have heard it is better these days but that left a bad taste in my mouth for the software.

I know all the cool kids in the Ruby world are working with git these days but I have found Bazaar to be great. It feels like SVN from a UI perspective but has the distributed workflow that Bitkeeper and git support. If you are interested in the distributed workflow but are turned off by the complications of git I highly recommend Bazaar. I know it doesn’t have the “in” status that git has but it works and is much simpler (IMHO). Kind of like SVN + distributed workflow instead of an entirely different system.

Lucas HĂșngaro
Lucas HĂșngaro said on March 25, 2008

Hey Steven, nice guide.

If you still have invites, I would like to receive one.

Also, check GitNub: http://github.com/Caged/gitnub/wikis/home

Geoff Cheshire
Geoff Cheshire said on March 25, 2008

Geoffrey’s PeepCast on git is also well-worth its $9 cover charge if you’re just getting started.

http://peepcode.com/products/git

Laurence Lee
Laurence Lee said on April 02, 2008

Very well written article, thanks! This clears up a lot of confusion I’ve had with merging changes from remote repositories.

I’d be grateful if you could send me a github invite, if any are still available.

Kristen
Kristen said on April 03, 2008

Good article. May I have an invite as well?

Jonas Grimfelt
Jonas Grimfelt said on April 03, 2008

Good summary of Git. Do you have any invites for GitHub left?

Perry
Perry said on April 04, 2008

Excellent job! Still have invites? If so, I would love one.

Alex
Alex said on May 07, 2008

I’m very new to git and github and I’ve been searching for some info on how to pull and merge forks and I am so glad I was able to (finally) find the tutorial on your site! Thanks so much!! :)

Jason Calleiro
Jason Calleiro said on June 06, 2008

Do i have to have an account on github to submit patches to others projects?

Steven Bristol
Steven Bristol said on June 06, 2008

@Jason,

Yes, everything on github requires an account. But they are out of beta now, so you can get an account without even asking.

steve

Ivan
Ivan said on July 09, 2008

Today was a weir way. I woke up earlier than usual (3 hours), saw a video of linus talking about git at google plex (http://www.youtube.com/watch?v=4XpnKHJAok8) , watched this screencast http://railscasts.com/episodes/96 (FOR FREE AS IN BEER), listened to half of a interview of one of the people at less, and last but not least fork, push, pull and commit for the first time ever.

pd: i am already on github!

lol

Mobile Memberships
Mobile Memberships said on February 24, 2012

This is a well written article. I also find git extremely complex. I would love to see more posts that break it down into small bites and simplify the process.

Mikael
Mikael said on June 26, 2012

Tiny suggestion: Use numbered lists instead of bulleted lists for the Git commands. It gets tiresome to have to count down the bulleted lists to correlate to your “Step N” descriptions :-)

Litsa
Litsa said on July 31, 2012

Thank you so much for this post. It helps to have stuff explained in terms of SVN.

About Steven
Steven Bristol has written code for the past 20 years. He like green vegetables and kittens, oh and butterflies too. He loves to throw ninja stars at his enemies.

You Should...

Follow Steven on Twitter
Friend Steven on Facebook
Subscribe
LessEverything Copyright 2011 LessEverything.com
We don't like footers, they're kinda boring