How to use CVS

What is it?

CVS, or Concurrent Version System, is a program that keeps track of different versions of the same files. This is done by keeping an original of the files in a different place. Thereafter each user must check out a copy of the original, and work on that copy. After the work is done,the new version of the file must be checked in to the repository again. Thereafter, all workers will receive the new and updated version of the file when they check it out.

How do I use it?

Be sure to always have the latest version of the project files, by giving the command cvs update (or cvs up) whenever you log in. When you have worked on a file, check in the file 'filename' with the following command:

cvs ci -m "Write a short log command here" filename

If you want to write a longer log command, write

cvs ci filename

and you will get an emacs window where you can write your command. When you are done, write C-x-c as you always do in emacs, and the log command will be saved.

How often do I check in?

Always check in the files at the end of the day. If you know that other people are working on the same file, you should check in more often than that. You should also check in after you have done major revisions. Remember to compile the program before you check in, so that you know you do not check in a defect file.

What do I write in the log message

The best way to learn to write good log messages is to read other log messages. Pick a file (e.g. twol-sme.txt, sme-lex.fst), and read the log (the command is cvs log filename | less). If the log message tells you what you want to know, then it is a good log message.

That was the crash course, here come some more details.

The first session you get yourself a version of the project, with the command cvs checkout gt. All subsequent sessions you should go to the gt directory (in your home directory, write "cd gt"), and start the session by the command cvs update -dP. The reason for this is to ensure that you start out with the most recent version of the files and folders.

The most important cvs commands are found below, with comments in parentheses after each command.

cvs update -dP

(to get recent versions of the files that are already there, and new folders and files that have been added.)

cvs up -dP

(short version of the same command)

Then work hard on e.g. the file called file.txt. Save the file you worked on. Then the file must be checked in (by "cvs commit") to make it available to the other workers. Check in at least once a day, in order to avoid conflicts arising from other people working on files that do not (yet) contain your updates.

cvs commit filename

(to make the file available to all other workers)

cvs ci filename

(a short version of the same command)

Then cvs asks you to write a log comment. Do that. Then write 'ctrl x ctrl c' (i.e., quit emacs). cvs ci -m "short log comment" filename if all you want to write is "short log comment".

There is an alternative way of checking in files. If you have worked on the file in emacs (as we do in this project), you may write C-x C-q instead of the normal emacs command C-x C-c. Then you get a buffer asking for a log text. Terminate you log text with C-c C-c, and, voila, the file is checked in in cvs. (This method works for RCS as well).

Other commands:

cvs log filename | less

(to see earlier log comments written to the file filename)

cvs add filename

(to make a new file available to be checked in to the cvs system. After you have used the cvs add command, you must write cvs ci -m "..." filename (where ... is the log message) in order to check in the file)

cvs diff filename

(to see the difference between your local version of a file and the version in the repository; this command works only when there is an M before the file name when you write "cvs up")

cvs diff -r 1.123 filename

(to see the difference between the current version and version number 1.123)

cvs diff -r 1.123 -r 1.124 filename

(to see the difference between version number 1.123 and version number 1.124)

cvs co -r 1.123 filename

If you work on revision 1.125, and suddenly find out everything that was done since 1.123 has been a disastrous dead end, you may go back and check out version 1.123 with this command.

Messages from cvs when you update

• An M before the filename indicates that your own file has been altered, and is not up to date.
  • If you know what changes you have done: Write "cvs ci filename" and make your log comment.
  • If you do not remember what changes you have done: Write "cvs diff filename"
• A U or P before the filename indicates that someone else has altered the file, and that your version has been updated. (If you want to see what has been done, look at the log comment, with "cvs log filename | less")
• A C before the filename indicates a conflict. You should now open the file in your editor (emacs), look at it, and resolve the conflicts. That means that you write the text as you think it shall be, and that you delete all text that was inserted by cvs (<<<<<<<<<<, >>>>>>>>>>>, line numbers, etc.)

The official CVS manual is http://www.cvshome.org/docs/manual/cvs.html, also known as 'the Cederqvist Manual'.

CVS Pocket Reference

You may also write info cvs on the command line, that manual is actually quite ok.

You need a username in the master cvs server, victorio.uit.no, and cvs group membership. All persons associated with the project do have this. The following line is automatically executed in /etc/profile; only those who do not have bash as shell might need to set it manually (and we all have a bash shell on victorio).

export CVSROOT=/usr/local/cvs/repository

'remote use' means that you check out the cvs files to a machine different from victorio.uit.no. You then work offline on your local machine (at home, or on travel). Then, returning to a place where you are online, you may check in and update your cvs files as normal. In this way, you have two sandboxes (i.e.: you have two copies of the source files): One copy on victorio, and one copy on your own local computer. Note that these two sandboxes are independent of each other.

You need a ssh client in your local computer that can connect to victorio. If you have Linux or Mac OSX this is already in place. You also need a username in the master cvs server, victorio.uit.no, and cvs group membership in victorio. Then you need to set up your local machine. The following lines should be added into your local initialization file (this is the file .profile for bash on Linux, on Mac OSX).

export CVSROOT=:ext:username@victorio.uit.no:/usr/local/cvs/repository

export CVS_SSH=ssh

Another (much more cumbersome) way is to specify the repository attributes on each command line:

Write the following command:

cvs -d :ext:username@victorio.uit.no:/usr/local/cvs/repository co gt

You are then prompted for your password to victorio. You can leave out your remote (victorio) username if your local username and username in victorio are the same.

That is all! Then you run cvs as described above: cvs update to update, etc. You will be prompted for password at every occasion, but otherwise it is the same procedure as for local work (if there are many changes done, it might be easier to first copy all the files to victorio via scp, and thereafter copy them to the sandbox and do cvs update there).

[Setting up CVS on a Windows machine is not easy. Do it only if you have to.]

Intro

Here we assume that you already have an account at victorio.uit.no, and that you are able to use it via putty.exe on your Windows machine, and that you are sitting on your windows machine now.

To be able to use CVS you need 4 different putty programs (cf. below), and you need the program WinCVS (cf. further below). WinCVS can be downloaded from LINK.

Key generation

Go to the putty.exe download page http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. You probably has putty.exe already. If not, download it. Download the programs plink.exe, pageant.exe and puttygen.exe as well. Save them in the same folder as you have putty.exe (e.g. in C:\Program Files\putty\). Then establish a connection to victorio.uit.no, via your putty.exe program (see the instructions on putty.exe if you don't know how). Then open puttygen.exe. Click on the button "Generate", and generate a key (you will need a key). Then do not close this window, but switch to the putty.exe window (i.e. to your victorio account). There you open the file .ssh/authorized_keys (e.g. with emacs). In the puttygen.exe window you see a public key. Copy that to the file .ssh/authorized_keys, and close that file (save changes). Then save the private key, e.g. under the name "identity_victorio" in the same folder as you have the putty programs on your local Windows machine.

Pageant.exe

Then start pageant.exe. It will show up as a small icon down in the lower right corner of your screen. Right click on it, and chose "Add Key". Go to the putty catalogue and choose identity_victorio. Leave pageant.exe active down in the corner (don't click on Exit).

WinCVS

Now, open WinCVS. Under Admin, choose Preferences (Ctrl F1), and the "General" option. Here are the settings (assuming your user name is "trond", exchange it with your own user name):

Authentication:     ssh
Path:               /usr/local/cvs/repository/
Host address:       victorio.uit.no
User name:          trond
CVSROOT:            trond@victorio.uit.no:/usr/local/cvs/repository/

The "Show CVS console (open TTY)W should be ticked.

For the "Settings", do NOT choose RSA public identity file, but DO choose "If ssh is not in the PATH". Underneath, write in the path to the program plink.exe. In my setup, it looks like this: C:\Programfiler\ssh\plink.exe. Do not set any Additional ssh options.

For Globals, do NOT tick the "Checkout read-only" (i.e., deselect that one). All other options should be deselected, except the "Supply control when adding files", "Dirty files support", and the "Checkout text files with the Unix LF". These three should be selected.

For WinCVS, under HOME (passwords and ~/.cvs* files) you set the directory where you plan to have your files (I use D:\Mine dokumenter\Trond\). The other options are deselected. As default viewer I have Notepad, but it may not be the best option.

The Command Dialogues can be left as is, all deselected except the one saying "Shift".

Checkout

We are almost there now. In WinCVS' Create menu, choose Checkout Module. The Checkout settings should have gt as the "Module name and path on the server". The Local folder to checkout to should be the folder on your windows machine where you plan to put your files (e.g. under "My Documents"). For Checkout options, nothing should be set, "Merge options" none, and for "General" and "Globals", you should find the values you already set on the "General" and "Globals" option in the configuration.

Now click OK, and you should receive the gt catalogue on your Windows machine. (To good to be true, of course...)

WinCVS Usage

I have not come that far yet, and I will not do that either, until we get a programmer. Windows users, be patient.

Command line usage

CVS has been built-in to MacOS X since the very first day, and the basic procedures are exactly as described above for Linux outside victorio.

Graphical clients

There are a couple of excellent graphical clients available for MacOS X. The one used in our projects is Concurrent Versions Librarian (CVL). More detailed instructions on how to set-up and check-out from victorio using CVL can be found on another page.

If you have committed a file as 'dead', that is marked it as removed, and commited that change, the file is moved to the attic. Sometimes you may want to bring it back into life again, and to do that you should follow the procedure outlined here (this is taken from the CVS FAQ-O-Matic):

1. Identify the deleted revision of the file, simply performing a 'status' on the file will reveal this (paths shortened for readability):

   a84-230-135-66: sjur$ cvs status ulikestavelsesverb.xml
   ===================================================================
   File: no file ulikestavelsesverb.xml            Status: Up-to-date
   
      Working revision:    No entry for ulikestavelsesverb.xml
      Repository revision: 1.2     /.../gram/sma/Attic/ulikestavelsesverb.xml,v
   

2. We now need to check out the revision prior to being deleted

   a84-230-135-66:~/.../gram/sma sjur$ cvs up -r 1.1 -p ulikestavelsesverb.xml > ulikestavelsesverb.xml
   cvs update: use `cvs add' to create an entry for ulikestavelsesverb.xml
   

3. We can now add the file again, restoring the previous revision:

   a84-230-135-66:~/.../gram/sma sjur$ cvs add ulikestavelsesverb.xml
   cvs add: Re-adding file `ulikestavelsesverb.xml' (in place of dead revision 1.2).
   cvs add: use 'cvs commit' to add this file permanently
   

4. Finally we commit the change:

   a84-230-135-66:~/.../gram/sma sjur$ cvs ci "Resurrected this file from the dead ..."
      cvs commit: Examining .
      Checking in ulikestavelsesverb.xml;
      /.../gram/sma/ulikestavelsesverb.xml,v  <--  deleted_file
      new revision: 1.3; previous revision: 1.2
      done
   

What if you get an error message like the following?

You type cvs co gt, as you have been told. The machine answers:

cvs update: No CVSROOT specified! Please use the '-d' option.

Then answer with the following magic spell:

cvs -d /usr/local/cvs/repository/ co gt

Why you have to do this I do not know.