The intention of this tutorial is to give a brief overview of basic version control functions and to show how easy it is to install and use a version control system. This tutorial uses CVS as the version control system. CVS was chosen because it is freely available along with good documentation and it works on many operating systems. The steps below assume a 32 bit Microsoft Windows operating system. Please note that even though you downloaded and installed WinCVS we are only interested in the CVS command line interface (because it is simpler). WinCVS includes the latest version of CVS for Windows PCs along with a nice install program.

Multiple work areas (called sandboxes from here on) are used to simulate two users sharing code of a test source code project. This avoids having to log in with different user names. This is one example of using multiple sandboxes of the same project on the same PC.

Download WinCVS (currently version 1.1b8) from http://www.wincvs.org/download.html. Install WinCVS, accept all defaults.

Create a directory structure like this on your hard disk:

c:\cvs
c:\cvs\test
c:\cvs\work\sb1
c:\cvs\work\sb2

Populate the new directory tree with these files:

c:\cvs\env.bat                     (see below)
c:\cvs\test\makefile.txt           (optional)
c:\cvs\test\include\file1.h        (optional)
c:\cvs\test\include\file2.h        (optional)
c:\cvs\test\source\file1.c         (see below)
c:\cvs\test\source\file2.c         (optional)

Create a batch file called cvs_env.bat in the c:\cvs directory:

set path=%path%;C:\Program Files\GNU\WinCvs 1.1;
set CVSROOT=:local:c:\cvs\repository

The five files in the test sub-directory simulate a source code project. All files contain only their file name on the first line. Note, only file1.c is used in the steps below.

Open a command prompt (DOS) window, go to the c:\cvs directory, and execute the cvs_env.bat file, i.e. type "cvs_env" (omit the quotes). This sets up the command line environment needed by the CVS version control system. Repeat this step each time you open a command prompt window for CVS. Hint, you can use multiple command prompt windows, one for each sandbox (explained below).

Type "cvs -help". This displays the CVS help screen and verifies the first line in the cvs_env.bat file.

Type "cvs init". This is the only command that does not require specific directory. This initializes the CVS repository and verifies the second line in the cvs_env.bat file. This CVS command will return without displaying any message, however it creates a directory called c:\cvs\repository. This repository (directory) contains administrative and configuration files at c:\cvs\repository\CVSROOT, all defaults will work fine for this tutorial. More importantly the repository will also contain the version control database (master copy of your source code along with a history of all changes). The repository is usually located on a central file server, but not in this tutorial to keep things simple.

Go to the c:\cvs\test directory and type:

cvs import -m"Initial import into CVS" test your_login_name start

This imports (copies) all files into the repository (to c:\cvs\repository\test) and puts the source code project under version control. The c:\cvs\test directory is no longer needed and can now be removed.

Go to the c:\cvs\work\test\sb1 directory. Type "cvs checkout test". This creates a sandbox (or work area) of the source code project.

Go to the C:\cvs\work\test\sb1\test\source directory. Add this line to file1.c (using your favorite editor or the Windows build-in editor called notepad):

"Added code for feature 1"

Type "cvs diff" or "cvs diff -c". This displays the change you just made to file1.c.

Type "cvs commit -m"Finished feature 1"". This will check-in your change into the repository.

Now go to the still empty sandbox 2 directory c:\cvs\work\test\sb2. Type "cvs checkout test". This creates another sandbox of the source code project. Note that this sandbox of the test source code project includes the change we made above in the sandbox 1 directory.

Go to the c:\cvs\work\test\sb2\test\source directory and add this line to file1.c:

"Added more code for feature 2"

Type "cvs commit -m"Finished feature 2"". This will check-in your change to the repository.

Go back to the sandbox 1 directory containing the file1.c file. Type "cvs status". This will show that there is a new version of file 1 available (file1.c status: Needs Checkout).

Type "cvs update". This will update sandbox 1 with the change made in sandbox 2.

Lastly, try "cvs log file1.c". This will display all revisions for file1.c along with all log information. Note the comments you entered above as part of the CVS commit commands.

Omitting the file name causes CVS to apply a command to the entire current directory tree. Go to the root of sandbox 1 (c:\cvs\work\sb1) and repeat the log command without a file name, i.e. "cvs log".

That's it. To summarize, you put your test source code project under version control, created a sandbox, made a change to the test project in your sandbox, and checked that change back in (to the repository). You then created a second sandbox (simulating a second user). The second sandbox contained the change you just made in the first sandbox. You then made another change, but this time in the second sandbox. The tutorial then concludes by showing how the first sandbox is updated to reflect the change from the second sandbox (user).

I would like to thank Stephen Coon for proofreading and testing this tutorial.

Olaf