Getting the Hang of GitHub

Andrew Burgess on Jan 11th 2010 with 19 comments

A project is always more fun when you’ve got friends working with you, but how can do it when working on a coding project? I’ll keep my keyboard to myself, thanks.

Enter GitHub. With this web service, you can share your coding projects and collaborate with ease!

Disclaimer

This tutorial will assume that you’re familiar with Git, arguably the best distributed version control software there is. Already lost? Don’t worry: read my introduction to Git to get up and running. Then come on back here and find out all about GitHub, the social network for developers!

Getting Started

Of course, you’ll need a GitHub account if you’re to experience any of the social coding goodness. Let’s do that right now. Head over to the GitHub website and click “Pricing and Signup” at the top.

Creating an Account

There are several different plans you can use, depending on your needs. Right now, the free “open source” account is all we want; so let’s click “Sign Up.” It’s your standard sign up page; enter your name, email address, and password. You’ll also need an SSH public key; I explained how to get one in my previous article:

Open up your terminal and type this: ssh-keygen -t rsa -C "your@email.com". The t option assigns a type, and the C option adds a comment, traditionally your email address. You’ll then be asked where to save the key; just hitting enter will do (that saves the file to the default location). Then, enter a pass-phrase, twice. Now you have a key; let’s give it to GitHub.

First, get your key from the file; the terminal will have told you where the key was stored; open the file, copy the key (be careful not to add any newlines or white-space).

Once you have the key, just paste it into correct field. Like it says, you don’t have to do this now; you can add a key later. Then click the button to agree and sign up.

Warming up to the Interface

When you first log in, you’ll see the dashboard; it’s something like this:

In the top right corner, you can see a toolbar with options for controlling your account. There are also some links for getting around GitHub, as well as the search box.

The main panel offers a number of actions; later, it will be used to keep you up to date on projects you’re interested in. And on the right of that, your own repositories will be listed. Remember, in Git, repositories are the containers that hold all the code and history related to one project.
When you have a chance, browse around the Account Settings, It’s all what you’d expect, so I won’t go over it; but if you plan to be an avid githubber, you should probably fill out your profile and see what else is in there.

It’s all about Repos

Really, the whole purpose of GitHub is making Git repositories available to the world; therefore, it follows that working with repositories (or repos, as they’re often called) is something you should be comfy with.

Creating a repository is pretty simply. On the dashboard, click “New Repository” on top of your repo list (which is currently empty).

Three textboxes await you here; your repository will need a project name, a description, and the URL for the project’s website. If you’ve upgraded to one of the paid plans, you can choose whether this should be available to the public or not. When you’re done, hit “Create Repository.”
GitHub will now give you instructions for hooking the GitHub repository up to one of your local Git repository. If you’re familiar with Git, this should be pretty old hat to you. The important part is the last two lines of either the “Next Steps” or “Existing Git Repo?”

view plaincopy to clipboardprint?

1.   git remote add origin git@github.com<script type="text/javascript">  
2. /* <![CDATA[ */ 
3. (function(){try{var s,a,i,j,r,c,l,b=document.getElementsByTagName("script");l=b[b.length-1].previousSibling;a=l.getAttribute('data-cfemail');if(a){s='';r=parseInt(a.substr(0,2),16);for(j=2;a.length-j;j+=2){c=parseInt(a.substr(j,2),16)^r;s+=String.fromCharCode(c);}s=document.createTextNode(s);l.parentNode.replaceChild(s,l);}}catch(e){}})(); 
4. /* ]]> */  
5. </script>:aburgess/My-First-GitHub-Repo.git  
6.   git push origin master  

The git-remote command allows you to track other repositories and keep them “synchronized” with your local one. In our case, we’re tracking the repository on GitHub from our local repository. So, that first line is adding a remote; we’re calling it “origin” and giving it a URL. This is a private URL that only you can use to read and write to your GitHub repo.

In the second line, we’re using the git-push command to send everything in the master branch out to origin (our GitHub repository). Notice that none of the coding or project work (creating files, etc) is done on GitHub. That’s all local work; you should work on your project just as you would a plain vanilla local repo. However, you’ll regularly push it to GitHub with that second line.

So let’s say you’ve been working on a project for a while and you’ve been pushing your commits to a GitHub repo. What project meta-data can we explore on GitHub? Let’s look at the jQuery repository.

See that toolbar near the top, just under the project name? These options allow us to drill down into some of the Git information that we uncovered in the command line last time. Right now, we’re on the source tab. It starts with drop-downs for the repo branches and tags; use these to view the different branches or tags. There’s also some project meta-data; we have the project name, URL, and cloning URLs (These URLs are read-only).

Then, you can see the information about the latest commit: author, time, comment, and hashes. Under that, you’ve got a file browser, which shows you the latest versions of all the files in the project, as well as their age and the message of the last commit they were changed in.

If the project has a readme file, it’s displayed under the file browser.

Commits

Let’s switch to the commits tab at the top and see what it holds.

As you might expect, we can view a backlog of commits on this project. Clicking the commit hash (on the right of the commit entry) will let you view what was changed in the commit.

Green lines (prepended with a ‘+’) are additions and red lines (prepended with a ‘-’) are deletions.
You can subscribe to the commit history RSS feed of any repo if you want to keep track of it.

Network

The next tab is the network tab; this shows you a graphical representation of the repository’s history. This graph is drawn from the perspective of the committer ‘jquery.’ Each commit only show up once, so commits not on jQuery’s line are not in jQuery’s repo. This way, we can see what commits other people have made that we don’t have. It’s incredibly useful, but somewhat confusing if you’re not grokking git all the way. If you want to know more, check out GitHub’s blog post about it.
The network tab also offers a list of members (people who have forked the repo) and a feed as well.

Graphs

The graphs tab offers you a number of different view of your project from a graphical perspective. It’s really just meta-data, but it may offer some interesting insights:

Fork Queue

If you’re viewing a repository you own, you’ll see another tab, Fork Queue. This shows you the same information you saw in the network graph, but differently. From here, you can choose which commits to apply to your repository, on whichever branch you want. For more on the fork queue, check out this post and video on the GitHub blog.

You can enable three other tabs from the repo admin panel: Wiki, Issues, and Downloads. These allow you to create a wiki, track bugs in your project, and offer downloadable copies of your repo. They are all pretty intuitive.

The Social Side

Like the tagline says, GitHub is all about social coding. Although we’ve already seen a few of them, it’s time to check out the rest of the social features of GitHub.

Exploring Other Repositories

If you ever have some free time and want to dig into a coding project for a while, GitHub is the ideal place to go. Let’s see how we can find interesting projects.
Start by clicking the “Explore GitHub” to the right of the search box. We’ve got a couple of tabs to choose from here:

• Repositories
• Search
• Timeline
• Languages
• Changelog

For me, the most interested is the languages tab; choose your language and check out the most watched and most forked projects for that language.

So let’s say you’ve found a project you’re interested in; what next?

Interacting with other repositories

When viewing a repo, the social tools are underneath the search bar. Starting at the right, you can see how many people have forked the project, and how many people are watching it. We’ve been talking about forking and watching, but it’s time to get some formal definitions on the table.

• Forking a project means that you’ll get a copy of that repository that you can play with all you want.
• Watching a project means that any actions on it will show up in your news feed, on your dashboard.

I’m taking a rabbit trail, but you can do more than watch projects; if you find particularly talented developers, you can follow them to track their every keystroke. Just click the follow button on their profile page.

You can also send them a message if you’d like. Now we’re talking social network!

Back on the social toolbar, the next button (moving left) predictably lets you download the source code of the project. The next button let’s you fork the repo, and the last one let’s you watch it (you saw that coming).

If you’re looking at a repository of your own, there will be two other buttons in the row: ‘Pull Request’ and ‘Admin.’ We’ll come back to ‘Pull Request’ in a minute; feel free to look around the admin panel.

It should be obvious most of the basic features are:

• change your default branch
• create a project page (we’ll come back to this)
• turn those extra tabs (wiki, downloads, issues) on/off
• rename or delete the repo

When you’re done, click your project name at the top to return to the source view.

Our scenario before introducing the social tools was that you had found a repo you want to work on. The first thing to do is fork the project; just click that ‘fork’ button. Now you’ve got a copy of the repo in your account. Let’s clone the repo to your computer, using your private clone URL. Doing this automatically sets up a remote called origin, as we discussed earlier. That origin is not the original project you forked (you can’t write to that) but your forked copy of it. You do need to set up a remote for the original project, however; do that with this command:

1. git remote add upstream [original project's public clone URL here]  
2. git fetch upstream  

That last line gets the latest branches from the upstream remote and stores them in tracking branches.
Now’s the time to begin coding. As you make commits, they’ll show up the the original project’s network graph, because they aren’t in that repo. They’ll also show up in that repo’s fork queue, so the owner can pull them in if he/she likes them. However, you can request that they be pulled in. That’s what the pull request button is for: you can send the owner of the original repo a message.

It’s nothing fancy; really, it just lets them know that they should check out their fork queue.
But what if they’ve made changes to the project since you forked it? It’s best practice to integrate their changes into your repo before requesting they pull in your changes. You can easily get their updates using that upstream remote you made! Just run this command:

1. git fetch upstream master  
2. git merge upstream/master  

As we just saw a moment ago, the fetch command gets the latest content from the specified remote, in this case our upstream remote. Also, we’re specifying that we only want the master branch. The second line merges the specified branch with the one we’re on. We’re on the master branch of our local repo, and we want to merge our tracking branch upstream/master.

Note: If this tracking branch talk is confusing you, check out this article on gitready.com. Basically, tracking branches are simply branches that keep track of where other repos with the same project are in relation to your repo. To see all your branches run the command git branch -a. Here’s what I get for a forked repo:

If you’re lazy, you could run the command git pull upstream master. This does both the fetch and merge commands at once. However, this could cause merging problems, so stay away from it!
Once you’ve merged the changes, you can request a pull with peace of mind, knowing your fork is up to date with the upstream repository.

User and Project Pages

Github gives you a rather unique ability to create a personal website from a GitHub repository. My GitHub username is andrew8088, so if I created a repo named andrew8088.github.com, it would be published at http://andrew8088.github.com. Simple as that!

You can also create a site for a project; this is a bit more complicated, but GitHub makes it easy to get a generic, single page explaining your project. Click that admin button in your social toolbar. Then click ‘Generate Your Project Page’ under ‘Repository Information.’

Then, just fill in all the fields:

And click “Create Page.”

If you want to customize your page further or add pages, you can follow the advanced instructions at theGitHub Pages Help.

When it’s only a Snippet

Ever been talking code with a friend online and wanted to share a snippet? It happens to all of us, and GitHub offers a quick way to do it. It’s Gist. They say it best:

Gist is a simple way to share snippets and pastes with others. All gists are git repositories, so they are automatically versioned, forkable and usable as a git repository.

Click the Gist link to the left of the search box, or go to Gist.GitHub.com. You can simply paste in your snippet or type it all in. Give it a file name and let them know what language your writing (for syntax highlighting). Then click ‘Create Public Gist.’ Copy the URL and share!

Keeping in the Know

Any social network can become addicting, and GitHub is no different. If you want to keep track of your repos on the go, check out iOctocat, the GitHub app for iPhone and iPod Touch.

Conclusion

Well, it’s been a whirlwind tour, but I hope you’re feeling more familiar with what could be the best code hosting/sharing site on the web! Ever used GitHub? Have a better option? Hit the comments!