Hosting your OSS project on github

Maybe you’ve heard me or others blather on about how great git is and how great github is to host git projects. Maybe you’ve heard it enough that you want to give it a shot or at least see what is involved in it and why us crazies think it’s so great. I’ll attempt to describe how one could go about moving their project to github and some tips for maintaining it. This is by no means a comprehensive guide, but it should be enough to get you started. Thankfully there is plenty of content on the net already so I’ll be doing a lot of linking.

Step 1 – Install Git and create your github account

Read through this awesome guide from Kyle Cordes.

Mac users – follow one of the guides on github to get git installed, then follow the rest of Kyle’s guide.

Step 2 – Import your svn project onto github

There are a few ways you can do this. Github makes it very easy by allowing you to just import an svn repository from their UI. Here’s a guide on github on some ways to do this.

Step 3 – Clone your project locally

Kyle’s guide talks about how to clone your repository. It’s pretty simple though, just type "git clone git@github.com:username/repositoryname.git". You can see your public (read-only) and private (read/write, use this one) clone url here on your project’s page, like this:

Step 4 – Setup your .gitignore

Unlike SVN’s abomination of ignoring procedure, git sticks to a single .gitignore file in the root of your repository to specify ignored files. This makes it very easy to get things up and ignored and keep them clean. In SVN, every time you add a project you’d need to ignore the bin and the obj directories for instance. In git, you just have one rule that always ignores them. Here’s a sample of my baseline .gitignore file:

obj
bin
_ReSharper.*
*.csproj.user
*.resharper.user
*.resharper
*.suo
*.cache
*~
*.swp
/Build
NDependOut

Once you’ve got that file set up, you’ll need to commit it and push it. There’s lots of guides on committing and staging and such and I’ll link to those below, but for now just do this:

git add .gitignore
git commit -m "Adding .gitignore"
git push

So what did that do? The first line, git add…, staged the added file for commit. All changes, adds, deletes, etc, must be "staged" before they are committed. Staging is a powerful thing, but I’ll let the other guides go into that. The next line, git commit…, committed your staged change to your local repository. This is so quick because it doesn’t actually talk to github. The change is only local. The next line, git push, actually pushes your changes up to the remote repository (github).

Step 5 – Learn

Time to pause for some learning. Like I mentioned, there’s a lot of great material out there already. Here are a few resources:

  • An Illustrated Guide to Git on Windows – Great guide to using git on windows and all of the gui tools available with msysgit
  • GitCasts – Some great screencasts showing how to work with git. A lot of content here, some are a bit long but they’re great learning tools.
  • Why Git is Better than X – Great for showing people the difference between git and other source control solutions. Helpful sales tool if someone is on the fence.

Step 6 – Maintain and accept contributions

So now the fun part. You get git. You have your project on github. Now what? How do people send you patches? Do they still email you patch files? Isn’t there a better way? I thought I said git was better! Never fear, yes there’s a *much* better way to accept contributions now that you’re using git and on github. Remember, git is a distributed version control system. It was built for this stuff!

First, the benefits:

One of the coolest things you’ll notice after accepting your first patch from someone in git is that not only will you have all of their individual granular commits in your timeline (rather than one giant patch) but those commits will still be attributed to the original author and even maintain their original change date!

Next, how to contribute:

  1. Find your repository on github.
  2. Fork it (click the little fork button). Forking on github is not necessarily claiming that you’re going to go your own way with a project. I’ve seen people new to github get concerned when their project was forked, but really it’s just the beginning of the contribution cycle.
  3. Clone your fork locally. For example,
    git clone git@github.com:aaronjensen/machine.git
  4. Add a remote for the original repository, this way you can get any changes to that repository locally.
    git remote add machine git://github.com/machine/machine.git
    git fetch machine
  5. Make local changes. Commit them. Push them.
  6. Send a pull request. This will notify the original repository’s owner that you want them to pull your changes and merge them into their repository. Here’s a github guide on the subject.
  7. Sit back and wait for the project owner to accept your patch!

Finally, how to accept patches:

As a project owner when one of these pull requests come in you’ll get a message in your inbox on github. From there, you can either manually pull from the command line like mentioned in the above github guide or, if there would be no merge conflicts, you can use github’s swanky Fork Queue UI to merge changes in from the site itself! Check out a post and a video about that.

Step 7 – Enjoy the pretty pictures

Github has some really cool graphs for all of the projects. I encourage you to check them out. here are a few from machine:

This entry was posted in git, training. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://www.sistemhost.com hosting

    Very nice… Thank you your reply…

  • http://codebetter.com/members/aaronjensen/default.aspx aaronjensen

    Put up with what exactly? I’ve been using msysgit for months now. Aside from it being a bit slower than the linux version (though still significantly faster than svn) it runs great.

    I’ll be the first to admit I haven’t first hand tried hg or bzr, but from what I’ve read, I’m quiet happy to stick with git–they appear to offer little that git does not and take away a few things that I like about git. Though not an independent and unbiased authority, there is interesting information here: http://whygitisbetterthanx.com/

    Furthermore, there is nothing that I’ve seen that compares to github for source hosting, so even if all things were equal w/ the technology itself (which they aren’t) I’d still choose git based purely on github’s existence.

    Also, many ALT.NETers are getting more and more into the ruby and other non-.net spaces, so git knowledge is helpful there too.

  • http://wekempf.spaces.live.com wekempf

    I’m curious about the Git hyping within Alt.NET and the blogosphere lately. Git is so tightly coupled to POSIX, that the Windows port is awkward at best. Why do people choose to put up with that, instead of using one of the other DVCSs, such as hg or bzr?

  • http://abombss.com Adam Tybor

    Nice article Aaron, I have to agree with you about not needing a Visual SVN or Tortoise. Gits cli has worked just fine for me because like you pointed out there are no moving or renaming issues like with SVN.

  • aaronjensen

    Brian,

    Another lovely thing about git is that you don’t *need* visual studio integration. Most of what visual studio integration does in the SVN land is the move/rename tracking. Git does this for you, automagically, so you don’t need a fickle tool to issue commands for you. I haven’t missed it at all. On the contrary actually, I love being able to move and rename without having to wait for VisualSVN to issue its commands.

    Git has a few gui tools, the most useful of which is probably ‘git gui’ which I tend to just keep open. You can use git gui to see changes and stage changes for commits. I also use gitk to visualize the commits/branches and sometimes reset to particular commits.

  • http://brianbrowning.wordpress.com Brian Browning

    Does visual studio have any decent git integration yet?

  • http://flux88.com Ben Scheirman

    Good post, I’m almost to the tipping point with Git, and github just seems awesome.

    Oh, and btw you can setup global ignore for TSVN, right-click, TortoiseSVN->Settings.

  • http://www.tobinharris.com Tobin Harris

    Awesome post that, I use Git/GitHub daily and wasn’t sure about the forking situation.

  • http://blog.donnfelker.com Donn

    Good tutorial. Thanks Aaron

  • aaronjensen

    Hey Ryan,

    Check out tortoisegit: http://code.google.com/p/tortoisegit/

    I haven’t used it, but I heard it’s coming along. Also, AnkhSVN/VisualSVN aren’t nearly as needed with git as you don’t have to track moves/deletes/etc yourself. No need for IDE integration except to commit, and for that I generally just keep a ‘git gui’ open at all times.

  • Ryan Montgomery

    This is great! I can’t wait to get started with Git. One thing I can’t seem to find is a TortoiseSVN/AnkhSVN replacement. Those tools really make SVN as useful as it is.