B337 Advanced Software Development
Murdoch University Topic 2
CVS (Concurrent Versions System)
CVS is a version control tool that allows you to record the history of your (software) source files in a centralised repository. In the software development process, you often need to incrementally refine your source files, so each source file is likely to have multiple versions. Being able to keep track of these different versions is paramount, especially when the new version does not work the way you expected and retrieving an old version of the source file is necessary.
There are many version control tools available. The very popular version control tool is perhaps SCCS (Source Code Control System) that runs on Unix. In the B337 unit, we will use CVS which has been installed on machines in the lab. CVS is free and is downloadable from http://www.cvshome.org/dev/codewindow.html. You should use a version control system, such as CVS, when developing your software projects (assignments).
The basic operations supported by CVS are: importing source files (a Java package, for example) into the cvs repository; checking out files from the repository for updating; examining status of source files being updated; finding out difference between versions, etc. CVS also allows the repository to be on a remote machine so long as that machine is accessible via NFS (network file system), eg. the repository could be on drive H while the source files checked out from the repository were saved onto your harddisk (drive C) for fast edition and enhancement. The repository could also sit on a server and multiple software developers could access this repository from the client machines. CVS provides a locking mechanism so that a read access from the repository is pending while a write access to the repository by another developer is active.
More details on CVS can be found in the c:\Program Files\cvs\cvs.html or c:\cvs\cvs.html file. You may not be able to understand that html file fully because most of the issues discussed there are relevant for the Unix environment only while other issues are for system administration. I have therefore compiled below a brief description on how to use CVS and the set up of environment variables, path, etc. that are required for CVS to function.
I have made the assumption that the CVSROOT repository is on drive C and the working directory of the source files is also on drive C. Please refer to the last section of this text for the set up of environment variables if
(i) drive H (your home directory after you are logged on) is the desired drive for the repository and working directory, or
(ii) drive H has the repository while the working directory is on drive C (for fast source file access, for example).
Environment variable
You will need to set up the environment variable CVSROOT to point to a directory. For instance, putting the line
SET CVSROOT=:local:c:\cvs_root
in your c:\autoexec.bat file will set the c:\cvs_root to be the master source repository directory. Note that you must have the string :local: immediately before the absolute path name.
Search path
Suppose that you have cvs.exe installed on your c:\cvs directory. You should then include c:\cvs in the search path, i.e. putting the line
SET PATH=%PATH%;c:\cvs
in c:\autoexec.bat.
Note that to have the environment variable and path effective, you will need to reboot your PC or type c:\autoexec in a MS-DOS prompt window. For the latter operation, the setting will be effective in that MS-DOS prompt window only. If you are using the machines in the IT lab then you can skip this process since the search path has already been set up.
Initialisation
Do the following initialisation (assuming that you have created the master source repository directory c:\cvs_root above) in an MS-DOS prompt window:
cvs –d :local:c:\cvs_root init
The command above would create the subdirectory CVSROOT under c:\cvs_root. The CVSROOT subdirectory contains administrative files for cvs. The other subdirectories contain the actual user-defined packages (each subdirectory maintains a software package whose version you want to control and monitor).
Some commonly used cvs commands
Now suppose that you have a package of Java units, say the files HelloWorld.java and Greetings.java, under the c:\myJavaProgs directory. You are about to do some modification to any one of these files and would like to be sure that you could retrieve the current version of HelloWorld.java and Greetings.java back if something drastic happens in the modification process.
1. Importing a package into the cvs repository
You import the entire package to the cvs repository by typing:
cd c:\myJavaProgs
cvs import –m “initial import” myJavaProgs myVendorTag start
In the above command, “initial import” is the message that you specify for the importing, myJavaProgs is the package name, myVendorTag is the vendor tag, start is the release tag. The last two arguments may fill no purpose in this context, but since cvs requires them they must be present.
If the above cvs command was successful then the messages returned by cvs would be
N myJavaProgs/Greetings.java
N myJavaProgs/HelloWorld.java
No conflicts created by this import
If the –m flag was omitted in the above cvs command, then an editor (default editor is Notepad for Windows) would appear in which you could type the brief description for the reason of importing.
2. Checking out the package for updating/edition
You must check out the package before proceeding to step 3 below for the editing/updating. This step will allow you to commit the new version (after your editing/updating) of the Java units to the repository. To check out the package, type:
cvs checkout myJavaProgs
A subdirectory myJavaProgs would be created in the current directory where the command was invoked. All the Java units (in this case, HelloWorld.java and Greetings.java) and a subdirectory CVS (cvs uses it for bookkeeping tasks) would be generated in the myJavaProgs subdirectory. It therefore depends on from where you invoke the command. If you type
cd c:\
before the above cvs command, then the original version of HelloWorld.java and Greetings.java would be overwritten. However, this is not a problem as the files have not been updated since the initial import.
3. Editing/updating one or more Java units in the package
You can now proceed with your update/edition on the Java unit(s) in the package. If you have tested your modification thoroughly, you can commit the updated Java unit(s) to the cvs repository (see step 4). If your update introduced bugs into the package then you might want to discard the update and roll back to the previous version (see step 6).
4. Committing the updated Java units to the cvs repository
Suppose that you have now updated both HelloWorld.java and Greetings.java and have verified the correctness of your update. To commit the updated Java unit(s) to the cvs repository, type:
cvs commit Greetings.java HelloWorld.java
or
cvs commit *.java
The system should respond with
c:\cvs_root/myJavaProgs/Greetings.java,v <-- Greetings.java
new version: 1.2; previous version: 1.1
done
c:\cvs_root/myJavaProgs/HelloWorld.java,v <-- HelloWorld.java
new version: 1.2; previous version: 1.1
done
Note that the CVS subdirectory must be present in the current directory for the above command to work.
Not also that you can commit one or more Java units but when you check out, you must check out the entire package (i.e. all the Java units of the package). So you would need to be in the c:…\myJavaProgs subdirectory created by the cvs checkout command.
5. Comparing the differences
Suppose that you were in the c:\new directory when you checked out the package. Your directory structure would now be
c:\new – c:\new\myJavaProgs – c:\new\myJavaProgs\Greetings.java
c:\new\myJavaProgs\HelloWorld.java
c:\new\myJavaProgs\CVS
If you have edited Greetings.java extensively (say), you can compare the difference between the edited version and the checked out version by typing (assuming that you are in the c:\new\myJavaProgs directory):
cvs diff Greetings.java
6. Rolling back to an earlier version
If a Java unit that you have updated fails to work, you can roll back to the latest version from the cvs repository. Suppose that Greetings.java is damaged and you want to replace it with the latest version of Greetings.java in the repository:
del Greetings.java (DOS command to delete the damaged file)
cvs update Greetings.java
If you want to roll back an earlier version (say version 1.1) rather than the latest version of Greetings.java from the repository then
cvs update –p –r 1.1 Greetings.java > Greetings.java
The command cvs update –p –r 1.1 Greetings.java would generate version 1.1 of Greetings.java to standard output (i.e. screen), the command above simply redirects the standard output to the file Greetings.java.
7. Deleting a source file from the repository
Suppose that, after extensive update to your software package, you found that one of the source files (say Greetings.java) is redundant and should be removed. Type:
del Greetings.java (Dos command to delete the unwanted file)
cvs delete Greetings.java (tells cvs to remove the file from the repository)
cvs commit Greetings.java (you must do this to get the file removed permanently
from the history)
Next time when you check out files of the package myJavaProgs from the repository, Greetings.java would not be generated.
8. Adding a new source file to the repository
Adding a new source file (say GoodDay.java) is also easy:
cvs add GoodDay.java (add GoodDay.java to the repository)
cvs commit GoodDay.java (commit it to the history)
9. Renaming a source file in the repository
Suppose that you want to rename HelloWorld.java to HiWorld.java:
ren HelloWorld.java HiWorld.java (Dos command for renaming a file)
cvs remove HelloWorld.java (cvs remove is a synonym of cvs delete)
cvs commit HelloWorld.java (update history that HelloWorld.java has
been deleted)
cvs add HiWorld.java (add HiWorld.java to repository)
cvs commit HiWorld.java (update history)
To view a list of cvs command synonyms, type: cvs --help-synonyms
10. Viewing the status of modification and versions of files in the cvs repository
At any point in time of your update of the Java units for your project, you could inspect the status of the package by typing (assuming that you were in c:\new):
cvs status
The message displayed could look like this:
CVS.EXE status: Examining .
======
File: Greetings.java Status: Up-to-date
Working revision: 1.3 Thu Jun 29 06:53:10 2000
Repository revision: 1.3 c:\cvs_root/myJavaProgs/Greetings.java,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
======
File: HelloWorld.java Status: Up-to-date
Working revision: 1.2 Thu Jun 29 06:43:08 2000
Repository revision: 1.2 c:\cvs_root/myJavaProgs/HelloWorld.java,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
If you want to view the status of Greetings.java then use: cvs status Greetings.java
11. Releasing
When you have finished modifying the Java files and would like to move on to another task, you could either remove the working directory by hand. However, a better solution is to use the release option. Type:
cd c:\
cvs release myJavaProgs
If there were any modified files that have not been committed, cvs would prompt you for confirmation of a release. The command cvs release myJavaProgs does not clean up the c:\myJavaProgs directory unless you specify the –d flag:
cvs release –d myJavaProgs
If you confirm yes when prompted, the entire c:\myJavaProgs directory would be deleted.
Other useful cvs flags
The examples on cvs commands given above may not cover all the operations you want to accomplish in the version control process of software development. For online help of cvs commands, the summary below would be useful:
cvs history shows repository access history
cvs log Greetings.java shows the log (history information) of Greetings.java
cvs --help-options shows options available
cvs --help-commands shows commands available
cvs --help-synonyms shows cvs command synonyms
cvs shows help options
cvs --help remove shows options for the cvs remove command
cvs --help update shows options for the cvs update command
How to set up a cvs repository and a working directory on drive H
Suppose that you have your project (say as a large Java package) kept in the \myProj directory on drive H (your home directory). You want to set up the cvs repository in h:\cvs_root directory. You will need to set up a batch file which you can run each time you are logged on. It is unwise to set up the environment variables in a batch file on drive C as it is unlikely that you would be using the same machine each time you come to the lab.
- create an h:\setcvs.bat file using an editor. Put the line below in the file
set CVSROOT=:local:h:\cvs_root
- change directory to h:\ and type
setcvs
- do the initialisation
cvs –d :local:h:\cvs_root init
Note that you only need to do this initialisation once (unless you have cleaned up the h:\cvs_root directory by accident).
- to import the Java units in the myProj package into the repository, type
h:
cd myProj
cvs import myProj myVendorTag B337Assignment1
- to modify any files of the myProj package, check out the package from the repository first:
h:
cd \
cvs checkout myProj
How to set up a cvs repository on drive H but a working directory on drive C
Follow steps 1-4 above. For step 5, type:
c:
cd \
cvs checkout myProj
A working directory c:\myProj is now created for updating. When finished, commit those modified Java files back to the repository on drive H. Clean up the c:\myProj directory. Next time when logged on, do steps 2 and 5 again.
Why shouldn’t the cvs repository reside on drive C of a lab machine?
because other students can then access your packages by running cvs.
….repository residing on drive C of a personal laptop is fine.
cvs.doc Mark Reynolds/Du Huynh Page 1