Using version control systems

So, you want version control? Smart choice. We support the unix CVS server software and the unix and windows CVS client software in the CS department. Herein, you shall find an explanation of setting up and using CVS on departmental machines. Much of what you read will be applicable to working from clients off of our network as well.

In addition we have some simple instructions for setting up an SVN server if you know you need one and are savvy enough to figure out the client side and debug issues with the server yourself.

To use CVS in the CS department, you *must* have a CS account. We do not support anonymous CVS, pserver, or any other authentication method that is not tied to having a CS account. As stated in our account policies, account sharing is not allowed. If you need to collaborate with someone off site, they will need to be sponsored for a guest account by a faculty member (send mail to udb for more information), or you'll need to come up with an alternative access method such as creating snapshots of your code (or changes) and making them available on the web or via email.

This document specifically does not cover all of the fundamentals of CVS (such as file deletion, or past version recovery) or advanced aspects of CVS such as branching or tagging. You will need to figure out those aspects of the system yourself, or with the help of your instructor or TA. Please refer to the documentation below for more information.

First you'll need to pick a location to store your repository. Please note that your CVS repository, if stored in your home directory, will be subject to your disk quota. You will likely need to host your repository elsewhere per your instructor's direction if you are working with particularly large repositories or binary data such as graphics files. For purposes of this example, we'll use /tmp/cvs, which is not a sensible place to store your repository because it is routinely erased and not backed up. You can replace /tmp/cvs with whatever directory you end up using. We will also call the module (your source code) project1. You can name it whatever you like, of course, or have more than one within your repository.

You can set up a repository manually on the unix side, or more automagically from MS windows.

Unix repository creation

These commands can be run on any CS unix host.

  1. make your cvsroot directory: mkdir /tmp/cvs
  2. make the directories that cvs requires, and a directory for your module: mkdir /tmp/cvs/CVSROOT /tmp/cvs/project1
  3. initialize the repository: cd /tmp/cvs ; cvs init

Your repository is now ready to use from any CVS client--windows or linux. see Working with groups below if you need to share access to your repository securely with other users.

MS Windows repository creation

This document explains the usage of the the Tortoise CVS software in the UTCS environment. It is specifically tailored to the department installation of TortoiseCVS interfacing with our UNIX system setup. We do not provide support for other configurations, although you may find success in using Tortoise against a different CVS server, or even a subversion server. Please do not ask us for help with such configurations, though.

Please do the following steps in the order specified to create and use your CVS repository. To get started you will need to create a new module. There are two steps to this process:

  1. Log into a CS UNIX machine and navigate to the directory in which you wish to store your project. Within that directory, make a subdirectory called CVSROOT. It must be fully capitalized.
  2. Log in to a machine in the microlab and create a folder to work in. Open the folder in windows explorer and right click in the empty folder window, and choose "CVS->Make New Module" and then fill the following values into the settings fields:
    • CVSROOT: (will be filled in as you fill out the other fields)
    • Protocol: Secure shell (:ext:)
    • Protocol parameters: (leave blank)
    • Server: (any public CS UNIX machine)
    • Port: (leave blank)
    • Repository Folder: The same directory you made a CVSROOT directory in in step 1. (/tmp/cvs in our examples.) note that this directory name should NOT include the CVSROOT portion of the path.
    • User name: The CS UNIX login of the person who made the CVSROOT folder (during creation, one person should do all of the steps listed here. later we will add others to the access list.)
    • Module: Whatever you wish to call your project. This name should be only one word (no spaces or metacharacters), for example project1. You should not use the Fetch List  button as there are no modules created yet.

Finally click OK and enter the password for your CS UNIX account. Your module has now been created and is ready to begin populating!

Sharing your CVS repository with other users

All of the above instructions have assumed a single-user repository. However, creating a multi-user repository is not hard. First you must send mail to udb@cs.utexas.edu from your CS email address requesting that a new UNIX group be made. Please include a list of the CS UNIX login names of everyone in the group (including yourself!), the course # that you are working on (for example CS 101), and someone will reply with a group name for you. This will take up to 24 hours to create!

So you will need to be sure to do this in advance of your need to collaborate. Note that the person who creates the repository can use it instantly, but that other users will not necessarily be able to check out and will definitely not be able to check in any files until this is completed. Once you have a group name, login to a CS UNIX machine, and change to your repository directory (this is the one containing the CVSROOT, called /tmp/cvs in our examples). Execute the following commands, replacing yourgroup with the actual group name that you received in response to your request.

chgrp -R yourgroup .
chmod -R g+rwxs .

Using TortoiseCVS as a client from MS Windows

To use your CVS repository, you must first check out your module, even if it is still empty. unless you have already used it in the current session (for example you just created the module, or already checked something out successfully), you will need to reenter the settings as specified above. To initiate a check out, simply right click in a folder (or on the desktop) and choose CVS checkout. You may need to refill the values as above. Once you have checked out your module, you can edit files, add files, and don't forget to commit once you wish to add new versions to the repository.

Unix client usage

To perform most operations with the unix clients, you'll want to set the $CVSROOT environment variable to the path of your CVS repository,

for example:

  • bash: export CVSROOT=/tmp/cvs
  • tcsh: setenv CVSROOT /tmp/cvs

The equivalent setting of the CVSROOT environment variable value for remote unix clients using a CS login is:

username@hostname:/path/to/repository for example, fool@emos.cs.utexas.edu:/tmp/cvs

You'll also want to set the environment variable $CVS_RSH to ssh. Note, you only need to do make these settings if you are working from a non-cs remote host!

To check out files, change to some workspace (somewhere outside of your repository, like /tmp or your home directory) and simply run: cvs co project1

To import an existing directory (with files) into the repository:

  • Go to the directory that contains any directories/files that you want to import into CVS. This should be a subdirectory containing only the files or directories you want to ch eck in. Do not do this from your home directory, unless you want to import your mailbox and your mozilla profile, and...and anyway it's a bad idea.
  • run cvs import -m 'Initial checkin' project1 VENDOR_TAG RELEASE_TAG This will import (recursively) any directories/files in the current directory into the project1 repository. VENDOR_TAG and RELEASE_TAG can be anything you like, but typically release flag indicates the version of the code you are working with, with underscores (_) instead of periods (.) Also don't forget to replace project1 with the real name of your module!

Otherwise, files can be added to the repository via:

  • cvs add file_name
  • cvs commit

SVN server setup unix

  1. Ask udb to make you a member of group svn.
  2. Once a member, make yourself a repository:
    $ umask 2 # so everything is group writeable by "svn"
    $ mkdir /u/svn/repos/username
    $ svnadmin create /u/svn/repos/username You'll need to replace "username" in the above commands with your username.
  3. Create passwords for yourself and other users you wish to share it with.
    $ cd /u/svn/etc/
    $ /usr/bin/htpasswd -m ./users username # or whoever you want to add
  4. Edit the SVN access file to create your access list. This is a shared file. Please do NOT change other folks' access lists!
    $ cd /u/svn/etc
    $ vi access
  5. Import your stuff (assumed in directory ".") 
    $ umask 2 # so everything is group writeable by "svn" 
    $ svn import . https://zweb.cs.utexas.edu/svn/username
  6. If you receive an error when importing stating that the database is read-only, you need to check the group write permissions on your files. Use the following command to find which of your files need group write enabled:
    $ find /u/svn/repos/username ! -perm /g+w

The following links were used as reference materials in the creation of this document: