Bob's Blog

After hearing much on Twitter and the blogisphere about Git, I've finally decided that I need to invest some time in learning about it so I can decide whether or not it's for me.

I started out by watching a video that I found linked to somewhere. The video, Tom Preston-Werner, Chris Wanstrath and Scott Chacon -- Git, GitHub and Social Coding consists of three presentations by the guys that created GitHub. The first one, by Tom Preston-Werner, provided a nice overview of Git and GitHub - I found it quite useful. The second one, by Chris Wanstrath, went into more detail about GitHub itself. Although this is not necessary information for using Git, I found it to be quite inspirational. I began to see how not only is Git a cool version control tool, but how combining it with with something like GitHub can potentially help an open source project get more contributors, as it really lowers the barrier to entry. The final presentation, by Scott Chacon was way over my head. I didn't get much out of it, but may view it again in the future when I become proficient with Git.

Having attained a basic understanding of Git, I decided that it was time to install it, and attempt to move one of my open source projects to GitHub. I found a number of blog posts that cover getting started with Git, including a very useful series by Mike Henke, which starts with Setting Up a Riaforge Project with Git and Github (Part 1). Mike's posts cover setting up Git on Windows, and as I'm on a Mac I needed some more information. I found a post by Jaisen Mathai entitled How to get started hosting your git repository using GitHub and OSX, which included most of the setup instructions, as well as a post by Andrew Bednarz on theAppleBlog called Using Git With OS X: 6 Tools to Get You Up and Running which directed me to some of the software. I decided to take all of the information that I gleaned from those resources are compile it into this one post, for others that would like to get started with Git and GitHub on a Mac.

Step 1 - Install Git

You can, of course, compile Git from source, but I'm not that hardcore. Lucky for me (and maybe you), there's a Google Code project that provides an OS X installer for Git. As of this blog post I used the one labelled Git Installer 1.6.5 - OS X - Leopard - Intel. The download is a disk image with an installer package, a readme and a shell script. Run the installer first. The shell script, called setup git PATH for non-terminal programs.sh allows non-terminal programs access to Git. I have no idea if I need that, but I ran it anyway. Note that I had to change the permissions on the file in order to run it via terminal. Your Mac should now be able to run Git. You can test the installation by opening up a terminal window and typing:

You should see a message saying something like: "git version 1.6.5"

Step 2- Create an Account on GitHub

Sign up for a free open source account at GitHub. You only need to provide a Username, Email Address and Password. Leave the SSH Public Key blank for now (unless you know what you're doing and have one already). Note that the Username that you choose will be used to identify all of your projects on GitHub, so choose wisely.

Step 3 - Import an Existing SVN Repository

You don't have to do this, but it's what I did, so I'm including the steps here. First, create a new repository. There will probably be links on your GitHub dashboard to do this, or you can go straight to the Create a New Repository form. Give your project a name and description. You can also point to an external URL if one already exists for your project (e.g., a RIAForge project page), and click Create Repository. On the next page you should see a link near the bottom that says "Importing a Subversion Repo? Click here", so click there. You'll see a screen allowing you to import a repository from an SVN server. Note that currently this only works for public SVN repos. Enter the URL to your SVN repo and click the Import SVN Authors Button. GitHub will attempt to grab all of the authors from your SVN repo. On the next screen you can either assign a GitHub Username to each of the authors found, or to none of them. It's an all or nothing thing. Make up your mind, and then click the Import Repository button. GitHub will then import your SVN repository in the background. This can take as little as a few minutes and up to several hours. You should receive an email when the import has finished.

Step 3 - Configure your Mac to Talk to GitHub

To tell Git that you want to communicate with GitHub, open a terminal window and type the following:

That last command was something that I picked up from Mike Henke, that addresses issues with how Git deals with CRLFs.

Next, you need to create a public key and give it to GitHub. I'm assuming that you don't already have one (I didn't), so here's the process to create one. Note that in all of the steps where you have to type something, type everything following the colon, but don't include the double quotes.

1. Open a terminal window.
2. Type: "cd ~/.ssh"
3. If you get an error message like: "-bash: cd: /Users/username/.ssh: No such file or directory" then you can create a .ssh directory by typing: "mkdir .ssh". After you create the directory you should then be able to type: "cd ~/.ssh".
4. Type: "ssh-keygen". You'll see a message like: "Generating public/private rsa key pair.", followed by a prompt like: "Enter file in which to save the key (/Users/username/.ssh/id_rsa):". Just press the return key to accept the default.
5. You'll be prompted to: "Enter passphrase (empty for no passphrase):". Type a passphrase that you'll be able to remember.
6. You'll be prompted to: "Enter same passphrase again:". Do it.
7. You should then see a few messages indicating that your identification has been saved, your public key has been saved and showing you a key fingerprint. That's it, you're done generating your keys.

Now you need to copy the contents of your public key and paste it to GitHub. The easiest way to copy it is to type: "cat id_rsa.pub | pbcopy" from the same terminal window, which will place the contents of the file onto your clipboard. Then go to your GitHub Account Overview page and in the section entitled "SSH Public Keys", choose to add another public key and paste the contents of the clipboard into the key textarea, and click Add Key.

Get a Copy of Your Git Repo on Your Local Machine

If you go to the home page for your project on GitHub, which is something like http://github.com/username/projectname/, you should see a link labelled Your Clone URL. If you click it you should see a window popup with a command in it, which will look something like "git clone [email protected]:username/projectname.git". Open up a terminal window and navigate to a folder into which you want to store your Git repos, for example /Users/username/Documents/gitRepos, and then type in the command. Git should connect to GitHub and download a clone of your repo to your machine, at which point you can now work with it.

I am documenting all of this a few days after having done it, so I hope I haven't left anything major out. If you try it and run into difficulties please leave a comment and if I find that anything is missing I'll update the post.