Friday, August 31, 2007

CVS Basics Tutorial (usage guidelines from an user's perspective)

CVS Basics

[Note: commands are given in blue. System responses are given in

Why should we use CVS?

  • If the system crashes, we can get back the files from CVS. So CVS can be used as a back up.
  • It is commonly used for file sharing. You can see your team's file from a cvs server.
  • It is used to creating builds for your project. Builds are packages that you create for your project - say as a zip or tar.
  • CVS has a versioning system. You can take not only the latest version of your system but any version which you checked in any time in the past. The coolness here is that, only the difference between the previous and the current version is stored in the server so that the storage space is taken minimally.

This document is written for the user point of view. The administration part of CVS (like import, branch creation will not be covered here.

CVS Usage:

1. The first step is that you will check out the existing files from the cvs server. When you check out we get
a.All folders we checked in
b.versioning and location information (like current folder, files, version etc) are present in a hidden folder called 'CVS'.

command : cvs co MyApplication (co means checkout - you can use checkout instead as well) - MyApplication is a folder available in the cvs server, which is your root directory.

you will get a list of files that are downloaded. the files get stored in the directory from where you execute this command

say, this gets you a folder MyApplication\source\com\CompanyName\Project\Module\

(You can checkout a single file or a single folder with the command say cvs co MyApplication/folder1/file1.txt or cvs co MyApplication/folder1)

You can expect your output to be something like the following :
C:\Documents and Settings\username\Desktop>cvs co MyApplication
cvs checkout: cwd=C:\Documents and Settings\username\Desktop ,current=C:\Documents and Settings\username\Desktop
cvs server: Updating MyApplication
cvs server: Updating MyApplication/build
U MyApplication/build/
U MyApplication/build/build.xml
U MyApplication/build/
U MyApplication/build/genreports.conf
U MyApplication/build/library.xml
cvs server: Updating MyApplication/Project_package
cvs server: Updating MyApplication/Project_package/conf
U MyApplication/Project_package/conf/module.xml
U MyApplication/Project_package/conf/server.xml
U MyApplication/Project_package/conf/web.xml
A folder called MyApplication gets created and all files and subfolders are copied to the folder MyApplication. Since i executed this command from my windows desktop, MyApplication folder gets created in my desktop.

2. next you are going to add files say Program1.c and Program2.c inside the folder MyApplication\source\com\CompanyName\Project\Module\test
go to the folder MyApplication\source\com\CompanyName\Project\Module\
You have to first add the folder 'test'

C:\Documents and Settings\username\Desktop\MyApplication\source\com\CompanyName\Project\Module>cvs add test
? test/Program1.c
? test/Program2.c
Directory /mycomp/projects/mysd/MyApplication/source/com/CompanyName/Project/Module/test added to the repository

The folder test is added, cvs says that that there are other two files unadded inside the folder test. You can add the files as you see below.

C:\Documents and Settings\username\Desktop\MyApplication\source\com\CompanyName\Project\Module>cvs add test\Program1.c test\Program2.c
cvs server: scheduling file `test/Program1.c' for addition
cvs server: scheduling file `test/Program2.c' for addition
cvs server: use 'cvs commit' to add these files permanently

3. after you type this command, only the entries of the files Program1.c and Program2.c will get uploaded to CVS.
the actual files Program1.c and Program2.c will get uploaded to the CVS when you type the following command

command : cvs ci test\Program1.c test\Program2.c (ci means check in, you need not check in a folder, 'add' is enough)
if you simply say 'cvs ci', all the files that you added from the current folder will get uploaded/updated to cvs.

when you add a file for the first time (you will 'add' a file only once), you have to check in from the same folder where you added the file.

C:\Documents and Settings\username\Desktop\MyApplication\source\com\CompanyName\Project\Module>cvs ci test\Program1.c test\Program2.c
RCS file: /mycomp/projects/mysd/MyApplication/source/com/CompanyName/Project/Module/test/Program1.c,v
Checking in test/Program1.c;
/mycomp/projects/mysd/MyApplication/source/com/CompanyName/Project/Module/test/Program1.c,v <-- Program1.c
initial revision: 1.1
RCS file: /mycomp/projects/mysd/MyApplication/source/com/CompanyName/Project/Module/test/Program2.c,v
Checking in test/Program2.c;
/mycomp/projects/mysd/MyApplication/source/com/CompanyName/Project/Module/test/Program2.c,v <-- Program2.c
initial revision: 1.1

The files are uploaded to the cvs server successfully.

4. Merge / Update
Here comes an important part which requires notice.
Suppose imagine you are checking out a file called sample.c, the version is 1.2. After you check out, your colleague has made some changes to the file and has checked in the same, the version of the file has gone up to 1.3. Now you are making some changes and trying to check in. Now the version which you are holding is 1.2 which is older than the file which is in the cvs server. Now cvs will not accept your file. It will ask you to update the changes first before checking in.

you can update saying -

command :
cvs update myfile.txt

If you simply say this command, the version which your colleague has checked in will get copied into your system and the changes which you made will be lost. So what do you do?

Here is a plan.
rename your file say to myfile-1.txt

now say cvs update myfile.txt . Now the file which your colleague checked in will be downloaded to your folder. Now you can see the changes and update your new file (myfile.txt) from your old file (myfile-1.txt) and then check in the updated new file. (Now of course once again the file version will go up say 1.4).

(if you simply say 'cvs update', all the files in the current folder and the files in the subfolder will be updated from the cvs server to your local system)

C:\Documents and Settings\username\Desktop\MyApplication\source\com\CompanyName\Project\Module\test>cvs ci Program1.c
cvs server: Up-to-date check failed for `Program1.c'
cvs [server aborted]: correct above errors first!
cvs commit: saving log message in C:\DOCUME~1\username\LOCALS~1\Temp\cvsBF.tmp

No comments: