This document is a brief introduction to a Concurrent Versions System (CVS) usage. It does not cover the whole nor complete issue. Its aim is to provide a basic overview of CVS usage for people who are not enough familiar with this source code files management system.
Before you begin to work with CVS, you need to log in. For this purpose there is a command
cvs -d :pserver:firstname.lastname@example.org:/home/cvs login
To omit writing a parameter after
-d switch every time, it is possible to set an environment variable
CVSROOT to an appropriate value in
$HOME/.bashrc file for example:
If you are using other command interpreter (shell) than
bash, you have to accomplish settings of
CVSROOT variable in an appropriate way. Once the environment variable
CVSROOT is properly initialized, for login purpose just type
cvs login command.
If you are already logged into CVS, it is not needed to regularly log out. But you have to remember that password, which was entered after
cvs login command, was stored into
$HOME/.cvspass file and is encrypted with a very weak even trivial cipher. Thus after user account compromitation, the attacker also achieves access to the particular CVS repositories.
To log out from CVS system the following command is used:
The process of log out means that trivially encrypted password will be removed from
$HOME/.cvspass file. This password is sent via network every time the connection with CVS server has been established.
For all project checkout there is a command:
cvs checkout .
If you are interested in only one project checkout, use this command:
cvs checkout <project>
<project> with the appropriate name of the project. To find out, which projects are available for fetch and under what name (so called aliases or modules), use this command:
cvs checkout -c
It is quite common and rather often that developers make some changes in project. Thus it is recommended from time to time to perform an actualization of project files. This is an absolute must for project developers, always before starting work on project and sometimes even during such work. An ideal state is to work with the recent copy of source files. This can be supplied by:
The best is if this command is performed in the directory, in which some project from CVS is fetched.
INSERTING CHANGES INTO CVS
If developer made some modifications which are considered as good, then they probably want to put them into CVS as another version of a file or files. Please note that changing file locally has basically no effect on CVS and nobody knows about these alternations. To insert such modifications to CVS write the following command in the directory where changes were made:
Once the command is entered a pre-set editor (
export CVSEDITOR=vim) should be run. There, it is needed to write a message describing performed changes. Thanks to this there will be a comprendium for other developers (and later also for the modifier) about the meaning, intention and consequences of modifications. Comment is often written in language appointed by the project developers. For open source software projects English language is preferred.
After the temporary file with the comment is written and work with the editor is finished, the commit operation begins. If there was done something wrong, an error may occur during inserting changes into CVS. The most common error is the absence of access rights for writing. If no error has occurred, CVS writes out information about new version or file creation and so on by default.
If you enter only
cvs commit command, CVS will search for all modified files in the current directory and subdirectories. The entered comment for changes will be used for all changed files. Sometimes it may be desirable to insert changes only in selected files, or some change with one message and another change with a different message. For the purpose of committing selected files, there is a following command:
cvs commit <list_of_files>
There is also a possibility to insert changes only with a short message, which will be written on command line using
-m switch. In this case no text editor will be run.
cvs commit -m "Headers update." file.h file.c Makefile
Comments written during
cvs commit operation can be reviewed using this command:
cvs log <file>
On the output, there is exactly written who, what, when, how and why made changes, so there is immediately a clear overview about the file manipulations. Thus it is needed to write comments as reasonable meaningful sentences.
An example of a less eligible CVS comment:
cvs commit -m "Version changed." configure.in
An example of a much more eligible CVS comment:
cvs commit -m "Version changed from version 0.6rc3 to 0.6." configure.in
For every file or project it is possible to find out which concrete lines were changed during particular changes inserting into CVS (
cvs commit). This is useful for example when "patch" is being created. It contains only real modifications in file, so it can be used for fast publishing of bugfixes or actualizations.
For example we want to create a "patch", the application of which on source file
file.c with version
1.123 will result in obtaining the same source file with version
2.34. For this purpose
cvs diff command can be used:
cvs diff -u -r 1.123 -r 2.34 file.c > file.c-1.123-2.34.patch
User will apply "patch" on their local file with a command:
patch -p0 < file.c-1.123-2.34.patch
Differences between versions can also be obtained by the entered date:
cvs diff -D yesterday file.c
Other commands are for example
cvs admin and so on. When they are used incorrectly, they can make more damages than benefits, they can even make unrevertible changes. So we recommend beginners with CVS not to try nor use these commands.