How to use CVS

We first cover cvs on cochise, then cvs on another Linux machine, and finally Linux on other platforms.

NOTE! If the cvs does not work the way you want it to do, the fault is not necessarily your. There are some troubleshooting tips at the end of this document.

A crash course in 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 recieve 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 filenamn | 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.

Checking out the files when working on cochise (the project's own machine)

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. The reason for this is to ensure that you start out with the most recent version of the files.

Every now and then you should write cvs checkout gt while standing in your home directory (e.g. right after having logged in). Then you will get not only the new versions of files that already are in the directory, but also eventual new files and directories that have been added since last time.

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

cvs update
(to get recent versions of the files that are already there)
cvs up
(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 leas once a day, in order to avoid conflicts arising from other people working on files that do not
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 inestead 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 checkin 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

General manuals

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

There is an O'Reilly book, CVS Pocket Reference, it is the only CVS book, but it is all too short to be really useful.

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

cvs in cochise.uit.no

You need a username in the master cvs server, cochise.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 cochise).

export CVSROOT=/usr/local/cvs/repository

Setting up environment for remote cvs use on a Linux and Mac OSX machine

'remote use' means that you check out the cvs files to a machine different from cochise.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: One on cochise, and one 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 cochise. If you have Linux or Mac OSX this is already in place. You also need a username in the master cvs server, cochise.uit.no, and cvs group membership in cochise, but if you can read this, then that should be in place already. 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@cochise.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@cochise.uit.no:/usr/local/cvs/repository co gt

You are then prompted for your password to cochise. You can leave out your remote (cochise) username if your local username and username in cochise 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 occacion, 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 cochise via scp, and thereafter copy them to the sandbox and do cvs update there).

Using CVS on a Windows machine: WinCVS

[Settin 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 cochise.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 cochise.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 cochise 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_cochise" 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_cochise. 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:       cochise.uit.no
User name:          trond
CVSROOT:            trond@cochise.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 shoudl 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 Dialogs canb 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 machin 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.

Using CVS on a Mac

There are CVS versions for the mac. (References?) But since the Xerox tools do not run on the mac, it is not a good idea to port the project to a mac. (this may change in the future).

Troubles using cvs

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! Pelase 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.

Trond Trosterud
Last modified: Fri Aug 27 09:15:59 2004