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
Now we’ll do some basic configuration. Within the bash, enter:
git config --global user.name "Your Name" git config --global user.email "email@example.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 "firstname.lastname@example.org"
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:
If you are using XP than replace
C:\Documents and Settings\. If you still can’t find the file, goto your bash shell and type c
at ~/.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
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
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).
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).