SourceControl

1.  Introduction

The projects in the class are big enough (both in absolute size as well as number of people) that you will want to use source control.

For the initial assignments, we will require you to use it, so that you'll learn why you want to use it.

In the real world, a lot of companies use commercial, industrial strength source code control systems. (Perforce, SourceSafe, AlienBrain, ...) However, a lot of projects use the Open Source tools.

Unfortunately, we can only provide you with Open Source tools. Two tools seem to dominate:

• CVS - I recommend the CVS book, especially the first few chapters to get the ideas.
• Subversion (a.k.a. SVN) - I recommend the Subversion book, especially the first chapter or two that give the basic ideas.

While subversion is newer, has some really cool features, and is designed to fix many of CVS's flaws, CVS is sufficient for the kinds of projects you're doing here. It also has the big advantage that the course staff is more familiar with it and (more specifically) how it fits into the CSL environment.

Using a source control system is really easy. After a few days, it will become second nature. The thing that is not easy is figuring out the details of how to make it work in the CSL environment - which requires you to connect source control with secure authentication, networking, a distributed file system, class project structures, and multiple operating systems. This document is designed to help you with that.

Note: I am assuming that you already know the basic concepts of source control (repository, checking out, ...). Also, while this document is specific to CVS, most of it applies to subversion as well.

2.  Basics of Source Control in CS

Your repository (the database of files and versions) will live in AFS (so its secure, backed up, etc...). We'll give you space in the class project partition (ask the TA, and she'll set you up with a repository).

Note: you should (almost) never need to actually look in the repository directly. If you want to work on the files, check out a copy. The main reason you might need to access the repository directory is to set file permissions.

Both CVS and SVN run well on the CS linux machines. For any other machines, we'll actually run CVS or SVN on a CVS linux machine, but we'll connect to them through a secure shell "tunnel" so it will look like your windows or remote linux box is talking directly to the repository.

We recommend a CVS client for Windows called "TortoiseCVS" - its already installed on the CSL Windows machines. It integrates CVS right into Windows Explorer. Your icons are updated to show a file's CVS status, and all the CVS commands are just a right click away. There is an equivalent "TortoiseSVN" that is even cooler (it has fancy file merging features).

To do some work, you set your CVS client (e.g. tortoise) to use your repository. The trick is that rather than just being a file on your local disk, its a long "filename" that says "get to this repository through an ssh tunnel to my account on this other machine". You then check out a copy of your project to the local disk of the machine you're working on, do your work, and then commit the changes back to the repository when you're done.

This may make more sense when we give you the specifics.

3.  Getting a Repository

For CVS (and SVN), the repository is just a directory of special files.

For 679, we will make you directories in the class AFS space. This is a finite space, so don't put too much stuff in your repository. Each project will get its own repository.

Because the repository is just an AFS directory, we will use AFS file permissions for access control. (note: both SVN and CVS have fancier access control mechanisms, we're just not using them).

When you start a project, send email to the TA and she'll make a directory for you and initialize a repository in it. Be sure to tell her who needs to have access to the directory.

Your repository will be a directory path on AFS, like:

If you're curious, the magic incantation that makes this directory is:

But, the TA will do this for you (since only she has permissions and she'll also need to set up file permissions).

4.  Connecting to the repository from Linux

There's one catch with CVS - getting the first "module" (CVS speak for a directory). Once you have the first directory, you can check it out and add to it easily. But without something to check out, ....

To get around this problem, when we set up your repository, we'll put an initial directory and an initial file into that directory. For me, that directory (or module) is called "Proj1".

On a CSL Unix machine, I can go to a place I want to do my work (say /scratch/mike) and check out my module by typing:

And cvs types back:

Some things to note here...

1. I had to tell CVS where the repository was (and in this case, its a directory on the machine I'm using)
2. I used the CVS "check out" (or CO) command
3. CVS told me the files that it was "updating"

5.  Connecting to the repository from Windows

If I'm sitting on a windows machine, there are a few things that will be different:

1. I will use tortoise (with its nice GUI) rather than the CVS command line
2. Even though the repository may be a directory on my local machine, CVS cannot work across windows networked drives. Therefore...
3. Rather than just giving the repository as a directory, I have to give it more detailed instructions to do the CVS operations on a remote Linux box.

The down side to #3 is that the first time I check things out, I need to have a magic incantation. The upside is I only need to do this once (since CVS remembers where the repository is), and it will work from anywhere that I can make a secure shell connection from (not just within CS).

The repository directory will be: :ext:gleicher@best-emperor.cs.wisc.edu:/p/course/cs679-gleicher/2007/cvs/mike1

Let me explain each of the pieces (since you'll need to change them to fit your needs):

• :ext: - means that we'll access the repository from an external connection (note: use "ext" not "ssh")
• gleicher@best-emperor.cs.wisc.edu - I need to give it my account name (gleicher) and a CS linux box (best-emperor) that it will log into to access the repository
• /p/course/cs679-gleicher/2007/cvs/mike1 - is the repository dirctory on the linux machine (just as in the previous section)

TortoiseCVS will actually construct this string for you from a series of questions in its dialog box. (that's actually how I got it right).

To check out a module using Tortoise: right click in the directory where you want the module to be checked out to. You'll see an option on the context menu "CVS Checkout" that will bring up Tortoise's dialog box.

Note: in this example, the "Module" is "Proj1", the "Repository folder" is "/p/course/cs679-gleicher/2007/cvs/mike1", the protocol is "ext", and the other things you should be able to figure out.

If this works, you'll see a folder in your directory (Proj1) that has a little check mark in it (to let you know that CVS has it under its control).

A warning: in doing the checkout, CVS will need to make a secure connection to the linux server. It will ask for your password, and may ask you if its OK to connect to a computer whose key signature its never seen before. Also, in doing what you think is a single operation, CVS might need to make multiple server connections, so it might ask for your password many times.

Note: for subversion, there's a similar scheme. Your repository will be something like svn+ssh://gleicher@gargamel.cs.wisc.edu/... But I have had some problems getting it to work reliably.

6.  Using CVS

That's actually all of the CS specific stuff. Everything else is just like normal CVS.

Some of the basics:

• you'll want to have your project in the checkout directory (so move things there initially)
• you "add" the files that you want CVS to keep track of. beware: adding a file only tells CVS "please keep track of this file" - CVS doesn't actually do anything to the repository until you commit
• you commit your changes

All of the CVS commands you need are available on the Tortoise right-click menu.

For reasons you don't want to know about, CVS needs to know if your file is an ASCII text file (like code) or binary (like an JPG image). Usually, it will guess when you add the file. But you should check to make sure it guesses correctly.

Please only put files into CVS that you really care about and that would take effort to recreate. So, put your visual studio project and solution files in, but not the debugger information files. Put your source code in, but not the generated object files or executables. Otherwise, CVS will be keeping many copies of your big binary files, and that will fill up our AFS space fast.

7.  Getting started

Please try all of this out and get it to work BEFORE you need it for really tracking your important files. It takes a little bit to set up and get used to, But once things are set up and working (and we'll help you with that), it really is very easy and takes little effort.