WinCVS Tutorial (Part I)

 


For additional information about WinCVS, take a look at WinCVS Tutorial (Part II) or at one of the references listed at the end of this document.

 

What is CVS?  17

Terminology  25

Getting Started with WinCVS   61

Starting a New Module  112

Checking Out a Module  136

Adding Files and Directories  154

Editing a File  165

Committing changes  179

Updating files  201

Resolving Conflicts  223

Locking files  238

Viewing changes  244

References  263

 

What is CVS?

CVS stands for Concurrent Versioning System. A version control system stores one master copy of your source code in a central repository and allows you to checkout files to make changes to them.

 

CVS helps if you are part of a group of people working on the same project. It is all too easy to overwrite each others’ changes unless you are extremely careful. CVS solves this problem by insulating the different developers from each other. Every developer works in his own directory, and CVS merges the work when each developer is done.

 

Using CVS, you can also record the history of your source files and can easily retrieve old versions to see what modifications you made.

 

Top

Terminology

The terminology used in this tutorial is listed here. You are strongly advised to become familiar with the basic terminology, before delving into the rest of the tutorial.

Repository

CVS stores a complete copy of all the files and directories that are under version control in the repository.

Working Directory

Normally, you never access any of the files in the repository directly. Instead, you use CVS commands to get your own copy of the files into a working directory, and then work on that local copy.

 

Note that the repository is not a subdirectory of the working directory, or vice versa; they should be in separate locations.

          Remote Repository

When the CVS repository is accessed remotely from a different machine, it is called a remote repository. Using CVS in this manner is known as the client/server operation. The machine that mounts the CVS repository is known as the server, and you will run CVS from another machine, known as the client, which mounts your working directory.

 

Your working copy of the source files is going to be on a different machine than the repository. The seel machine is going to act as the server, and mount the CVS repository. You can use any of the machines in the lab, and use the WinCVS client to connect to the server.

            WinCVS

WinCVS is a win32 client interface to the CVS version control system, available at http://www.wincvs.org.

 

For more information, see the section Getting Started with WinCVS.

            Module

                        Module is a directory hierarchy. A software project normally exists as a single module in the repository.

                       

CVS lacks good support for restructuring a project file hierarchy, so you save yourself a lot of trouble if you spend some time planning before importing a new module.

            Import

Normally refers to the process of creating a new module in the repository by sending an entire directory structure. Note that the directory structure on the client is not under version control after importing the module. Importing the module has simply added this module into the repository. You need to checkout the module in order to obtain the CVS controlled code.

 

For more information, see the section Starting a New Module.

            Checkout

                        Normally used to describe the first retrieval of an entire module from the repository.

            Commit

                        Sending your modifications to the repository.

            Update

                        Get other users’ modifications from the repository. Updates the local copy only.

            Export

Refers to the extraction of an entire module from the repository, without any CVS administrative files. Exported modules will not be under CVS control.     

            Tag

                        A symbolic name given to a set of files at a specific time of development.

 

Top

Getting Started with WinCVS

WinCVS is a win32 client interface to the CVS version control system, available at http://www.wincvs.org.

 

Note: Before you begin, make sure to get your user-id and password for connecting to CVS.

 

1.      Download WinCVS from here http://mirror.openspace.ch/maccvs/download.html Note that the latest stable release 1.2 works on Windows 98 and Windows NT/2000. WinCvs is known to work on recent systems (not on Win95 and WinNT 3.5, except if you installed Internet Explorer 4 or above). It requires some recent libraries like shlwapi.dll, COMCTL32.DLL, COMDLG32.DLL.

2.      Install it. Unzip the file downloaded into a temporary folder and run setup.exe. Follow the instructions provided by the installer. WinCvs will add itself to your start menu but you will probably want a shortcut to it on your desktop.

3.      (Not required) Command-line interface option. If you intend to use the built in command line interface option, you also need to install Tcl/Tk8.1.1 from www.scriptics.com.

4.      Run it. Run the executable file, either from the startup menu or from the shortcut on your desktop. When you launch WinCVS, you see a screen that looks like this:

 

 

The pane on the left is the workspace. The upper right pane shows the details of the currently selected folder in the workspace. Of-course this is familiar to all Windows users. The lower right pane is the output. All messages from the CVS server are displayed here. The location of all these panes is change-able; so don’t worry if you don’t find your panes in the location shown above.

 

5.      Setting the Browse Location

The first time, WinCVS asks you for your browse location, you need to select the directory where all your code resides.

 

 

6.      Setting the WinCVS preferences

When WinCVS starts for the first time, the Preferences dialog box should pop up automatically. If it doesn’t, you can open the dialog box from Admin->Preferences…

 

 

(i)                 General Tab

 

Enter the CVSROOT:

:pserver:your-id@seel.eecs.wsu.edu:/usr/local/cvsroot

 

Authentication:

  “passwd” file on the cvs server

           

 

(ii)               Globals Tab

 

Uncheck the “Checkout read-only” check box.

 

6.   Logging in

      Before any cvs files operations can be performed, the user must log in to cvs. Log in to cvs by selecting Admin->Login… from the menu. You will be prompted for your password.

 

 

            Enter your password and click Ok. If your login was successful you’ll see a message in the status window:

 

cvs login

(Logging in to your-id@seel.eecs.wsu.edu)

 

*****CVS exited normally with code 0*****

 

            If your login failed, you’ll see a message in the status window:

 

cvs login

(Logging in to your-id@seel.eecs.wsu.edu)

cvs login: authorization failed: server seel.eecs.wsu.edu rejected access to /usr/local/cvsroot for user your-id

 

*****CVS exited normally with code 1*****

 

If you have reached this point successfully, you have the configuration details out of your way and are all set to use WinCVS for your project version control.

 

Top

Starting a New Module

One of the first things you would be looking at when you start using WinCVS is how to get all those project files you have under version control? Getting your project files (a module) under version control is called importing in CVS terminology. Make sure you have a directory structure with only those files that you want to have in the repository, and then proceed as below:

 

Note 1: Importing a module needs to be done just once for any project. That means that you can have the project leader of your group, import all the files into CVS.

 

Note 2: Be aware that CVS treats empty directories as non-existent. You might want to put a dummy file in an empty directory if you want to import it to the repository.

 

1.      Choose Create->Import module… from the menu.

2.      In the dialog box that pops up, choose the project directory that you have prepared.

3.      The Filter dialog box shows up, make sure that the files mentioned have the correct text/binary setting.

 

 

4.      In the Import Settings dialog box, enter the module name, under which you want to store your files in the repository. Enter your name in the Vendor field and start in the tag field.

 

 

5.      Press the Ok button.

 

Note: Nothing is changed in your local copies during the import operation. That means that the local copies will NOT be under version control after the import operation. You need to checkout a copy of the module to get a version-control copy of the files you just imported. For more information see the section Checking Out a Module.

 

Top

Checking Out a Module

Checking out a module from the repository gives you a local copy of the directory hierarchy that makes up the module.

 

1.      Choose Create->Checkout Module… from the menu.

 

 

2.      In the dialog box that pops up, specify the name of the module that you want to check out (this will be the same name that the group leader specified while importing the module to the repository) and the local folder where you want to check out the module to.

 

 

3.      Select the Globals tab and make sure that Checkout read-only is un-checked.

4.      Press the Ok button.

 

Note 1: Make sure all further work you do, is done on the files in the folder you have checked out the module to. Any previous project files on your machine are NOT under version-control.

Note 2: All further development should be done by checking out files from WinCVS. For more information see the section Editing a File.

 

Top

Adding Files and Directories

When you create new files that you want to include in the repository, you must tell CVS to handle the files. If the directory containing the files is not under CVS control, you will have to add it before adding the files. (If you want to add entire directory hierarchy, you should look at the section Starting a New Module).

 

1.      Select the directory, file or files that you want to add.

2.      Choose Modify->Add selection or Modify->Add selection binary from the menu.

 

 

3.      As the files are only marked for addition, you have to commit them to enter them in the repository. (For more information see section Committing changes).

 

Top

Editing a File

Since “Checkout read-only” was selected while checking out a module, you’ll need to explicitly tell WinCVS, which files you intend to edit before editing them. This may be cumbersome, but it enables other developers to track who is currently editing given files (see step 5 below).

 

1.      Select a file that you want to edit by clicking on it in the workspace.

2.      Choose Trace->Edit selection from the menu.

 

 

3.      The icon next to the filename changes to reflect the fact that you can edit it now.

4.      Open the file by double-clicking on it and save the necessary changes. The icon next to the file becomes red, to indicate that it is a dirty file.

5.      Make sure to unedit the file if you don’t intend to check it in by choosing Trace->Unedit selection.

6.      It is possible to ask CVS who is currently editing a file. Select the file you are curious about and choose Trace->Editors of selection from the menu. The list of known editors of the file is displayed in the output window.

 

Top

Committing changes

All changes you make in the file that you have checked out are only to your local copy. If you want to make those changes available to others who access that file in the repository, you need to commit your changes to the repository by checking it in.

 

1.      Select the directory, file or files that you want to commit.

2.      Choose Modify->Commit Selection from the menu.

 

 

3.      In the Commit Settings dialog box, enter a log message to describe what changes you made and press Ok.

4.      If the commit was successful, you will see the following message in the output:

 

cvs commit -m "no message" readme.txt (in directory C:\Group1\)

Checking in readme.txt;

/usr/local/cvsroot/Group1/readme.txt,v  <--  readme.txt

new revision: 1.3; previous revision: 1.2

done

 

*****CVS exited normally with code 0*****

 

Note 1: Before committing, you should do an update to make sure there are no conflicts. For more information see section Updating files

 

Top

Updating files

There might be more than one person working on the same file. One of the developers will have to merge in the changes made by the other developers before committing the changes. The process of getting changes from the server to your local copy is called updating.

 

1.      Select the directory, file or files that you want to update.

2.      Choose Modify->Update selection… from the menu.

 

 

3.      A merge conflict will result if two developers modify the same portion of a file.  If a merge conflict is detected, WinCVS displays a red C icon next to the file.  It's up to the developer to resolve conflicts by hand.  CVS will not let you commit a file that has unresolved merge conflicts in it. For example, the following output is generated in the output window:

 

cvs update readme.txt (in directory C:\Group1\Group1)

RCS file: /usr/local/cvsroot/Group1/readme.txt,v

retrieving revision 1.3

retrieving revision 1.4

Merging differences between 1.3 and 1.4 into readme.txt

rcsmerge: warning: conflicts during merge

cvs server: conflicts found in readme.txt

C readme.txt

 

Note: If a merge conflict occurs, you need to manually resolve the conflict before you can proceed to commit your changes. For more information see the section Resolving Conflicts.

 

Top

Resolving Conflicts

Two developers can modify the same file at the same time.  One of the developers will have to merge in the other developer's changes before committing the file.  If you don't check in your changes frequently you will be merging a lot.  It's best to communicate with your team members to make sure you don't step on each other's toes.

Let's say that someone modified a file that you've been working on.  Now you have to merge in the other developer's changes.  This process is called "updating." (For more information see the section Updating files). A merge conflict will result if two developers modify the same portion of a file.  If a merge conflict is detected, WinCVS displays a red C icon next to the file.  It's up to the developer to resolve conflicts by hand.  CVS will not let you commit a file that has unresolved merge conflicts in it.

During an update, CVS modifies the file to show you the conflicting edits.  But not to worry -- the original file is saved to another file like .#readme.txt.1.3 before the merge takes place, so you will not lose your work.

For example, a file that has a merge conflict might have the following text:

Good, this seems to work :)

<<<<<<< readme.txt

Hi there !!! abcdef=======

Hi there !!! okay>>>>>>> 1.4

Both set of changes must be resolved to a single set of changes before committing the file. This normally involves communication both the developers who worked on that file and made changes to it.

Once the conflict has been resolved, go ahead and commit the changes. (For more information see section Committing changes).

Top

Locking files

(This option doesn’t seem to be working with WinCVS1.2) Two developers can modify the same files at the same time.  This can be a problem with binary files so CVS provides a locking mechanism.  A file that is locked by one developer cannot be "committed" by another developer. By default, CVS prevents files from being locked. In this case you can use the cvs edit -c command to acquire a "reserved" checkout, the cvs commit -c command to commit the file, and cvs unedit -c to remove the lock. WinCVS does not provide a user interface to the edit -c, commit -c, and unedit -c commands.  It must be entered at the command line or within WinCVS's command-line window. 

 

Note: You would be better off communicating within your group regarding who is making changes to which file, and resolving conflicts by talking to each other, than trying to attempt and use this feature.

 

Top

Viewing changes

WinCvs may be used for viewing status, logs, diffs etc, of files and directories.

1.      Select the directory, file or files that you want to know more about.

2.      Choose one of Query->Diff selection, Query->Log selection, Query->Status selection or Query->Graph selection from the menu.

3.      If a dialog box pops up, enter any necessary information, and press the OK button.

 

 

Here is a short explanation on what output you might expect from the various status commands:

 

Diff

Lets you compare your local copy of a file with any revision of the same file in the repository. It also lets you compare different revisions within the repository. The output consists of lines starting with < or >, symbolizing lines that should be removed or added respectively, to go from your revision to the one you compare against.

Log

Shows log messages, dates, tags, authors, etc. for all revisions of the given files (unless you limit what revisions to display).

Status

Displays the modification status of the given files, i.e. whether the files are modified locally or in the repository. It also shows both the local and the repository revision numbers, and tags, if any.

Graph

A rather cool feature that shows the revision graph for a single file. Particularly useful when you have one or more branches in the file's revision history. The local revision is marked by a document icon. The graph lets you select two revisions (using the shift button for some reason) and do a diff between them.

 

You can configure WinCVS to use an external diff program too. For more information see Using external diff program with graph mode  Error! Bookmark not defined..

 

Top

 

References

You might find the following resources helpful, if you run into any questions/problems while using WinCVS.

 

1.      WinCVS Daily Use Guide. http://www.computas.com/pub/wincvs-howto/ (Excellent reference material with helpful tips for basic functions)

2.      WinCvs Version 1.1 User Guide. http://www.wincvs.org/winhtml/wincvs11.htm (Step by step guide for every function available)

3.      WinCVS QuickStart for Novices. Manik Surtani. http://silkroad.co.uk/help/help.php3 (As the title suggests….a quick start)

4.      CVS and WinCVS QuickStart Guide. http://devguy.com/fp/cfgmgmt/cvs/startup/  (Step-by step instructions with nice pics)

5.      CVS Information manual. http://www.cvshome.org/docs/manual/cvs.html (How to use and administer CVS)

 

Top