1.1 HOW-TO Use CVS

Projects for which different people work on the same set of files benefit from organizing these files and keeping track of any changes to them. To this end, a program called CVS (Concurrent Versions System) is used. In this chapter, a short introduction is given with regards to CVS functionality that we most often use. For the Astro-WISE project, source code, webpages, and documentation files are stored using CVS.

1.1.1 AWBASE and test version

It is important to note at this point that we maintain a CVS version of the code which is tagged as ``AWBASE''. This version is tested and qualified and we therefore strongly recommend that you use this version if you do checkout your own code. The lastest CVS version is referred to as ``current'' or ``test''.

1.1.2 Getting access

Read-only access is available using the following commands. The password to login can be requested from your Astro-WISE representative. Logging in can take a little time.

cvs -d :pserver:anoncvs@cvs.astro-wise.org:/cvsroot login
# base version
cvs -d :pserver:anoncvs@cvs.astro-wise.org:/cvsroot checkout -r AWBASE <module>
# test version
cvs -d :pserver:anoncvs@cvs.astro-wise.org:/cvsroot checkout <module>

where module can be:

• awhtml - for the webpages
• awe - for the pipeline (documentation is found in awe/astro/docs and various README files)
• install - for the installation scripts

In order to get write permission you first need ssh (secure shell) access to the repository. First you will have to generate a private/public DSA key pair. Make sure you are using secure shell protocol 2! Recent versions of ssh should default to protocol 2, e.g. OpenSSH 2.9 and newer. The public/private keypair is generated with:

ssh-keygen -t dsa

You will be asked for a passphrase. This passphrase can be empty or, for additional security, a phrase. Make sure you remember the passphrase if you use one, because you will need it when authenticating yourself later. If you are behind a firewall check that it does not block outgoing ssh connections.

The next step is to send the file called:

~/.ssh/id_dsa.pub

to danny@astro.rug.nl and wait for further instructions.

While waiting for instructions add the ssh-rsa public key for the cvs.astro-wise.org host to the file called:

~/.ssh/known_hosts

Depending on the version of your secure shell you might have to add the key to a different file instead, e.g. /.ssh/known_hosts. In addition, ensure that your version of ssh uses the same protocol as cvs.astro-wise.org server. Under some circumstances you'll have to create or edit a file called /.ssh/config and add a line stating:

Protocol 2

The ssh-rsa public key for cvs.astro-wise.org can be found http://www.astro-wise.org/howto/cvs_id.pubhere.

Once you have write access, the code can be obtained with these commands:

setenv CVS_RSH ssh   (csh syntax)
  or
CVS_RSH=ssh; export CVS_RSH   (sh syntax)

cvs -d cvs.astro-wise.org:/cvsroot checkout -r AWBASE <module> # base version
cvs -d cvs.astro-wise.org:/cvsroot checkout <module>           # test version

where module can be:

• awhtml - for the webpages
• awe - for the pipeline (documentation is found in awe/common/docs, awe/astro/docs, and various README files)

1.1.3 Using your CVS checkout

Set the $AWEPIPE environment variable to the directory of the awe module to use your CVS checkout with the awe-prompt. That is, set $AWEPIPE to the directory with the common and astro directories. E.g. in csh

setenv AWEPIPE /Users/users/myname/myawe/awe

or in bash

export AWEPIPE=/Users/users/myname/myawe/awe

1.1.4 Using CVS

After checking out a module the next two CVS commands are most often used (there is a module called Demo on cvs.astro-wise.org that you can use to practice your CVS skills):

• cvs update

This command will update the locally checked out version of the module. The local version is merged with the latest version in the CVS repository. Usually it is a good idea to use CVS update -d which will ensure that directories that have been added to the module in the repository are created. Without the -d option only the directories that currently exist in the locally checked out module will be updated.

• cvs commit

This command will commit local changes to the CVS repository. You will be asked to supply an informational text, where you can enter e.g. what the reason for the change was. If used without options everything that was changed will be committed. If one or more files and/or directories are specified as arguments to CVS commit only those are committed.

In short, if you want to be in sync with changes that others have made you use CVS update, and if you want to propagate your own changes to others, use CVS commit.

NB. It is very important to regularly do an update and not to wait too long with a commit, especially when there is a high probability that you are not the only person working on a file. In particular, before you commit major changes it is important to update. If you do not, there is a risk that CVS will inform you of a conflict which has to be solved by hand.

A few examples:

cvs -nq update -dPA

Does not actually update (-n option), just does the regular checks. Runs in quiet mode (q). Creates new directories if any are found in the repository (-d option). Removes directories that are empty in the local checkout (-P option). Resets any tags, updates to the newest versions (-A option).

cvs commit -m "Fixed <error> in <place>" astro/toolbox/<something>.py

1.1.4.1 Switching between the AWBASE and test versions

To obtain the AWBASE version in your own CVS checkout, do

cvs -q update -r AWBASE -dP

This will replace all files with the AWBASE version. Note that files, that you have changed, will NOT be replaced. Subsequent updates with cvs update will continue to retrieve the files tagged as AWBASE. To get the most recent version again, do

cvs -q update -dPA

If you want the latest versions you will first have to use the "-A" option!

1.1.4.2 Selecting the version for a given time

It is possible to get a particular version of file from CVS for a given time. This makes it easy to resort to the version of a week ago, in case the most recent version appears to have problems.

To obtain the version of a given time, do

cvs -q update -dP -D <date>

The <date> can be specified in a large variety of formats, including ISO-formatted (1972-09-24 20:05), MM/DD/YY (or DD/MM/YY, depending on your desktop settings). Some examples are

'1 month ago'
'2 hours ago'
'400000 seconds ago'
'last year'
'last Monday'
'yesterday'
'a fortnight ago'
'3/31/92 10:00:07 PST'
'January 23, 1987 10:05pm'
'22:00 GMT'

1.1.5 Moving the AWBASE tag

The AWBASE tag can be moved to a different revision of a file in CVS. When doing that, it is no longer possible to know to which revision of a file AWBASE was previously pointing. To be able to revert to the previous AWBASE the following steps have to be taken when moving the AWBASE tag in CVS.

1. Add a tag named AWBASE<yymmdd>, where <yymmdd> is the current date. For example, the tag for July 14th, 2006 becomes AWBASE060714. A convenient way to do that from the unix prompt is

   cvs tag AWBASE`date +%y%m%d` filename
   

   Be sure to supply a filename or all files will be tagged recursively!

   The above example will tag the latest version. If you intend to move the AWBASE tag to a specific revision, other than the latest version, you have to include the -r option. To move to revision 1.20 of interesting.tex, for example, do

   cvs tag -r1.20 AWBASE060714 interesting.tex
   

   The cvs log command can be used to get an overview of all revisions of a file.
2. Move the AWBASE tag to the tag that was created in the previous step. The following command can be executed from the unix prompt to do this conveniently

   cvs tag -r AWBASE`date +%y%m%d` -F AWBASE filename
   

   Be sure to supply a filename or all files will be tagged recursively!
3. Remove the sticky tag that was created by the cvs tag command.

   cvs -q update -A filename
   

   This step is higly recommended for beginning CVS users and optional for expert CVS users that know about ``stickyness''. If you have no idea about your level of CVS expertise, always perform the last step.

   Of course, the above commands can be combined in an alias for convenience. An example for Unix in C Shell is:

   alias cvstag 'cvs tag AWBASE`date +%y%m%d` \!* ; cvs tag -r AWBASE`date
                                +%y%m%d` -F AWBASE \!* ; cvs -q update -A \!*'
   

---