A Stroll with CVS

This page is here to get you using the Project CVS repository. It takes you through obtaining working copies of the CVS repository (s) committing changes to existing files and adding new files. See the links on usingcvs.php for a greater understanding of CVS

Introduction

Had enough of "learning curves", just want to get things happening. Well this may be a good place to start. There are a couple of caveats though. . . I am assuming the following:

Prerequisites: You have CVS installed; You have Open-SSH installed. (or SSH); You know how to use a terminal . ( Xterm , RXVT, Kterminal or Gnome Terminal ); You are a registered 1040 developer. (but you may still use a similar process even if you are not); I drive Linux but this should all be possible from a Mac (OS 9 +), Beos, Windows (95 +) and Certainly any other Unix. (e.g. Free-BSD)

Tasks

These are the more common tasks you might be undertaking :

Installing the Tools _ Preparation for Work _ Get a Working Copy _ Updating Your Copy _ Commit your Changes _ Add some new stuff _

Installing

You need to have CVS and OpenSSH installed. The easiest way to do this is to install the binary packages for your Operating System. The CVS and OpenSSH sites have instructions and you are advised to follow them. If your lucky it can be as easy as "apt-get install cvs "

Get Organized

How you "Get Organized" is of course up to you.

Here is an example that a Project Developer might use. :

Make a directory to keep the Working Copy in:

[/home/you ]$ mkdir 1040WorkingCopy

You need to export (set) some environmental variables before your first 1040 CVS session. You can do this by hand , or have them automatically loaded via your shell resource files or a script that you might run at the start of a session.
Once you have built a Working Copy you should be able to use CVS from within that directory without rewriting your local environmental variables. For now we will do it the "old fashioned" way.

First we tell CVS that we will be using SSH (OpenSSH).

[/home/you ]$ export CVS_RSH=ssh

Then we tell CVS where to find the REPOSITORY. (all one line )

[/home/you ]$ export CVSROOT=Login-Name@cvs.tenforty.sourceforge.net:/cvsroot/tenforty

Obtain Your Working Copy

You need to get a working copy of the Repository before you do anything else. So lets do that.

[/home/you ]$ cd 1040WorkingCopy

[/home/you/1040WorkingCopy ]$ ls

Would just show your dot files . and .. There is nothing in here yet.

To check out the TENFORTY source code we would do this:

[/home/you/1040WorkingCopy ]$ cvs checkout TENFORTY

You enter your password and all being well CVS will build your Working Copy right where we are under the 1040WorkingCopy directory. This would include the Top directory TENFORTY. For our purposes here we can call this the TENFORTY module. There are others available right now for various aspects of the project. The simplest way to find out is to use the View-CVS tool.

[/home/you/1040WorkingCopy ]$ ls -larh Should show you all.

You will notice some directories called CVS
you need not edit or add anything to these directories.
CVS uses them for CVS stuff. For now just look. ( please :)

By the way one of the many pieces of information stored in the CVS directories is the URI to the CVSROOT.

You now have your own copy of the Repository module called TENFORTY. You can use this to build the application or to edit and fix/improve/debug etc. once you have changed even a single whitespace your ready for the next step :)

Commit Your Changes

For clarities sake I am going to assume you didn't add any new files or directories . That's comes later... So all we need do now is Commit your Changes to the repository.

The format for this process goes like this:

cvs commit -m "a short message" filename anotherfilename yetanother and-so-on

I am going to use a slight short cut, which is useful when you have worked on one or a number of files. Note where the commands are issued from .

[/home/you/1040WorkingCopy/TENFORTY ]$ commit -m "description of changes"

CVS will tell you it's examining this directory then upload the changes. It will finish with some version's information and a short report.

You might use the View-CVS web interface to see this is all as you expected.

It's that simple. The -m "description of changes" leaves a CVS log message with each file so we can quickly see what's been done. You don't have to use the -m switch but CVS will open your default editor and make you leave a message in any case, so you may as well do it now.

Please leave an explanation in the ChangeLog, even if it's just "fixed that bug" it makes tracking changes and intent much more productive.

Note that CVS ignores any files that have not been registered with it previously during this process. (It also knows about all the common backup suffixes etc. and will generally ignore those as well) So the net effect is to upload any source file that's altered. Even if you don't want it to ! To commit particular file(s) only, name them as a whitespace separated list (tab completion works) after the quoted message.

Update Your Working Copy

This next step is an important one. Essentially what you need to do before you work on the current source is to bring your working copy into alignment with the Repository. The syntax is simple.
cvs up
Issued from anywhere in your working copy will attempt to bring everything in the current directory and below into alignment.

[/home/you/1040WorkingCopy/TENFORTY]$cvs up

CVS will connect to the server and recursively compare files, downloading any that can be overwritten. What CVS won't do is overwrite anything that is different to a file version it knows about.

This means it will report files in your source that it knows nothing about (with a ?) and will tell you to move files it knows about but are not registered versions (with m) . Running update after a session and / or before your next session is a great way of checking that you actually have committed everything you meant to and that you are working with the latest version of every file. It may help to think of update as meaning "download the latest changes and compare my Working version with the Repository".

You only need to run checkout when your building a new Working Copy of some or all of the Repository; Update takes care of everything after that.

Add new Files

To this point we have been working with existing files. The time will come when you will need to ADD some new files. This is a two stage process.

The first stage uses the syntax
cvs add filename filename2 filename3
This tells CVS to set up the info it needs in those CVS directories at the repository. "Add me to the list of files you manage in this Repository module"

The second stage is just a simple commit

An example

[/home/you/1040WorkingCopy/TENFORTY]$cvs add newfile.pm

CVS will log the changes to the repository and then tell you to commit the file to have it usable.

[/home/you/1040WorkingCopy/TENFORTY]$cvs commit -m "module for extracting tags" newfile.pm

To ADD a new directory you need to have at least one file in it. (CVS manages files not directories) The process is just the same. It is best to add the directory and then the file like this:

[/home/you/1040WorkingCopy/TENFORTY]$mkdir newdirectory
[/home/you/1040WorkingCopy/TENFORTY]$cvs add newdirectory

CVS should report something like: Directory /TENFORTY/newdirectory added to the repository

Now assuming you have built a file called (amazingly) newfile you would add it to the Repository like this:.

[/home/you/1040WorkingCopy/TENFORTY]$cvs add newdirectory/newfile

CVS should report something like this:
cvs add: scheduling file 'newdirectory/newfile' for addition.
cvs add: use 'cvs commit' to add this file permanently

So all you need do is run commit from somewhere above the new directory and it should all be uploaded and placed into action.

[/home/you/1040WorkingCopy/TENFORTY]$ cvs commit -m "my new file that does this great thing"

CVS should report:
Checking in TENFORTY/newdirectory/newfile
... ... ...
initial revision: 1.1
done

Conclusion and Revision

CVS is a very flexible and useful tool. The above really serves only to get you started. All the commands mentioned so far take extra switches and there are many more commands and tools available for you to use and abuse. However 90% of your work can be accomplished with just add, commit and update. Update is your friend use if often . Update after every commit and before each coding session and you will catch most errors (in the code and in your working copy) before they become a problem.

The most common problem you may have will probably be merge conflicts. Essentially you have to resolve these by hand. I can waffle on some more about it but it comes down to that. The next most common problem would be "no version" errors. Go back and add the directory and files step by step. Directory first. Then Files. Don't even think about trying to update until you have both steps done. :) Check that you have your environmental variables set correctly and that you are in a working copy of the repository.

This doc is "definitely a work in progress" it is written almost totally from the results of user reported problems and issues, please feel free to report any problems you have with this doc (or the rest of the site) and any CVS issues to Pete.

Remember;
checkout (co) a repository once
add your new files to the repository
commit your changes so we can all use it
update (up) your working sources.

Hope this helps. (not hinders)
Pete (Your tame Admin.)
September 2002