Contributing to OSS, a Git Bootcamp

So you want to contribute to an OSS project, but its hosted on github and you don’t know where to start. This guide will cover the basics you’ll need to get contributing – something made relatively easy by Git itself.

First you’ll need to install a Git client. We’ll be using msysgit, so grab the latest full installer from: http://code.google.com/p/msysgit/downloads/list

Run the installer. I’ve disabled Shell integration (but you don’t have to). What you want to do is make sure you pick Bash Only and Windows Style when those screens come up. After it’s done installing, you should have a Git Bash shortcut on your desktop. Edit the shortcut and change the “Start in” path to where you do most of your work (e.g., most of my source code is in c:\work). Now start it up and you should get a bash shell. For the time being you just need to know that cd works the way it does in dos, and to use ls -l instead of dir.

Now we’ll do some basic configuration. Within the bash, enter:

git config --global user.name "Your Name"
git config --global user.email "your@emailaddress.com"

Next, create a free acccount on github. We now need to create a public/private keypair – don’t get discouraged, you only have to do it once and it isn’t hard. In your bash shell, type:

ssh-keygen -t rsa -C "your@emailaddress.com"

It’ll ask you where to save the key, just hit enter to accept the default value (the value that shown inside the parenthesis). Next it’ll ask you to create a password, so type something in and hit enter then confirm your password.

The last step in getting setup is to tell github about your public key. Go into your Account Settings on github and click the “SSH Public Keys” button and then the “Add another public key” link. Your title can be something like “My Home PC”. In the Key textarea, copy the contents of:

c:\users\YourName\.ssh\id_rsa.pub

If you are using XP than replace c:\users\ with C:\Documents and Settings\. If you still can’t find the file, goto your bash shell and type cat ~/.ssh/id_rsa.pub and copy and paste it from there (you may need to change the property of the window (top-left icon) and in the options enable “Quick Edit Mode”).

Ok, now we can get rolling. In GitHub find the project page that you’d like to contribute to. In this example we’ll pretend you wanna work a bit on http://github.com/karlseguin/Metsys.WebOp.

In the top right, hit the “Fork” button. You’ll be taken to your fork of the Metsys.WebOp project, something like: http://github.com/YourName/Metsys.WebOp

You should also see Private, Read-Only and Http Read-Only buttons. Make sure Private is selected (should be anyways) and copy the URL. Next, go into your bash and type:

git clone THEURL Metsys.Webop

You should now have a copy MetSys.WebOp on your computer. You can open the project, make changes, add files, delete files, whatever.

Rather than continuing linearly through what you do, we’ll switch to talking about what you can do.

First and foremost, the most important command is git status. Type this within the Metsys.WebOp folder (cd Metsys.WebOp) or any subfolder and you’ll see the current state of your repository. If you actually READ everything, it’ll normally tell you what you likely want to do next.

Whenever you add a file or files, you’ll want to type git add . to add all pending files (again, git status will make it clear that files exist which need to be added). The . means that all pending files are added. If you need to add a file which is being ignored (there’s a .gitignore text file in the root of the project which has a bunch of patterns to ignore), you use the git add -f FileName command (you’ll typically use this when you want to add a 3rd party reference .dll).

Whenever you want to commit your changes, type git commit -a -m 'Your Commit Message'. This will commit all files that you have changed.

Committing only updates your local repository. You’ll want to push this back to git hub by using git push (and git pull does the opposite, updating your local copy with the remote (github) one).

Where things get interesting is when you want to actually contribute to another project. Since you’ve pushed to your github repository you could goto your github project and hit the “Pull Request” button. However, to increase the likelihood of having your changes accepted you should do everything you can to make it painless for others to merge your changes in. You do that by first merging their latest copy with your changes (of course, since you just forked the repository there will be no differences in this case).

First you’ll add a reference to the main repository by typing:

git remote add KarlsFork git://github.com/karlseguin/Metsys.WebOp.git

then you pull that repository into your working copy:

git pull KarlsFork master
(master is the main branch, don't worry about branching for now).

Now execute git status

If there are any merge conflicts you’ll have to resolve them (these are typical diff files). Once they are resolved, you re-add them using git add . Next you commit your changes with git commit -a -m 'Merged Karls master', push using git push and you can finally do a Pull request via your proeject GitHub site (if there is a long list of recipients, try to only send the notice to the core developers you know are responsible for it).

By doing a merge before asking for a pull request, you ensure that pulling your changes into the main copy is a 1 command affair.

As you continue to work and move forward, you’ll want to pull from the main frequently, in order to avoid having to do complex merges. If the project is busy, you might even add other forks (using git remote add) and merge with them (sometimes the main fork doesn’t integrate often).

There’s a bunch more stuff you can, and will eventually need to do. You can learn a lot from:
http://learn.github.com/ or from TekPub’s Mastering Git series: http://tekpub.com/preview/git

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.

6 Responses to Contributing to OSS, a Git Bootcamp

  1. I wish I could do such a good tutorial

  2. Really nice Guide. I wish I could do such a nice tutorial..

  3. I wish I had seen this guide some month sooner. Because when I started working on Cuyahoga it moved from SVN to GitHub. My problem was that I was not familiar enough to Git. So never had the chance to work on it.

  4. Peter Lehmann says:

    a other good link got why to use Git is http://progit.org/book/

    a other thing I like to use “git add -A” when i need to add/remove all the changes i have make, as it also takes deletes

  5. John Sheehan says:

    Only set autocrlf to false if the project will only ever be opened on Windows. If you want people to be able to open it in MonoDevelop on Linux or OS X, true is a better option.

    Karl, the only thing I would add to this is the commands to easily scrap your changes and bring your local copy up to date with the latest remote master without wiping your repo, deleting it and reforking.

    Thanks for the article!

  6. Tuna Toksoz says:

    After cloning a repository, it is a good practice to check if there is any changes to the repository (right after the clone operation). IF you see any files being changed, it is highly likely that you run into autocrlf issue.

    Tim Barcz does a good job explaining it here on devlicio.us
    http://devlicio.us/blogs/tim_barcz/archive/2009/11/29/i-just-cloned-why-did-git-change-my-files.aspx

    To sum up his presentation, it would be good to have

    git config –global core.autocrlf false