LMU-CS Version Control Information

Overview

LMU Computer Science undergraduates are strongly encouraged, and in many cases required, to maintain a relatively complete electronic portfolio of all coursework in a revsion control system, such as Subversion (a.k.a. SVN) or Git. Maintaining an electronic portfolio of your work has several important benefits:

You can more easily compose application letters for jobs and graduate schools that require a listing of notable projects completed during school.
The process of turning in certain assignments is simplified, since many professors may prefer to just extract homework from your electronic repository.
Some professors may wish to make corrections or give feedback by writing directly to your repository.
You gain all the advantages of revision control:
- free backups,
- access from any computer with an Internet connection,
- ease of working on collaborative projects,
- the ability to branch, merge, and, especially, revert.
You learn how to manage projects by breaking them up into logical phases (milestones).
You gain valuable industry preparation: revision control systems are routinely used in nearly every business.

There are several places on the web that will host a repository for you. LMU Computer Science students, however, can also take advantage of a private subversion repository provided with their lab account. These notes cover only about 3% of everything you can do with SVN, but at least it is a useful 3%.

Your SVN Repository

Every LMU Computer Science student gets a account which contains, among many other things, a public-facing website, a private database, and a private SVN repository. Over time you will likely build up a repository of all of your work at LMU (that isn't required to be hosted on public sites, which is generally required of senior capstone projects).

/
|__ homework
|   |__ cmsi185
|   |   |__ ...
|   |__ cmsi186
|   |   |__ ...
|   |__ cmsi281
|   |   |__ hw1.tex
|   |   |__ hw2.tex
|   |   |__ hw3.tex
|   |   |__ src
|   |   |   |__ java
|   |   |   |   |__ ...
|   |   |   |__ javascript
|   |   |       |__ ...
|   |__ cmsi282
|   |   |__ ...
|   |__ cmsi284
|   |   |__ src
|   |   |   |__ c
|   |   |       |__ hello.c
|   |   |       |__ ...
|   |   |__ ...
|   |__ cmsi386
|   |   |__ ...
|   .
|   .
|   .
|
|__ projects
    |__ tictactoe
    |   |__ ...
    |__ scrabble
    |   |__ ...
    |__ lolcompiler
        |__ ...

Your private repository is stored in the the directory ~/.svn.

Workflow

The most common SVN tasks are these:

Check out a module from the repository, making a copy of it on your computer's local filesystem. The checked out files constitute your "workspace", or "sandbox".
Create new files and edit or delete files in your workspace.
Inform SVN which of the files in your workspace you want it to track (and sometimes, which ones not to). Also inform SVN when you have deleted a workspace file and want it to remove the copy in the repository.
Commit the changes you made in your workspace, thereby writing those changes to the repository.
Update your workspace with the current contents of the repository. Your workspace gets out of date whenever someone else, or you on another computer, have checked in work.
Always before committing at least, run a diff to see how your workspace differs from the repository.

Committing Your First File

Let's start by making a workspace. Create a directory called homework/cmsi284/hello/c in your home directory. Navigate to it, then create the file hello.c as follows:

#include <stdio.h>
int main() {
    printf("Hello, world\n");
    return 0;
}

Before checking it in, make sure it actually works:

~/workspace/homework/cmsi284/src/c$ gcc hello.c
~/workspace/homework/cmsi284/src/c$ ./a.out
Hello, world

Now let's tell SVN about it:

TODO

At this point you're ready to commit or "check in" your work. Only check in source code (like hello.c); never check in "derived artifacts" (like a.out).

TODO

Making Changes

Now let's do something useful. Make a change to the code, something like changing the text "Hello, world" to "Hola, mundo". Do it now. We don't have to invoke svn add this time; that was already done. But before we commit, let's get into the habit of running a diff.

TODO - svn diff

That looks good, so commit:

TODO - svn commit again

Updates and Diffs

Now you're working with version 2 of the repo, and the repository is at version 2. If someone else — or you, from another computer — checks out this file modifies it and checks in a new version, then the repository will be at verion 3. Your local copy is now out of sync with the repository. If you worked on your out-of-sync file and tried to check in changes, SVN would complain. Before you work, you should do a svn update. If no changes had been made you would see something like this:

Here SVN is telling you that you have an unmanaged file in the workspace that it doesn't know about, which is actually as it should be. If some one had made a change (from another computer most likely), then the repsonse to the update would have been:

~/workspace/cmsi284/src/c$ svn update
TODO

Update frequently when working on teams or from multiple computers.

A Couple More Things

Remember how you had to do svn add to inform CVS that you wanted it to manage a file for you, before you were able to commit? When removing a file, you have to do something similar. Say svn remove filename to disassociate the file, and then later, upon issuing svn commit the file will be removed from the repository.
The update command can be issued from pretty high up in the directory tree; it will update into all subdirectories.
You can do also do a svn commit from pretty high in the tree also to check in multiple files at once. Still, make sure you update and diff before checking in (always a good idea).

Using SVN from within Eclipse

These notes do not tell you how to use the SVN client in Eclipse. Like any tool, Eclipse's SVN client automates some mundane tasks for you and allows you to do complex tasks much faster, at the price of hiding some important functionality that you'll wish you knew the moment the tools fails you or just happens not to be there. Furthermore, if you get a job in a shop that does not use Eclipse, you'll be embarassed to admit your lack of commandline knowledge. Commandline svn is almost always faster. Eclipse pretty much only "helps" with complicated merges.

You must first create a repository location in Eclipse's "SVN Repository Exploring" perspective.
The connection type is svn+ssh, the server is svn.cs.lmu.edu, and your repository location is something like /nfs/svn/alice.
When adding subdirectories and files under a directory already associated with SVN, Eclipse does the svn add command automatically. Yes, this saves you some work, but the flip side is you will have to set things up to manually exclude files from being checked in. (Note how this differs from command line SVN, in which you manually say what to add.)
You do not have to invoke manual svn remove commands, either. Simply deleting a file (from within Eclipse) is enough. When you commit, the file will be removed from the repository.
SVN operations are found under the "Team" menu item. The most common operations are Check Out, Synchronize, Update, and Commit. Before checking in, always go to the Team Synchronizing View and make sure everything is in order. You'll see the files that will be added, the files that will be removed, and will be able to view changed files from a fantastic graphical diff.
You can set up Eclipse to show you when a file has been dirtied. (This is pretty neat.)
While something like Eclipe's SVN client is indispensible for very large projects with complicated branching and merging requirements, it takes some getting used to. Eclipse lets you partition your work in things called projects, which you have to be very careful how you map to SVN modules. Be careful to keep these ideas distinct. You'll probably screw up a lot at first.