Starting with Git!

Sep 2009

The purpose of this guide or tutorial is to give a brief overview of how to work with Git, even for people who've never had any experience with version controlling. This guide anticipates that you:

  • Have a bit experience with working in the terminal
  • Common sense
I will teach you how to:
  • Set up a Github repository
  • Upload content to your Github repository
  • Work with Git
  • Simple collaboration

A lot of people still believe SVN is much better than Git. However, this is not the case. SVN's way of handling repositories is bad, it means everyone pushes to the same master "repository". In Git everyone has their own, which is a lot smarter. I'm not going to go in depth about the difference, since a lot of people, with much more knowledge about Git and SVN than me, already did that. So you can Google your way to that.

With that in shape, let's get started!

Installing Git

Before starting this guide, you should have Git installed locally. You can download Git here. If you run Linux, there's a good chance that you can install it via your favorite package manager. For Ubuntu's package manager (Aptitude) the terminal command is:

sudo aptitude install git-core

You should most likely be able to type: "git" in the terminal, and it would give you the instructions on how to install it. This guide is not to cover the installation, but to teach the usage of Git. If you have troubles with installing, try to Google your way around!

A sample project at Github

Github

It has a lot of features, including graphs for your project, issue tracker and a wiki for your project.

Before you start on the next step, please register at Github.

Creating your first Repository

Our goal is to make a new repository, and upload a few files to it. Before we can do this though, we need to set up Git, so that Github knows who you are when you push things to their server.

Configuring Git

Configuring Git is very important, I used the first couple of hours with Git having headaches about Github not recognizing me, when I pulled stuff from my repositories at Github. However, it's pretty straight forward to configure.

We need to do two things:

  • Create an SSH-key
  • Provide this SSH-key to Git
  • Introduce ourselves to Git!

There is no reason for me to reinvent the wheel, Github has already done this. First, read their guide about Providing your SSH Key, then go ahead and Tell git your user name and email address.

The dialog to create a new project

Creating the Repository

Creating our own repository is pretty straight forward. Go to Github, login and you'll be at your dashboard. At the right you should see (create a new one). Click it, and it'll take you to the page where you can create your project.

Fill out the fields as you like, I'll call my project "Test". Hit submit. Now you've created your online Git repository!

Here's the new repository I created

You'll be taken to your new project, and you'll notice Github provides you a small guide on how to upload the first files to your project! Again, let's just follow Github's guide once again.

The first step is the Global setup step, we don't need to do this though, but because you followed the guides before, this is already done! I find it weird though, it doesn't tell you to provide your SSH key. Ignore this step.

However, we can follow the next steps:

Fire up a terminal, and type (replace Test with the name of the name of the repository you created on Github):

 mkdir Test

Afterwards, navigate into this new directory by typing:

 cd Test

Instance Git inside this directory by typing:

 git init

Create a new file by typing:

 touch README

Add this file to the repository by typing:

 git add README

Now, let's make a change to this file, by writing something to it:

 echo "Hello, is this on Github?!" > README

Now, we need to commit. Committing is a small message of what you just did (we'll cover more about that later):

 git commit -m 'Initial upload'
README file on Github

Next, we need to add the online Github repository (the origin), this is done by adding a remote origin (notice that you'll need to change "Sirupsen" and "Test" to reflect your own user, and repository):

 git remote add origin git@github.com:Sirupsen/Test.git
And finally, let's push it to Github.
 git push origin master

(This means we push the commits to the origin (master repository), at the master branch)

Now, go to your Github repository and you should notice a file named "README", if you open it you should see whatever you echoed into that file.

Now you've added your first file to Github! Continue to learn more about how to work with Git.

Working with Git

Now you know how to do the most basic stuff with Git, and Github:

  • Creating a local folder to represent your Git repository
  • Committing changes to a file
  • Update this on the server

With this, you can do the most basic stuff with Git. Now I will introduce you to some of the more exciting features of Git.

Pulling changes from the origin

Click Edit to edit the file

But, what if I change something online. And would like to apply these updates on my local copy of the repository? That's what we're going to do now. First, let's go to our Github repository. Click on the file you'd like to edit (you'll probably only have your README file currently). When your viewing the file, you can chose edit to edit it.

Now you can edit your file. Make a few changes - create a small commit message, then hit commit.

Editing a file on Github

Now, when you've added some stuff to your README file, it's time to pull the changes to your local repository. Open up the terminal where you arranged yourself into the Test directory, and pull from the origin:

 git pull origin master

Try to open the README file again, and you should see the changes you made on Github! Another way to check the output is by writing:

 cat -A README

Which will output the contents of the file directly in the terminal.

Cloning a repository

Instead of making a directory, adding the origin, and pulling, each time youneed a copy of your repository. You can simply use the clone command, which clones the repository to your machine. Let's try it. First, delete your local copy of the repository.

Github repository informations

Next, go to your Github repository, and on the top locate your private clone URL (see picture to the right). Copy it, and go to your terminal and type (replace my URL, with your own private clone URL):

 git clone git@github.com:Sirupsen/Test.git

And then you should have a fresh copy of your repository!

Deleting files from your repository

Sometimes you may need to delete files permanently from your Git repository. The command for this is almost the same as the basic delete command ("rm"), we just need to have git in front of it. This command will both remove the file form your harddrive, as well as remove it from the git repository.

For instance, I've added a file called "INSTALL". But I ended up just adding this text to the README file. I already added the content of the INSTALL file to the README file, and committed these changes - but now I want to delete the INSTALL file, as it serves no purpose anymore.

To delete the file, we type:

 git rm INSTALL

And then we need to commit the changes:

 git commit -m 'Removed INSTALL file, due to content having been appended to the README file'

Finally, push it to Github:

 git push origin master

Simple, right?

The Difference

At some point you might have just cleaned up a few files, and totally forgot about commiting. Its ok if you don't even remember which files you edited. To find the difference from the Github repository, and your local copy simply type:

 git diff

And it'll show what is different. As it might be a bit pain to add each individual file like this:

 git add file1 file2 file3 file4

And then give them a shared commit, there's an easier way:

 git commit -a -m 'Cleaned up files'

This takes all the files which are different from the main repository (Github), and gives them the commit entered after -m. This is also good when you are editing a single file, because instead of:

 git add file
 git commit -m 'Added function to calculate average'
You can do:
 git commit -a -m 'Added function to calculate average'

It automatically picks up the changed file(s), and then commits them. Cool, right?

Workflow

Now you know all the basic commands of git, and you know how to work with Github. Let's take a quick look at an example of how our workflow could be like now:

I create a file, and call it index.php, I've already added some stuff to it. Now, I want to push it to Github:

 git add index.php
 git commit -m 'Added index file'
You might ask now, why don't we use:
 git commit -a -m 'Added index file'
-a will not add new files to the repository, you'll have to do that with add the first time. Alright, now I've added the file. I make some more changes to the file, and I commit it:
 git commit -a -m 'Added a menu'
Now I think it's good enough, to be pushed to Github:
 git push origin master
These 3 commands are by far the ones which you are going to use the most.
  • Commit
  • Add
  • Push

As I said before, it's very important that you commit every time you can rinse up what you've done in one sentence. Commit messages must be short, and precise. You should maybe use some time on your first commits, but over time you should learn creating small informative and useful commits. That's all for now, we might come around collaboration in Git in a later post. The best way to learn is always trying out, and if you don't know how to do something, use Google!

For further reading go to Git's official website, and read the documentation. Github also has several amazing articles on Git!