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.
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:firstname.lastname@example.org:/cvsroot login # base version cvs -d :pserver:email@example.com:/cvsroot checkout -r AWBASE <module> # test version cvs -d :pserver:firstname.lastname@example.org:/cvsroot checkout <module>
where module can be:
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:
to email@example.com 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:
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:
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:
setenv AWEPIPE /Users/users/myname/myawe/aweor in bash
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):
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.
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
To obtain the AWBASE version in your own CVS checkout, do
cvs -q update -r AWBASE -dPThis 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!
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'
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.
cvs tag AWBASE`date +%y%m%d` filenameBe 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.texThe cvs log command can be used to get an overview of all revisions of a file.
cvs tag -r AWBASE`date +%y%m%d` -F AWBASE filenameBe sure to supply a filename or all files will be tagged recursively!
cvs -q update -A filenameThis 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 \!*'