A Short Tutorial on Eclipse/EGit/GitHub

I wrote this to help out some of my collaborators on our AI project for class, but I figure it might help some other people get started using version control.

Step 1: Get Eclipse

If you don't want to work in Eclipse, that's fine; you can access the source files directly without it. You will, however, need to look up how to generate SSH keys for your platform and how to set up Git on your own. GitHub has a nice tutorial after you sign up; so skip to step 2 and then take it from there.

If you do want to work with Eclipse, download the latest version here: http://www.eclipse.org/downloads/ and get the Eclipse IDE for Java Developers. Once you have it downloaded, extract it to someplace you will want to keep it, and double click on the eclipse icon to start it. We need to install the EGit plugin to use Git from Eclipse, so go to the "Help" menu item and click on "Eclipse Marketplace". Search for EGit, and install it (it should be the only item that comes up). Restart Eclipse when it prompts you to.

Eclipse is a powerful development environment because it's open source and has a ton of plugins for development; but that also makes it slow sometimes. Let's make it go a little quicker. Go to the "Window" menu and click on "Preferences". In the window that opens up, expand the "General" item, and go to "Startup and Shutdown". This will show all the plugins that get started with Eclipse. Unselect all of them and click Apply".

Ok, now that we're in our settings panel, go to "Network Connections" and expand it. It's under "General". Click on "SSH2", and move to the key management tab. IF YOU ALREADY HAVE A PUBLIC/PRIVATE SSH KEY GENERATED, SKIP THIS STEP. IT WILL OVERWRITE ANY EXISTING KEYS, AND YOU WILL NOT BE ABLE TO USE THEM ANYMORE. Otherwise, click on "Generate RSA Key..." It will create a public/private key for you; copy the public key from the text area and hold onto it. Don't do anything more with Eclipse at this point; we need to set up our GitHub account before we go further.

Side Note: If you already have a public/private key pair, you can open up the public key file (should be in /home/yourusername/.ssh/id_rsa.pub on Linux) and copy it for the next step.

Step 2: Getting Your Account Set Up

Ok, first things first: We need to set up a GitHub account. To do this, go to the main page at http://www.github.com and click on "Plans, Pricing and Signup" in the middle of the page. (It's big and blue.) At the top of the next page, it has a free hosting plan above all the paid ones; click on "Create a free account". Type in your username, email, and password (Generally, using your real name is a help in these kinds of things, since employers/future project leaders/current collaborators can tell who you are and what you've worked on) and click "Create an account".

Cool! So we have an account. Next thing to do is set up our SSH key. Go to "Account Settings" at the top of the page click on it. On the left sidebar is an option "SSH Public Keys", click on that. We'll want to set up another key, so click on "Add another public key". Give it a descriptive name in case you need to modify it, and paste the public key from Step 1 into the big box. Save the key, and you're done! If you haven't saved your key in Eclipse, go back and do that now. Click "Save Private Key", and put it into the default folder. If you want to put a passphrase on it, I encourage you to do so; if your private key gets stolen the thief has your identity and access to any server that uses that key.

Step 3: Clone the Repository

Back at GitHub, go to this url: https://github.com/CP365-B6-2011/Final_Project Copy the url on that page (where it says SSH | HTTP | Git Read-only). We need it to clone.

Go back go Eclipse, and go to File -> Import. Expand the Git category, and click "Projects from Git". This will pop up a window with all of your configured repositories, which at this point is none. Click "Clone" at the top right, and it should autofill the fields with the URL we've copied. If it doesn't, paste it into the url field. Under protocol, go ahead and change it to SSH, and click "Next". It'll try to authenticate to the server, and if you've set up your SSH key correctly it'll succeed! Enter any passwords it asks for and continue. It'll pop up a window with the various branches on the server; you can clone any of them that you want, but I recommend that you keep your team's code in a branch off of master. Definitely clone master. Once you've selected the branches you want, click "Next" and it'll ask you for a directory to put it into; put it wherever you want to. Don't change anything else. That will give you a copy of master that we can work on, and everything should be kosher.

Back to the main Import from Git screen, select the repository you just cloned and click "Next". Leave the defaults on the next page, and click "Next" again. Check "CP365_FP_GIT" and click "Finish". What do you know? You have a new project, with Git and everything!

Step 4: Working on the Project

If you didn't quite catch my presentation, there's some OpenOffice Impress slides you might want to look at here.

It's really best if each team works in their own branch. I'll set some branches up for each team later this afternoon, and I'll show you how to get them at our meeting. Until then, if you're really skippy and doing work already, feel free to work in master.

As far as working goes, do your work on whatever you're doing, then add our files by holding CTRL while clicking on each of them; right click on one of the selected files; go to "Team" -> "Add" and it will add your files to the repository. Immediately after doing that, commit by going to "Team" -> "Commit". Be sure to enter useful messages, we want to be able to see what's going on! When you've got en enough of your work done that you feel like it should be shared, go to "Team" -> "Push to Upstream". If it gives you a failure on the popup window, pull from upstream before pushing; it probably means someone pushed before you did. Well, that's all for now. Check back for more in a later post!