Lab 3: Distributed Version Control Systems

CMSC 240
Due: Monday, Nov. 4th by 11:59:59pm

One of the ways programmers collaborate is by sharing code. While it's not too difficult to
share code with one or two other programmers, sharing code with large groups of people can
be quite difficult. The reason for this is that if two different programmers make changes to a
file, two new versions of the file exist. If a third programmer wants to make a change to the
program, he has to choose which version to modify – or he has to merge together the two
versions to make a THIRD version which he can modify.

Obviously, this can be a very complicated and challenging process. Fortunately, there is very
good software for managing and sharing source code that helps alleviate this problem. These
software tools are called "version control systems".

The first widely used VCS was called "CVS" (concurrent versioning system) and it kept all the
source code on a server. Code could be "checked out" into several working copies. When the
user made a change to the source code, he could "commit" his changes to the server and the
change would be merged back into the code repository. He could obtain the latest changes by
other users by issuing an "update" command that would download all the changes and apply
them to his copy of the code.

CVS was a little clunky and was a little difficult to learn, so several new VCS tools have
become popular. One of them is "subversion" (also known as "svn"). Subversion is a lot like
CVS, but fixes some problems in the user interface that many people found annoying and
improves performance.

More recently, distributed version control systems like "git" have become popular. DVCS
systems don't have a central server. Instead, each user's computer acts as its own server and
manages a local repository. When a user makes a change, other users can obtain that
change by requesting it from that user's server. This system has a lot of advantages,
especially for open source software where having a central server makes it harder to ensure
that the code remains open and free to everyone. If you want to use a central server
(perhaps for access control), you can still do that with git, but you now have the option not to
lock yourself into that development model.

Step 1. Setting Up

Make a folder named Lab3.

Step 2. Cloning a Git repository

Git was developed by Linus Torvalds, the author of the Linux kernel. I've created a small
software project named “Simulator” that simulates traffic patterns. I've placed my code in a git
repository which you can clone. Type “cd Lab3” to go into your Lab3 folder, then type:

git clone [email protected]:Simulation

This should make a new folder named “Simulation” inside your Lab3 folder. Use “cd” to enter
it now.

To see the history of changes I made to the file, type:

git log

You should see a series of commits (starting with “Fix initialization bug” and ending with
“Initial Commit”) that give the history of the project. Now type:

git status

This should show you the current state of the project files. Files that haven't changed since
the last commit won't show up in the list.

Step 3. Configuration

Before we can contribute our own changes, we need to set some variables on our git
repository. In particular, we need to set a name and e-mail address to use in the git history.
There are also some configuration settings we should apply.

Type:
git config --global user.name ”YOUR NAME HERE”
git config --global user.email ”[email protected]”
git config --global pull.rebase false
git config --global push.default current

Change YOUR NAME HERE to your first and last name. Change
[email protected] to your actual Longwood e-mail address.

The pull.rebase configuration tells git to use “merge” to integrate changes into the repository
instead of the “rebase” algorithm.

The push.default configuration makes it slightly easier to send new branches to a server. We
can just use the “git push” command instead of requiring a separate step to create them.

We also need to set a default editor for commit messages. Type:

export VISUAL=$(which vim)

export EDITOR=$(which vim)

Note: You may want to add these last two commands to your .bashrc file so that they persist.
Otherwise, you’ll have to type them every time you log in to work on the lab.

Step 4. Adding Files

When we’ve changed or created a file, we can add our changes to the git repository. To do
this, we have to follow a two step process. First, we use the “git add” command to put the
files we’ve changed into the INDEX. The we use the “git commit” command to store changes
to those files into the repository.

Create a file named “README.txt” that has your full name and the date in it.

Then type:
git add README.txt
git commit

When prompted for a log message, type "Documented my Participation", then save and quit
the editor.

Step 5. Debugging

The files I gave you have a trivial syntax error. If you try to compile (by typing 'make' and
hitting enter), the program will break. Let's use git tools to figure out when the bug was
introduced and how.

Let's start by making a new branch to work in. That way, any changes we make can be easily
undone.
Type:

git branch bugfix

git checkout bugfix

This creates a new “branch” of the commit tree and then checks it out. To go back to the
master branch, you can type “git checkout master” (but don't do this now).

Now that we're in the bugfix branch, let's see if we can figure out WHICH commit caused the
problem.

The best way to do this is to use git bisect. To use git bisect, we need to know a bad commit
(the current or HEAD commit is bad) and a good commit (the initial commit is good).

Type:

git bisect start HEAD 6ab1b

The 6ab1b code is a portion of the hash for the Initial commit.

This starts the “binary search process”. git will 'rewind' your repository to a commit
somewhere between the one you marked bad and the one you marked good.

Type “make”. The compile should succeed, so the bug was introduced AFTER the current
commit (probably commit fa7ed104....)
Let's mark this commit 'good'. Type:
git bisect good

Git now bisects the history again giving you a new commit. Test this commit again and mark
it either “good” or “bad” depending on whether make fails. Continue until git bisect finishes.

You should now see a message that tells you which commit introduced the problem and
which (two) files were changed in that commit.

In order to fix the problem, we must first reset our state so that we are working on the HEAD
commit of the bugfix branch:

git bisect reset

git checkout bugfix

This resets the state to where we were initially. We are now ready to fix the problem.

We can see which lines were changed using “git blame”.

Type “git blame source.cpp” and hit enter. Notice that most of the lines were changed in
commit 6ab1b35, but ONE line was changed in commit aba86d5a. That's the commit that
introduced the bug. The problem should now be obvious.

Step 6. Making Changes to your files

When you make a change to a file, you should create a new "commit" in git. To do this, you
type:
git add <filename>

and then type “git commit”.

Fix the syntax error in source.cpp, test your change, then add the changed file to the git
repository and commit. Because you added this change to the “bugfix” branch it doesn't yet
show up in master.

Type:
git checkout master

and then type:

git merge bugfix

Git should automatically pull in your changes.

Step 7. Undoing a commit

If you mess something up, you can easily go back using the "git reset" command. Modify the
car.cpp by deleting the "Car::move()" function. Then type:

git reset --hard HEAD

to undo your change. This works because you haven't committed yet. If you had already
committed first, you could do:

git reset --hard HEAD^

The ^ symbol subtracts one revision from the HEAD commit. You can tack on several ^’s to
go back multiple revisions.

Step 8. Tagging a commit

A tag is a label we attach to a particular commit to make it easy to access. This is useful
when releasing a new version of a project or identifying a particular bug fix.

Let’s attach a “version 1” tag to the current state:

git tag v1

If you now type “git log”, you should see that the current commit has an additional string
identifying it as “v1”.

You can type:

git show v1

Step 9. Listing your commits

You can obtain a list of the recent commits by typing "git log". Run this command now and
pipe the result to a file:

git log > myproject.log

Step 10. Glitter

Extend the traffic simulation project in an interesting way. Use git to track your changes as
you go. Introduce at least five significant changes as separate commits. I won't be grading
your code – I will be grading your “git log” – but I do want your changes to be significant
(changes to more than a few lines of code) even if these are just comments.

Submitting

Make a tarball of your code by typing:

cd ..
tar czvpf Lab3.tar.gz Simulation

and then log into http://marmorstein.org/~robert/submit/ to turn upload it to my server. Please

do not put the entire Lab3 folder into the tarball – just the Simulation folder.