Personal tools
You are here: Home Writing My HOWTO Zone Using CVS w/SSH to Manage Your Code

Using CVS w/SSH to Manage Your Code

This document is aimed at individual users who want to do version control. This might be valuable to you, say, if you are in a course where you have a lot of programming to do and want to avoid losing your work!

Originally a homework assignment in my Object-Oriented Programming course, I am evolving it into a general-purpose tutorial on getting a project under CVS control. CVS is useful both for both individual and small to medium-size team projects.

In this description, we will approach this from the standpoint of an individual who wishes to maintain a repository for his/her own source code. A separate tutorial will appear shortly for small groups. The reason for this distinction is that the latter requires administration, while the former can be done by users not having administrative privileges.

Create a CVS Repository

The very first thing you should do is to create a CVS repository. CVS (Concurrent Versioning System) is used to do version control. Most certainly, you know something about software versioning, since you see version numbers (even today) in just about every major software product/project.

Version control seems to receive very little attention in the computing curriculum, and for good reason: It takes class time to actually cover this topic. In a course that emphasizes the balance between programming, tools, and techniques, it is a small price to pay.

In the CVS software, a repository is nothing more than a directory that contains two things: metadata and version files. The most important thing to focus on now is the latter, which is where every project and its source files will be placed. We'll go into some detail in lectures about what is actually happening behind the scenes. In this document, our focus is on introducing only the essentials and taking an immersive approach. (i.e., the Jordan philosophy-Just do it!)

We will be doing this on newabel. The only reason we are using newabel at this time is because it is a remote system that is connected to the Internet. Therefore, you'd be able to get to it at just about any time. You must log into your newabel account at this time, using the SSH utility. If you have installed Cygwin, you can open up a bash shell and type:

ssh gkt@cvs-host.domain.com

It is essential that you replace gkt with your own username.

Once you are logged in, you will see the infamous Unix shell prompt. Do not be intimated! All great things begin here. The Unix shell prompt, unlike the DOS prompt, is a robust programming language in itself. But in its most basic form, you simply tell the system what to do by issuing commands. This is what you will be doing for the most part in all interactions with the shell throughout the semester.

Creating a CVS repository is straightforward. You simply need to pick a directory and then make sure that you know where the directory is located. We will be naming the repository MyRepository; however, you are free to choose any name desired. I suggest naming the directory clearly with CVS at the beginnning so you know that it is something important and never to be deleted.

cvs -d $HOME/MyRepository init

This command creates a directory, relative to your home directory, named MyRepository. $HOME is a variable that the shell sets to your home directory's location in the filesystem. On newabel, for me, this directory is /home/gkt. You can find out what it is for you as follows:

echo $HOME

If all has gone well, you now have a CVS repository named MyRepository sitting in your home directory. To verify this, make sure you are still in your home directory and list the contents:

cd
ls -ld MyRepository

If all has gone well, you'll at least see the following:

gkt@newabel(11)$ ls -ld MyRepository 
drwxrwxr-x 3 gkt 512 Sep 1 18:05 MyRepository/

Download Sample C++ Program, Unpack, and Import into CVS

Once you have the repository established, the fun is just beginning. It is now time to download the sample project, which we are going to import into the repository.

You might as well get used to it. I speak Unix. We're going to use the web from the command line to fetch a file. This is much easier than first fetching it to your computer using Internet Explorer, hunting it down, and subsequently having to upload it to your account on cvs-host.domain.com.

wget http://cluster.cs.luc.edu/~gkt/Code/Lectures/272/DemoProject.tar.gz

In general, I distribute code using the open format .tar.gz, which means that the file has been compressed (the .gz) and tarred (.tar). The combination of .tar and .gz is similar to .zip, except that each of the operations occurs separately. (First an archive is created using the tar command. The resultant file is then compressed using gzip.)

In general, when unpacking a .tar.gz file, you want to see the contents before doing so. The following command is required on newabel, because it is running very old a very old version of the tar command. Just do it:

gunzip -c DemoProject.tar.gz | tar -tf -

If you look carefully, you'll notice that when this file is unpacked, everything will be unpacked into a subdirectory called DemoProject. This is the correct way to package source code: Always make sure that the content would be unpacked into a subdirectory.

To actually unpack the code, do the following:

gunzip -c DemoProject.tar.gz | tar -xf -

The most notable change in this command is to change the t to an x. This means that the files are to be extracted.

Place the DemoProject under CVS Control

At this point you have downloaded the demo project, unpacked it, and have done nothing else. Even though you were tempted to type the word make, you held back. We're now ready to put this sample project under CVS control. This will only work if you completed the first section successfully.

Make sure you are in the top-level of the DemoProject subdirectory.

cd DemoProject

You should only see the files Makefile, Point.h, Point.cc, and test1.cc present. If any other files are present, please delete them at this time. (You can use the Unix rm command.) If everything is ok, type the following:

cvs -d $HOME/MyRepository import -m "First Import" source/program0 YourUsername start

Here, YourUsername should be your actual username on newabel. I'd be using gkt here. The word start can actually be anything your heart desires. Customarily, this word is used as a tag, in case you ever need to retrieve the code that you originally placed under CVS control. We will not cover this issue immediately but you will hear more about it in the near future. The code will actually be stored in a different directory structure in the repository (under source/program0). In lectures, you will see how to add new directories and files to the repository, which will be essential for managing your class projects.

If all goes well, you should see something like the following:

$ cvs -d$HOME/MyRepository import -m "Placed Demo Under CVS" DemoProject gkt start
N DemoProject/Makefile
N DemoProject/Point.cc
N DemoProject/Point.h
N DemoProject/test1.cc

No conflicts created by this import

Anything else is probably a sign that you didn't follow the instructions. You'll probably want to restart from the beginning and delete the repository that you created in step 1.

Once the code is under version control, you can safely go back to your home directory. In case you have forgotten, the cd command with no arguments is used to go home (so to speak).

Congratulations! You are still living. Better yet, your code is under CVS control, so you now have a way of maintaining it and keeping track of all the work you have done. It may well save you when you least expect it.

Remote Repository Access

Everything we have done here thus far presumes that you are maintaining the CVS repository on the same system you are using for development. This can work quite well but might not be what you want in today's Internet-enabled world.

Most people today prefer to develop on their own computers, usually a home PC or (better yet) a laptop. This type of setup is entirely possible with CVS. All you need to do to take advantage of it is to use SSH as a tunnelling mechanism to access your remote account. You should read this document now and then return here for the rest of the story.

  1. Make sure you can SSH into the system cleanly.
  2. Check whether the cvs command can be executed.
  3. Make changes to PATH and/or .ssh2/environment (if you are running the SSH Communications shell)
  4. set CVS_RSH=<path-to-ssh-bin-dir>/ssh
  5. set CVSROOT=:ext:user@cvs-host.domain.com:/home/gkt/MyRepository
These are some lingering things from the homework assignment. Will expand into sections.
  1. Perform an actual checkout using cvs checkout. You will be checking out source/program0. After doing so, you should change directory to source/program0 and verify that the files are there.
  2. Modify the Point class (which means modifying Point.h and Point.cc) to support a new method double distanceTo(Point& another) that will return the distance between two points. You might find it convenient to use the built in C function sqrt() function to do the actual computation.
  3. Run the make command (just type make) to build the test program (test1.cc). If all goes well, you'll receive no errors and be able to run the test1 executable. If you get errors, it will be necessary to work to fix them. You should be able to write the code for this simple function, since the syntax for C++ arithmetic is nearly identical to Java (which came from C++, so this is no coincidence).
  4. Run cvs diff to determine the differences between the code currently in the repository and your changes. You should notice that Point.h and Point.cc have both changed.
  5. Use cvs status to get a report of what files have changed. What do you notice in the report? Is there anything not in the repository that should be?
  6. Use cvs commit to establish your changes in your CVS repository.
  7. Use cvs status to get a report of what files have changed. What do you notice in the report? Is there anything not in the repository that should be?

SSH Clients (Perhaps Konstantin could write-up OS X section)

Document Actions