CSci 6441.BA2: Database Management Systems

Department of Computer Science
The George Washington University, Spring 2011
CRN 15165

Git Handout

A version control system (VCS) is a tool that takes snapshots of all the code and other files in a project. This is useful for several reasons:

No serious software developer should be working without version control!

Many version control systems use a centralized repository. The repository is a directory, usually on a remote host, where the official copies of the files and all the versioning information is kept. When you want to work on the project, you create a working copy. When you are satisfied with the edits you have made to files in your working copy, you check the changes back in to the central repository.

Currently, one of the most commonly used centralized VCS is Subversion.

There are other means by which a VCS can be organized and a recently popular alternative is a distributed VCS (DVCS). A DVCS maintains the notion of a repository but instead of a project having one, central repository, it will have multiple repositories each with their own history of changes. The different repositories can be synchronized. A discussion of the advantages and disadvantages of distributed versus centralized VCS is beyond the scope of this document.

Git is a particular implementation of DVCS and it is the system we will be using in this class. You can find quite a bit of material on using Git at its website. In addition, you may want to consult the following websites:

Note that I am assuming you are comfortable working from a command line rather than using a GUI. There are GUI front-ends available for Git, but I will not be discussing them. Feel free to explore this on your own if you would prefer to work that way.

Using Github

By now, you have created an account for yourself on Github. There is only one very important thing to remember about Github:

It's just a convenient place to stick a repository.

Now to be honest, there's more to it than that. But all the extra things can be worried about later.

Think about it this way: you have a copy of your work and I have a copy of your work. When you make changes, I would like to see your changes. And when I make changes (e.g. grade your work), you would like to see my changes. How can we make this sharing happen? You will synchronize your repository with the copy on Github and I will do the same thing.

Now there's just one slight complication. Because of this whole pesky thing about grades, it is preferable if the permissions on the Github repositories were locked down so that the only people who can read from/write to the repository are you and I. It is for this reason that I have gone ahead and created a repository for you and you will make a copy of it (this is called cloning a repository). I will describe the commands for doing so below, but first we must discuss accessing Github.

Accessing Github

The username and password you specified while creating your Github account will allow you to log in from the web and manage the account. They are not what you will use to commit your work. You will not upload your files, instead you will use git to synchronize your local repository with the repository in your Github account. In order for git to access your Github account, you must generate a public and private cryptographic key! To do so, visit help.github.com and follow the directions under step 3, Generate a keypair. Be sure to follow the steps in the section titled Testing things out to verify that your key is set up correctly.

If you have problems, I will need more useful information than an email that reads It doesn't work. You are all graduate students and I expect you to be able to send a sufficiently detailed problem report.

Once you can successfully connect to Github you can use the material below to guide you through the process of submitting your work.

Cloning your Repository

The first step, which only needs to be done once, is to clone (copy) your repository from Github to your local machine. Actually, you will need to do this twice because I have created a private repository for your homework and a separate shared repository for you to use with your team for the term project.

To clone a repository, use the following command:

git clone git@github.com:gwu6441-ba2/REPOSITORYNAME.git

where REPOSITORYNAME is either your Github username for your personal repository or project-greekletter for your shared repository (replace greekletter with the appropriate greek letter). So for example, since my username is profburke and I am on team zeta, I can clone my personal repository with

git clone git@github.com:gwu6441-ba2/profburke.git

and I can clone my team repository with

git clone git@github.com:gwu6441-ba2/team-zeta.git

Adding Files to your Local Repository

This is a two-step process and it works the same whether you are adding a new file to your repository or editing an existing file. First, you notify git of the change and then you tell git to record the change in its versioning history. Note you must be working in your repository (i.e. your current directory is the repository directory).

Suppose we are adding (or editing) a file named myfile. The first step is accomplished with

git add myfile

then for the second step, use the command

git commit -m 'some meaningful commit message' myfile

Of course, you should replace some meaningful commit message with some meaningful commit message.

Submitting Changes to Github

With the commands from the previous section, you have recorded your changes in your local repository. Remember, that the whole point of a DVCS like git is that you can have multiple repositories—none of which are any more important than the others. In particular, your changes are not visible in the repository at Github, which means that I cannot see them.

So you need to synchronize your local repository with the one at Github. To do so, use the following command:

git push origin master

Origin is the name of the repository at Github. I have already configured this for you. Master is the name of the branch you are working on. I haven't explained branches, and I won't. If you're curious, read through the documentation for git.

Retrieving Changes from Github

Since the whole point of using Github is for you and I to share files, it is possible that your Github repository has changes that I put there and that are not reflected in your local repository. So to see changes I have made, you need to synchronize Github with your local repository. You do so as follows:

git pull origin master

Normally everything should be fine. It is possible that if two people make changes to the same file, you could get a merge conflict. If so, ask me how to fix it. Or better yet, read through the documentation and puzzle it out on your own.

If Things Go Wrong

I will add to this section as needed. But from using git and Github in previous semesters, I can tell you that the second most common error by orders of magnitude is to have your push rejected because you attempted to do a non-fast-forward update.

You can tell that's what has happened by reading the error message. It will be several lines long, but if you scan through it you will see the words non-fast-forward update. What this means is that somebody else has pushed changes to Github that you have not incorporated into your local repository. So when you try and push your local repository, there is an inconsistency.

The solution is simple. Do a pull and then try re-doing your push.

What is the most common error? Again, by orders of magnitude, it is to either forget to add your changes to the local repository or to forget to commit the changes. Note that for a good summary of how git sees your repository try the following command:

git status

The output does a good job of being self-explanatory, but consult the documentation as necessary.

mmburke@gwu.edu
Modified: Tue Jan 11 14:06:46 EDT 2011