Using CVS

What can a Versioning System do for me?

• Allow multiple users to modify the same code.
• Store one master copy of your source code.
• Retrieve any changes made to any file.
• Allow remote access to your code to uses who don't have logins on your machines.

Where does CVS store your code?

• The master copy of the code is stored in the CVSROOT directory.
• The code may be checked out from anywhere in the world.
• Any version of the code is available. Any changes made can be retrieved instantly.

Setting up CVSROOT

• You must tell CVS where the repository is store, via the CVSROOT environment variable.
• usage:

    export CVSROOT=:pserver:<login name>@<server address>:<repository>

• examples:

    (csh)     setenv CVSROOT :pserver:shack@zeus.itg.uiuc.edu:/itg/src/cvsroot
    (sh/ksh)  export CVSROOT=:pserver:shack@zeus.itg.uiuc.edu:/itg/src/cvsroot

Logging into the CVS server

• After you set your CVSROOT variable, you must log into the server.
• usage:

     cvs login
     (Logging in to shack@zeus.itg.uiuc.edu)
     CVS password: xxxxxxxx

• Note: If you get an error saying:

     Sorry, you don't have read/write access to the history file

  email your CVS repository administrator.

Importing a new module into CVS

• To move some source code into CVS for the first time, use the import command.
• usage:

     cvs import [module name] [vendor-tag] [release-tag]

• example:

     cvs import shack/demo shack init

  This imports the current directory and all subdirectories into the shack/demo module.

Checking out a copy of code

• In order to edit the source code, you must checkout a copy in your working directory.
• Every user of the repository will checkout their own copy of the source code. This will allow each user to develop and test their changes individually, before committing the changes to the server.
• usage:

     cvs checkout [module name]

• example:

     cvs checkout shack/demo

  This checks out all the files in the shack/demo module and places them into a shack/demo subdirectory.

Adding a file

• If, during your development, you wish to add a file into the current module, you must use the add command.
• usage:

     cvs add [file1] [file2] [files...]

• example:

     cvs add helloworld.pl

  Adds the file helloworld.pl into the module in the current directory.

Removing a file

• If you wish to remove a file from the current module, you must use the remove command.
• usage:

     cvs remove [file1] [file2] [files...]

• example:

     cvs remove helloworld.pl 

  Removes the file helloworld.pl from the module in the current directory.
• NOTE: You must remove the file first from the current directory, then issue a cvs remove command. Otherwise, it will assume you still want to keep the file around.

The Update Command

• The update command is used to synchronize your local copy with the repository.
• It states all the files that have locally been modified, removed, or added.
• Indicates any files in the local directory that are not in the repository.
• Update also merges any changes that have been committed to the repository with your local copy.
• If changes made by another user conflicts with changes that you have made, update will warn you of this and prompt you to manually merge the changes. We'll see an example later.
• When you execute the update command, it will list all the files that are of concern.
• usage:

     cvs update [file1] [file2] [files...]

• example:

     cvs update: Updating .
     ? concl.html   <-- this file/directory is not in cvs
     M tbl.html     <-- has been modified
     A add.html     <-- file will be added to the repository
     R remove.html  <-- file will be removed from the repository
     U intro.html   <-- a newer version was found on the server
                        the file is brought up to date
     C index.html   <-- there is a conflict which I must manually resolve
  

Committing Changes (1/2)

• After running the update command, you must commit your changes to the repository.
• usage:

     cvs commit [file1] [file2]

  If you omit the file list, it will commit all of the modified, added, and removed files to the repository.
• example:

     cvs commit helloworld.pl

• After issuing the commit command, cvs pulls up an editor to enter a log message. Which editor launched is specified by the EDITOR and VISUAL environment variables.
• When the editor appears, it displays a short summary of what has changed.

     CVS: ----------------------------------------------------------------------
     CVS: Enter Log.  Lines beginning with `CVS:' are removed automatically
     CVS:
     CVS: Added Files:
     CVS:    tbl.html
     CVS: ----------------------------------------------------------------------

  Here, the file tbl.html has been added.
• To abort a commit, simply leave the log empty and CVS will ask you if you want to continue:

     Log message unchanged or not specified
     a)bort, c)ontinue, e)dit, !)reuse this message unchanged for remaining dirs
     Action: (continue)

  By pressing 'a', you can abort the commit

What happens when somebody else changes some of the files that you use?

• CVS allows multiple people to modify the same file at the same time.
• When two people change the same file, CVS can, in most cases, automatically merge the changes together. cvs update will report a warning when automatically merging two files together.
• When cvs can not automatically merge two files together, it requires human intervention. In these cases, you are required to manually resolve the conflicts.

An example of a manual merger.

• Here, two people check out version 1.1 of test.c. Somebody else added the 'Hello World' statement, and committed it to the tree. This became version 1.2.
• You change the file and add the 'CVS, Explained' line.
• When you do a cvs update, you receive the following warning.

     [shack@argus demo] cvs update
     retrieving revision 1.1
     retrieving revision 1.2
     Merging differences between 1.1 and 1.2 into test.c
     rcsmerge: warning: conflicts during merge
     cvs update: conflicts found in test.c
     C test.c

• Note: the 'C test.c' line indicates that test.c has a conflict.
• Here are the different versions of the files side by side:

  Version 1.1	Version 1.2	Your copy (from 1.1)
  void main( void )	void main( void )	void main( void )
  {	{	{
  	printf("Hello World!");	printf("CVS, Explained");
  }	}	}

• When you look at the test.c file after the cvs update, it will look like the following:

     void main ( void )
     {
     <<<<<<< test.c
         printf("CVS, Explained");
     =======
         printf("Hello World!");
     >>>>>>> 1.2
     }

  To resolve the conflict, you must manually merge the code between the <<<<<<< and >>>>>>> lines.

An example of an automatic merger

• Here, two people check out version 1.3 of test.c. Somebody else changed main's argument list and committed it to the tree.
• You change the file and add the return line.
• When you do a cvs update, you receive the following warning:

     cvs update: Updating .
     RCS file: /itg/src/cvsroot/shack/d1/test.c,v
     retrieving revision 1.3
     retrieving revision 1.4
     Merging differences between 1.3 and 1.4 into test.c
     M test.c

• Note: the 'M test.c' line indicates that test.c has been modified (as if there was not a conflict).
• Here are the different versions of the files side by side:

  Version 1.3	Version 1.4	Your copy (after cvs update)
  void main( void )	void main(int argc, char **argv)	void main(int argc, char **argv)
  {	{	{
  	printf("CVS, Explained");	printf("CVS, Explained");
  }	}	return;
  		}

Acknowledgements & Additional Links

• Cyclic software for maintaining/releasing CVS
• Sean Dreilinger for his paper on CVS Version Control for Web State Projects.
• Bonsai - a who changed what search utility
• cvsweb - a repository based file viewing system