Or: How to use WinCvs while keeping your mental health.
Table of Complaints
This document describes day to day usage of the WinCvs 1.0.x client. It is not an introduction to version control systems, not an introduction to CVS, and not an introduction to WinCvs. It is more like a place you may turn to when you know approximately what you want to do, but don't quite remember how to do it.
It is assumed that you already have installed WinCvs, and that you have configured it to talk to the CVS repository you want to use.
If your browser supports style sheets, you will find a couple of different typesetting and color variations thruout the document. like this.refer to elements in the WinCvs user interface, such as buttons, tabs and input field labels. References to the original CVS documentation are given
The terminology used in the CVS documentation, and thus also in WinCvs, may differ from terminology used in other source repository systems. In an attempt to avoid confusion, we provide a short list of the most essential terms. Please make yourself familiar with these words before diving into the rest of this document.
For the entire story of "revisions", "releases", "versions" and "tags", see chapter 4 of the CVS documentation.
Getting a project under version control is called importing in CVS terminology. As the name implies, you should have something for the CVS server to import before thinking version control.
CVS lacks good support for restructuring a project file hiearchy, so you save yourself a lot of trouble if you spend some time planning before importing a new module.
The basis for the import operation is a "clean" directory structure. By clean we mean that files which need no versioning (compiler generated files, backups etc.) are removed. This is particularly important if your project has been going on for a while. You may have several files in your hierarchy that you do not want to put under version control, but that you want to keep where they are anyway. In that case you have to move them out before importing, and move them back afterwards.
Be aware that CVS treats empty directories as non-existent. If you want to add a directory in which you have neither files nor subdirectories, you will have to create a dummy file in it. We suggest that you create a file named README.txt, which contains a short description of what this directory is for.
Once you have a directory structure that contains only files you want to have in the repository, do the following to import the module using WinCvs:
WinCvs will now import your entire directory hierarchy to the CVS server. Note that nothing will be changed in your local files during the import operation. This means that your local copy will not be under version control after the import. Before starting to work on your version controlled sources, you have to do the following:
You should now be able to start working on your version controlled project.
To obtain a module from the CVS server for the first time, is known as a checkout. Checking a module out from the repository gives you a local copy of the directory hierarchy that makes up the module. To perform a checkout, do the following:
If you state that Who's Editing that File? for more information.should be in use, you will have to 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 the section
Occasionally you may want changes done by others to get incorporated in your local working copy. The process of getting changes from the server to your local copy is known as updating. Updating may be done on single files, a set of selected files, or recursively on entire directory hierarchies. To update, do the following:
Changes done by others will be merged into your files, keeping any changes you may have done to the same files. The repository is not affected by an updating.
If you receive reports of conflicts during the update, please read the next section.
Once in a while, the CVS server will report a conflict when you update your files from the repository. A conflict occurs when two or more developers have changed the same few lines of a file. As CVS knows nothing of your project, it leaves resolving the conflicts to the developers. Whenever a conflict is reported, you should open the file in question, and search for lines starting with the string <<<<<<<. The conflicting area is marked like this:
You should decide what the code should look like, do the necessary changes, remove the CVS markup, and commit your modifications to the repository.
Making local modifications available in the repository, is known as committing the changes.
Please note that committing changes will not automatically add new files that you have created to the repository. See Adding Files and Directories for a description of doing that.
WinCvs may be used for vieving status, logs, diffs etc, of files and directories.
Here is a short explanation on what output you might expect from the various status commands.
At a given stage of development, giving one or more files a common label to refers to their revisions, is known as tagging those files. Tagging is typically used on entire modules, so that the current state of the module can be reconstructed in the future. This kind of tagging should always be done on project deliverables, and before starting major changes.
To tag one or more files or directories with a label, do the following:
Note that CVS is quite restrictive when it comes to what characters a tag may contain: A tag must start with a letter, and may contain letters, digits, "-" (dash) and "_" (underscore) only. In particular, this means no dots, and no spaces. If you want to include version numbers in a tag, replace the dots with dashes. Two tag names are reserved, as they have special meaning in CVS: "HEAD" refers to the most recent version available in the repository, while "BASE" is the revision you last checked out into the local directory.
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. To add files or directories, do this:
If you want to add entire directory hierarchies instead of a few files, the above technique becomes cumbersome as the add operation is not recursive. In this case you should rather use import, as in Starting a New Module:
WinCvs will now import your entire directory hierarchy to the CVS server, under the given module. Note that nothing will be changed in your local files during the import operation. This means that your local copy will not be under version control after the import. To have the newly imported hierarchy under version control, obtain a copy of it from the repository:
WinCvs will now give you a fresh, version controlled copy of your hierarchy.
To remove files, you first schedule the files for removal, and then commit the change:
The files will now be removed from the repository. Note that files are not physically removed, but rather marked as "dead". By this way it will still be possible to retrieve the files if you choose to check out an old version of the module.
Removing directories is another story. CVS will optionally remove empty directories when you update one of its parent directories. If you want to get rid of an empty directory, do the following:
The directory will be removed if all its files were previously removed from your local copy and from the repository.
Operation of moving or renaming files or directories is not available in CVS. This is one of CVS's shortcomings. To simulate moving or renaming, you have to combine remove and add operations. See Adding Files and Directories and Removing Files and Directories.
One of the features of version control systems, is the ability to isolate changes onto a separate line of development. This line is known as a branch. (See What branches are good for in the CVS documentation.)
To create a branch, do the following:
Now a new branch with the given name is created in the repository. Note: The branch is created in the repository only. To start working on the newly created branch, you have to do what is described in Selecting a Branch to Work on.
To start working on a branch instead of the default development line, you have to bind your local copy to the branch. This is needed to make sure that actions such as updates, commits etc. work on the branch rather than on the main line of development.
To move your local copy to another branch, do the following:
WinCvs will now do the necessary updates to your working copy and move it to the desired branch. The updating may include adding or removing files.
CVS puts what is known as sticky tags on the files that are affected by the branch. You may view these sticky tags by issuing a status command on the files, as described in Viewing Changes. To remove the sticky tags and thus go back to the main development line, follow the description in Going Back to the Main Line of Development.
When you are satisfied with the changes you have done on a branch, you may want those changes to be available on the main line of development. Incorporating changes from one branch to another, is known as merging. To merge from a branch, do the following:
Any changes on the branch will now be merged into your local copy. You will probably also want to commit the merged files back to the repository, as described in Sending Your Changes to CVS.
Important note: The merge given above will try to merge changes from the start of the branch. If you do the operation a second time (to merge changes done to the branch after the last merge), merging from the start of the branch is not what you want, and it will most likely get you into trouble. To get around this problem, you should give the branch a new tag after every merge, and use the new tag when naming the branch for subsequent merges.
If you want to stop working on a branch and move your local copy back to the main line of development, you have to make WinCvs remove all sticky tags. To remove the sticky tags, and thus update your local copy to the main development line, do the following:
WinCvs will now update your local copy so it matches the current main line of development. The branch you were on still exists in the repository, and you may return to it as described in Selecting a Branch to Work on whenever you want to.
It is possible to ask CVS who is currently editing a file, but it only works if the developers announce to CVS when they intend to edit a file. This model is known as the IR CVS model (well, that's actually an internal joke at Computas), and it should be decided at project startup if this model is to be used.
To use the IR CVS model, developers should check out the module read only. It can be done by checkingin the tab of every WinCvs dialog.
To edit a file, do the following:
When you commit the file, the CVS server assumes you are no longer editing it, and WinCvs will make the file read only again. If you did not make any changes, a commit will not tell the CVS server that your have finished editing it. In that case you should rather do the following:
And now, back to the original question: "Who's editing that file?" To list the editor(s) if any of a file, do this:
WinCvs will now list the known editors of the file.
CVS and WinCvs differ from Visual Source Safe (VSS) in many ways. The most apparent difference may be that CVS does not require users to lock the files they are working on, as VSS does by default. In fact, the CVS documentation even encourages users not to use file locking. In the rare occation where several people have changed the same file at the same time, CVS will normally be able to merge their changes. If two or more developers have changed the same few lines, CVS will report a conflict, insert directives in the file, and leave it to the developers to decide what to do. Such conflicts are very rare, as they normally occur as a result of lacking communication between the developers (eg. two people trying to fix the same problem).
Another important difference is that VSS gives you a server view, while WinCvs shows a client view. In practice this means that, unlike VSS, WinCvs will not tell you about changes in the repository until you do an update, or explicitely query the status of selected files. Changes reported in the file view of WinCvs reflect modifications done by you after the last checkout, update or commit.
CVS is not as "visual" as VSS. When using WinCvs, it becomes quite clear that CVS was a command line driven program for many years before someone decided to encapsulate it in a GUI. Some of us prefer the simplistic approach of WinCvs, which may give a feeling of control for experienced users. Others will hate it. If you're one of the haters, feel free to improve the program and contribute your changes back to the community. :-)
The original CVS doc 1.10.6 that we reference is written by Per Cederquist et al.
You may find its source on the official CVS site at sourcegear.
Brought to you by Computas AS.
We use this guide internally. As we think it may be
of use to others as well, we provide this slightly modified
version on our web site. Feel free to copy it as you wish.