Simple Git HOWTO

What is Git?

To quote from Wikipedia:

Git is a distributed revision control system with an emphasis on speed. Git was initially designed and developed by Linus Torvalds for Linux kernel development. Every Git working directory is a full—fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Git's current software maintenance is overseen by Junio Hamano. Git is free software distributed under the terms of the GNU General Public License version 2.

So, now I'll break that down a bit into more digestable terms. Git is a system that allows you to store files and the revision history for them. There are many other different revision control systems out there, including (in order of age) RCS, CVS, Subversion, and Mercurial. Of these, the first three are what are called centralized revision control systems. They rely on a centralized server for dealing with the revision control aspects. You cannot persist a change to a file in a Subversion repository without access to the central server hosting the revision control system. Git and Mercurial are different in that they are distributed revision control systems. In both of these systems, each copy of the repository is able to act on its own and is able to support maintaining the revision history of the files. They both also support pushing repositories to another machine to allow you to maintain a "server" of sorts.

Git was essentially designed to host the Linux kernel source code itself, so it makes sense that we would be using it for this class, right? Most of this document will focus on the use of Git for this course, but if you want to learn more about the history and ins and outs of git, you should check out the following links (I highly recommend at least looking over the first two):

If you want to use Git on your machine (which is strongly recommended so that you can easily take advantage of its revision tracking capabilities), you will need to install it on your machine. You can get Git from the first link up above for Mac OS X or Windows, or from your package manager on most distributions of Linux.

Using Git for CMSC 421

You will be using Git in this course to turn in assignments. There are a few essential operations that you will need to know in order to actually get things turned in, and that's what I'll cover in the rest of this document. Here is a list of the operations that you'll be using for the class:

Cloning a remote repository
Adding files and Committing changes to a local repository
Pushing changes to a remote repository

You'll essentially have to do the first of these once, whereas the others you will be using a lot more extensively. Other operations that you may find useful are covered in the Git Community Book.

Once you have Git installed, you'll have a little bit of initial setup to do to make sure everything works as expected. Specifically, you should set up the name and email variables for Git. If you have previously used and set up Git, then there is no reason for you to change them, but if you haven't used Git before, please set them up now, as follows (filling in Firstname, Lastname, and glusername as appropriate):

git config --global user.name "Firstname Lastname"
git config --global user.email "glusername@umbc.edu"

You should also set up your default editor for your terminal. The instructions for doing this will depend on what you are using for your terminal, but on BASH, you should edit your ~/.bash_profile file and set the EDITOR environment variable. I suggest using nano (since its simple), but you can set it to any editor that you have on your machine. Add the following line to your ~/.bash_profile to set the editor to nano (change nano to the editor of your choice, if you don't like nano):

export EDITOR="nano"

If you are using Git on Windows, it comes with both a GUI and a terminal interface. I will not cover using the GUI tool in this document. Also, the terminal interface that Git for Windows comes with seems to include vi as its editor. If you want to use another editor with it, you're on your own there.

Cloning a remote repository

We have set up a central repository for each student on the GL server. This central repository is how you will actually turn in assignments. Once you've pushed a revision set up to the server (which will be covered later), you can consider that to be "turned in" for grading. You can push as many revision sets up to the server as you want, as we'll be taking a look at the latest of the revision sets when we grade assignments.

Since we have set up the initial repository on the GL server, the first thing you will have to do to actually use it is to clone the repository we have set up for you. You can do that with the following command (filling in both instances of glusername with your GL account username, and of course putting it all on one line in the terminal):

git clone ssh://glusername@linux.gl.umbc.edu/afs/umbc.edu/depts/cmsc/cmsc421/
Spring12/glusername

This will make a copy of the remote repository on your local machine in a subdirectory that matches your GL username. This will be where you will put all of the code/text/whatever for that which you have to turn in in the class.

Adding files and Committing changes to a local repository

The most essential function of a revision control system is to actually track revisions to files. Your repository should have a README.txt file in it already when you check it out. To get the hang of how things work in Git, lets add a new file just to make sure that everything is working. Create a new file in the directory with your repository (lets call it README.2nd) and put in some text, just to test things out. Then, run the following command to add it to your local repository's revision tracking:

git add README.2nd

On success, git won't print anything to the terminal in response.

Once you've added the file, it is still not actually committed as a change. You must run the following command to actually persist that change to the local repository:

git commit

When you do this, your editor should open with a file to let you describe the commit. Give it a short description, save the file, and exit the editor. Once you do that, git should print something similar to this to the terminal:

[master c0b7685] Description goes here.
 1 files changed, 1 insertions(+), 0 deletions(—)
 create mode 100644 README.2nd

Note that the line with "Description goes here" will be different for you, but the rest should pretty much match with what I have there. Once that is done, you have committed your first change to your repository. You can check on it by using the "git status" command, which should print something out similar to the following:

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)

Since committing does not involve the remote repository at all, you can commit to your repository whether you have network access or not. You should commit early and often when working on code, so that you can use the revision tracking to your advantage (for instance, if you break something in your code).

When changing a file, you must explicitly add the changes made to the repository by using "git add" as above, or you can use the shorthand "git commit —a" which will automatically add all changed (but not new) files. New files must always be added manually with "git add".

Pushing changes to a remote repository

Everything in the section above only affected your copy of the repository. You have not changed anything on the GL server as of yet. If you only add and commit, we will never see any of your changes (which would be a very bad thing for your grade). Once you have made changes and wish to push them to the remote repository, you must run the following command:

git push

This will push any changesets that you have committed from your local repository to the remote one on the GL server. That way, we will be able to check out the repository to actually grade your assignments. You can commit and push as many times as you would like. We will look at the latest revision (that is pushed before the project is due) when grading.