After all the hubbub i’ve been hearing about github, I assumed it would be a web 2.0 type of company – one that makes everything flashy, pretty, and most of all, easy.
But, reality laughed in my (and seemingly everyone else who’s ever tried using github with out reading many different “how to” pages) face(s). Github, when it works, seems like a great tools to collaborate with other people, or use as an online repository to have access to your (public) code. But getting it to work can be a major pain.
I lately attended a hackathon, and the first thing the other team members wanted to do was share the project over github. Although I had a Github account, I never got it work before and (amazingly – surrounded by other programmers) during the Hackathon, so, when the hackathon was done, I sat down, and did a lot of research until I got it to work, and thought I’d share this with the world.
First, a little explanation as to what Git is. think of it as a special folder in which you can save all (or some) of your files, under a special tag, or “commit”. by committing things, you create a snapshot of your files at that particular point in time.
this must be done locally first – whether you decide to save your Git repository online somewhere (such as Github or Assembla), or not. so, your first stop would be to install the Git engine on your machine, locally. let’s do that now.
so, to install git hub on your Mac (windows folks, Github has a great Tutorial on creating and using Git on windows):
1. Install Git by following the directions in the link.
2. Next, open your Terminal (Command+ spacebar opens spotlight, type Terminal in there and hit Return) and configure your name, so your comments will have your correct name:
git config --global user.name "Your Name Here" # Sets the default name for git to use when you commit
3. One more step in the initial git configuration is to configure your email. we’re still in the same Terminal window (and will stay in it for pretty much the rest of this Tutorial):
git config --global user.email "firstname.lastname@example.org" # Sets the default email for git to use when you commit
4. The last thing you need configure is password caching. This works from git 1.7.10 and up, and it tells git you don’t want to input your username and password every time you talk to a remote server. First, you need to check and see if you have the osxkeychain app by typing in:
git credential-osxkeychain # Test for the cred helper
If you don’t have it, download it using a command called curl:
curl -s -O http://github-media-downloads.s3.amazonaws.com/osx/git-credential-osxkeychain # Download the helper chmod u+x git-credential-osxkeychain</pre> # Fix the permissions on the file so it can be run sudo mv git-credential-osxkeychain /usr/local/git/bin # Move the file so git can access it # Password: [enter your password]
and to let git know to use your osxkeychain:
git config --global credential.helper osxkeychain # Set git to use the osxkeychain credential helper
Hopefully at this point, you’ve completed all of these steps with no issues, and you now have Git installed on your machine.
Next step would be to actually create the Git Repository iself. this is done, once again inside the terminal. so change directory over to where your project is, and initialize the git repository inside that folder:
Next, add the files you’d like saved into this newly initialized repository. You can do each file individually, but I like to simply add them all using the * wildcard:
git add *
Assuming that your files are ready for the initial Commit (remember, this simply saves a snapshot of the files under whatever comment you give it in the commit), type in the following command. You can, of course, modify the commit comment to suit your needs. I find that “First Commit” is pretty universal for the initial time you commit files into a repository:
git commit -m "First Commit"
That’s it – You’ve created your first Git repository, and saved your first version into it! From now on, repeat the above command (with more descriptive comments, of course) every time you’d like to do a commit.
Now, you must be feeling pretty good about yourself right about now. But wait, there’s more! What if you’d like to save this Git repository somewhere else – maybe somewhere where other people can download your glorious code, or collaborate with you? Enter sites like Github or Assembla. Github is the biggest repository on the web these days, and it’s great, except for one (pretty major IMHO) issue – the free option they offer is public only. This means that if you do put your glorious code up there, anyone can see it. Great on open source projects, but not so great on your own, super-secret app that’s-going-to-make-you-a-billionaire code.
On any project I have to collaborate with people, github is awesome, and is what I use. Most people haven’t even heard of assembla, so, easier to collaborate on github, since everyone will have an account up there anyway. On any private project I have, assembla is nice enough to provide me (and you!) with a free, private git account.
Both github and assembla use SSH keys as the way to authenticate you when you send information into or out of them. So, first, you have to find out if you already have an SSH key. You do this by attempting to go the /.ssh directory in Terminal:
If there is no such directory, that means you can start creating a new SSH key. However, if there is an .ssh directory (which would only be there if an SSH key has already been created), I would recommend backing up and removing the existing SSH key, and creating a new one instead (if you do not have an SSH key already, skip this step):
ls # thi command lists all the subdirectories in the current directory config id_rsa id_rsa.pub known_hosts mkdir key_backup # Makes a subdirectory called "key_backup" in the current directory cp id_rsa* key_backup # Copies the id_rsa keypair into key_backup rm id_rsa* # Deletes the id_rsa keypair
now you can start creating your own SSH key:
ssh-keygen -t rsa -C "<em>email@example.com</em>" # Replace "firstname.lastname@example.org" with - you guessed it - your own email.
Hit enter to save the file in the default location and name, and enter a passphrase in the next line.
Enter passphrase (empty for no passphrase): <em>[Type a passphrase]</em> # Enter same passphrase again: <em>[Type passphrase again]</em>
Now, by typing in the next command, you put the newly created SSH key into the clipboard. Once that’s done, you can log into either github or assemble and add the key in there. You must add the SSH key, or they will not agree to connect with your machine.
If you’d like to add your key to github:
1. Go to your Account Settings
2. Click “SSH Keys” in the left sidebar
3. Click “Add SSH key” and paste your key into the “key” field
4. Click “add key”
5. Enter your github password when requested
If you’d like to add your key into assembla:
1.click on your name in the upper right corner, and click on “Edit Profile”
2. Click on “Manage SSH Keys” on the left sidebar
3. Paste in your key from the clipboard
4. click “Add key”
To summerize – at this point, you have a local git repository ready on your machine, and you have github configured and ready to start synchronizing gits. Only one thing left to do – create a repository on github or assembla and start synching it with your local one. I’m going to focus on GitHub here, since that’s what the majority of people use.
I think a quick explanation is required here as to why we’re creating (yet) another repository. The repository you’re created online (be it github or assembla) is initially just another empty “folder”. this “empty folder” must be created up there, since you have to tell github that you’re about to send something its way. So, go ahead – log into github, and on the upper right corner there is a button that looks like this: - this is the “create new repository” button – click it.
Put in your project name, and a quick description, and click “create repository”
Now for the final part of connecting your local git with the online git. To push your existing local repository up to github, make sure you are in the same directory as your local git and type:
git remote add origin https://github.com/YOUR_USERNAME/YOUR_PROJECT_NAME.git git push -u origin master
Make sure to replace your username and project name in the example above. Also, please note the the name “origin” is a generic name – you could have named it anything you like. These are also the commands you would use to send a version up to github every time you do a local commit on your machine.
That’s it! You should have a better understanding of what a Git repository is, how to create and commit files to it locally, and how to clone it into Github!
If you made it all the way through this post, perhaps you’d like to find out how to connect your project inside eclipse with github?