DevGuy's CVS Information

CVS is a free, open-source, full-featured source-code management tool. Source-code management is discussed somewhat in theProgrammers' Canvas Pattern Language.

CVS Hall of Fame

It's hard to believe that everyone involved in CVS is not making a dime fromit. CVS's success is directly attributable to random acts of kindness.

CVS was written in part by Jim Kingdonstarting in the early 1990s. CVS's roots go back even further toRCS. The stewards of CVS graciously donated their considerable efforts to the OpenSource community. Jim has since moved onto bigger and better things, buthis wake is tremendous. Thanks Jim!

Recently the CVS torch has beenpassed to several groups that generally do not cooperate with each other. Tony Hoyle has breathed new life into CVS, rescuing CVS from bureaucracy by maintainingCVSNT.

Finally, Bo Berglund spends a great deal of time answering questions posted to the CVSNT news group. Thanks Bo!

DevGuy's Official CVS Software List

See here

CVS Client Installation

Client installation instructions for Windows

Are your Files in WinCVS Marked "Modified" (Red) Incorrectly?

This is the WinCVS DST bug.

CVS Server Installation

SSH Clients for Windows

See the instructions for SSH access on Windows.

Learn CVS

CVS Commands Reference Card

In order to print these cards you need to use an image programsuch as Adobe Photoshop.

CVS Glossary (Attention Newbies!)

Most newbies are understandably confused by the terms CVSROOT, root, repository, and module. While this section attempts to clear up some of the confusion, it is highly recommended that you refer to the CVS manual as well as other CVS-related sites on the Internet.

A repository is a collection of modules.

A module is a set of files and directories that are stored in a repository. There is a file in every repository called modules located in the CVSROOT module which lists all of the modules in a repository. However, the modules file is optional. CVS essentially creates default module names using the physical structure of the repository. For example, if you have a root directory in the repository called "sam", then you can enter commands using the module name sam, e.g. cvs co sam to check out the module. If you had a subdirectory under sam called bob, you could also enter cvs co sam/bob

There are at least four meanings of the phrases root and CVSROOT:

First, there is the environment variable named CVSROOT, the WinCVS configuration property named CVSROOT, and the -d option accepted by the CVS command line that specifies how to connect to a repository. All of these are referred to loosely as CVSROOT. There are various formats for the CVSROOT value because there are several protocols supported by CVS: local, pserver, SSH, sspi, kerberos, proxy.
Secondly, there is a module in every repository called CVSROOT which contains configuration and administrative information
There is a physical "root" location of a repository. All files in the repository must exist somewhere within the file system, and there is one location called the "root" where all of the repository's files and sub-directories are stored. For example, if you store your repository in c:\cvs, c:\cvs is referred to as the "root." When a repository is created (via cvs -d :local:c:\cvs init), CVS creates a sub-directory c:\cvs\CVSROOT. It is bad form to refer to c:\cvs as CVSROOT, but many CVS users make this mistake.
There is a "sandbox root" which is the top directory of a snapshot of a module or a set of modules. For example, the sandbox root can be c:\sandbox. Modules are checked out into the local sandbox so they can be modified and, later, committed.

CVS Pros and Cons

Filenames to Avoid in CVS

Directories named CVS
Directories named CVSROOT
Anything starting with a pound (#) or a comma (,)

Creating Branches

Use the tag command

Merging Changes from a Branch

See here

Transitioning from SourceSafe to CVS

Brief WinCVS guide: http://www.devguy.com/fp/cfgmgmt/cvs/startup/

SourceSafe users are used to being able to see the repository. For thisyou need to install CVSWEB. http://devguy.com/cvswebnt

SourceSafe users are accustomed to locking files. CVS has the commands admin-l and edit-c that perform reserved check-outs which are generally not called for. It is usually difficult fordevelopers to become comfortable with merging. Here's a link thatdescribes the merits of merging:

http://devguy.com/fp/ProgrammersCanvas/#Prefer_Merging_Over_Locking

Extract Visual Source Safe databases into CVS via the VSSExtractor.

SCM Patterns

Daylight Savings Time (DST) Bug on Windows Clients

(Link as: http://devguy.com/fp/cfgmgmt/cvs/#DST)

There is a bug during daylight savings time which causes CVS clients to think unchanged files have been modified. For example, in WinCVS, the files are drawn with a red font color. This problem can also occur after the transition from DST to not-DST (which occurs during the fall in the United States).

This is a Windows client problem, not a server problem. In other words, this problem happens on Windows clients regardless of whether the CVS server runs on Linux, UNIX, or Windows.

To remedy this:

For WinCVS:

If you use WinCVS 1.2, extract the files from the "patched" WinCVS from the CVSNT Page on top of your existing WinCVS 1.2 program folder. Or, upgrade to the latest version of WinCVS 1.3 (the patch is already in WinCVS 1.3 beta 4 and later).
Follow the CVSNT readme which describes how to turn on GMT mode, or just run this registry file on all clients for each user account that needs CVS access. You need to change the registry on all clients, not on the server. You also must run the registry script from each account that uses CVS on the machine because it's a user setting, not a machine setting.
Run "status" or "update" on all of the folders that you want to fix

For the command line:

Install CVSNT -- you may install the client tools only (cvs.exe and various DLLs). Make sure this version of cvs.exe is in your path rather than an older version.
Follow the CVSNT readme which describes how to turn on GMT mode, or just run this registry file on all clients for each user account that needs CVS access. You need to change the registry on all clients, not on the server. You also must run the registry script from each account that uses CVS on the machine because it's a user setting, not a machine setting.
Run cvs status or cvs update in all of the folders that you want to fix

Note that this might still not fix your problem, but it works for me as well as several other users. WinCVS 1.3 beta and later have the complete fix. Make sure you have run the registry file and have run "cvs stat" on your files before asking for help regarding this issue.

From Jonathan M. Gilligan <jonathan.gilligan@vanderbilt.edu>:

You can get some useful diagnostic information by selecting the incorrectly red file and running the macro "Macros/Tcl/Selection sample". Look at the following three pieces of information: "Modified" gives the binary flag indicating whether cvs thinks the file is modified. If the icon is red, this should be 1. If the icon is red and Modified is 1, then WinCvs incorrectly thinks the file is modified and correctly sets the icon red.

Next we want to see why WinCvs incorrectly thinks the file is modified. Look at "Timestamp" and "File modtime". The former tells us what time CVS/Entries thinks cvs last touched the file. The latter tells us what time WinCVS thinks the actual file modification time is. If these two agree, then WinCVS should not be setting the modification flag.

If they disagree, then you want to check whether WinCVS is calculating the correct file modification time for the file in question. From Windows
Explorer, right click on the file in question and choose "Properties" from
the context menu. Look at the file modification time. You will need to
convert the local time displayed there to UTC (Universal Coordinated Time). If your time zone is "GMT -06:00" then you want to add 6 hours to the time Windows says.

The main bug that has led to incorrectly red files in the past has been that WinCVS computes the file modification time incorrectly.

And here the official Red Icon FAQ by Jonathan:

1) What is the problem?

After the local computer changes its daylight-savings-time state (for mostof the U.S., first Sunday of April and last Sunday of October. See
http://aa.usno.navy.mil/faq/docs/daylight_time.html for details) WinCvs
erroneously thinks that files in the repository are modified when they are not.

2) Who will have the problem?

Only people running WinCvs and/or cvsnt under NTFS partitions. The problemdoes not occur with FAT and FAT-32 partitions. [I'm not 100% sure aboutFAT-32, but I believe that it does not have this problem]

3) Why does this problem exist?

Because Microsoft's Win32 API file status reporting functions report
incorrect file modification dates. According to Microsoft, "This is by
design." Thus, file status functions that work properly under Unix return
incorrect results under Windows. Moreover, the incorrect results are
incorrect in different ways depending on whether the file system is FAT orNTFS. WinCVS and cvsnt correct for this problem on FAT file systems, butthe original authors did not correctly allow for the differences under NTFS.

Microsoft's faulty documentation is more to blame than the hardworking
authors of WinCvs and cvsnt.

4) How can I fix the problem?

There are two steps to fixing the problem:

A) You must obtain corrected versions of WinCvs.exe and cvs.exe.
WinCvs version 1.3b4 or higher and cvsnt version 1.11.1.1 (build 21) or
higher.

B) You must fix the incorrect CVS/Entries files for every directory
checked out on your computer. Server repositories are not affected and
don't need to be changed or fixed.

If you update your cvs/WinCvs, erroneous entries in CVS/Entries files will
cause Cvs to incorrectly believe that the files were modified. Thus, you
must fix CVS/Entries. For the most part, this consists of manually editing
the modification dates on each line of CVS/Entries to set them either aheador behind by an hour.

The simplest way to do this is to run "cvs status" on all your locally
checked out directories. I have seen reports where this did not work. If it
doesn't, then you may need to delete the locally checked out directory andcheck it out again.

I will try to write a Python script to quickly go through a hierarchy of
cvs directories and fix Entries files if they look suspicious. This will
not be foolproof, as there will be a small but finite chance that some
locally modified files will be incorrectly flagged as unmodified. Those are
the breaks.

5) But it still does not work!

If you still have problems with this, please gather the following information:

*Make sure that the file is unmodified. Run "cvs status" on the file (or
"Query\Status" from the WinCvs menu) and make sure that cvs tells you thatthe file is "Up-to-date".

*Run the WinCvs Tcl macro "selection sample" on an unmodified file, that
shows up red, and send the output from that macro with your bug report. Iam particularly interested in the lines that compare the file modification
time recorded in the CVS/Entries file to the file modification time of the
actual file, as reported by Windows.

*Run the WinCvs admin macro "Get the cvs version" and report which versionof cvs.exe you are running.

*From Help\About WinCvs... get the version of WinCvs that you are using.

*What operating system are you using (NT, 95, 98, 2000, XP, Me)? Give meall relevant details (what service pack is your OS...).

*What file system are your files checked out to (FAT, FAT32, NTFS?). I
don't need the filesystem that your repository is stored on, just the
filesystem you have your files checked out to.

*What time zone is your computer set to use?

Send these six pieces of information ("selection sample" output, cvs.exe
version, WinCvs version, file-system, operating system, and time zone) witha bug report to me or to the WinCvs mailing list. I will try to address
bugs as quickly as I can, but I have a day job that keeps me busy, so
please be patient.

What About Bug Tracking?

Try Bugzilla. There are many other free bug tracking systems on SourceForge.

Tool to Move CVSROOT

Changing the CVSROOT is a pain. Sometimesyou need to move the repository to another server, use a different protocol,switch users, etc..

If clients already have files checked out, the move can be a real problem.

But fear not! Run dgfixcvs.pl to update the CVS administrative filesin client sandboxes with the new CVSROOT. Just run it from the root directoryof the sandbox.

This script requires Perl to be installed. Alternatively you can install the executable version here.

Tool to Check for Dangling Internal Locks

Sometimes CVS can die in the middle of an operation leaving dangling filelocks hanging around. Dangling locks can affect subsequent cvs operations.

Run dgfindlocks.plfrom thedirectory that contains the raw CVS files on the server. Run the scriptwhen you know for certain that there will be no activity from your CVSusers. If the script finds locks it'syour job to delete the files, or you can run dgdeletelocks.pl.

Note - these scripts take one parameter, the root directory of your raw CVSfiles. If you use the LockDir option, you should run the scripts twice,once for the CVS directory and again for the lock directory.

These scripts requires Perl to be installed. Alternatively you can install the executable version here.

Read-Only File Attributes

Traditional source control products use read-only file attributes to indicatethat a file is unlocked. Locked files are 'writable.'

Since CVS doesn't lock files, this convention is unnecessary. CVS is very good at identifying which files have been changed so read-only attributes aren't needed. Usecvs stat instead of looking at file attributes, or use dgstatfrom the Programmers' Canvas Toolkit.

WinCVS's 'edit' command makes files writable. If you use WinCVS, I suggest goingto WinCVS's preferences dialog and un-checking 'checkout read-only.' TortoiseCVS doesn't have an'edit' command.

CVSROOT

Here are some sample CVSROOT values, which are either assigned to the CVSROOTenvironment variable or follow the -d option on the command line.

Pserver, CVS server running on [UNI]+X:

:pserver:username@tiger:/cvs

SSH, CVS server running on [UNI]+X:

:ext:username@tiger:/cvs

Windows, CVSNT s

:sspi:tiger:c:/cvs

Pserver, CVSNT server:

:pserver:username@tiger:c:/cvs :pserver:username@tiger:/c//cvs

SSH, CVSNT server:

:ext:username@tiger:c:/cvs :ext:username@tiger:/c//cvs

General

The first thing you need to do with CVS is set your CVSROOT environment variable and then log in
- See the CVS Root section above
- cvs login
You should know about sticky tags
If the login command doesn't work, you should first delete all .cvspass files from all drives and try again.
Always use forward-slashes with CVS commands
All file names are case-sensitive, unless you use CVSNT
To get a list of modules, enter
cvs checkout CVSROOT/modules
If you want to add a new directory at the root, first enter
cvs checkout startThis will prime your root directory so you can enter
cvs add directoryname

Modules

CVS has a concept called a module.

Modules let developers group different directories according to function. When retrieving files from CVS, developers ask for a single logical entity as opposed to several directories. There are many advantages to grouping source code based on logical modules as opposed to the physical directory structure, especially since moving files around in CVS is difficult (if not impossible) once many developers have downloaded the repository to their local machines.

Get a List of CVS Modules

From the command line, enter:

cvs co -c

Downloading Files into a Clean Sandbox

Do not run these commands on your CVS server!

Here is an example that uses the pserver protocol. The-d switch is needed if you don't have a CVSROOT environment variable.

c:\>mkdir sandbox c:\>cd sandbox c:\sandbox>cvs -d :pserver:joe@tiger:c:/cvs login c:\sandbox>cvs -d :pserver:joe@tiger:c:/cvs checkout build
You can get a list of module names by entering:

cvs -d :pserver:joe@tiger:c:/cvs co -c

Then run WinCVS, go to View/Browse Location/Change... and enter c:\sandbox. You can use WinCVS to your heart's content now.

Binary Files

Binary files need to be added to CVS in a special way. If you don't do it correctly, CVS will try to convert newline characters in the file, resulting in a broken binary. The best way to add binary files is to use WinCVS and choose "Add Binary Files" from the Cvs Files menu, or "Add selection binary" from the right-mouse button. Or, enter
cvs add -kb filenameYou have been warned.

If you use CVS import, fix-up the files after the import by entering cvs admin -kb filename for each binary file followed by cvs commit filename

Binary files can not be merged so they must be locked before being edited. File locking is unnecessary for binary files that are rarely modified by the same developer at the same time.

Locking Files

First of all, you shouldn't lock files unless you have to. Locking and CVS don't go together!

Binary files such as graphic images, Word documents, etc., can not be merged. It's likely that such a document will be in contention at some point. The solution is file locking, a.k.a. reserved checkouts. A locked file can not be locked by another developer and it can't be committed by another developer. Files are automatically unlocked when committed.
High contention files can be watched for edits. This scheme follows a publish/subscribe model. When someone intends to change a file, she "edits" it via the CVS edit command and CVS emails a notification to the developers that have set up watches for it. Notifications are sent via email.
Files can be locked and unlocked in WinCVS with "Lock selection" inthe Trace menu.
If you lock a file and later abandon your changes, you must unlock the file with WinCVS or the CVS command line; otherwise the file will remain locked forever.
If you install TCL, you can find locked files in WinCVS using Macros/List Locked Files
Use findlocks.pl to look for files that are locked. This script requires Perl to be installed. Alternatively you can install the executable version here.
On the command line, use cvs admin -l to lock and cvs admin-u to unlock files. When you commit a file it is automatically unlocked.
cvs admin -l is a hack. The newer cvs edit -c is preferable, but not all versions of CVS 1.10 support it yet. CVSNT does. Use cvs commit -c when you're ready to commit.
WinCvs doesn't support edit -c or commit -c, but you can create a file named .cvsrc file in your HOME directory (the HOME environment variable points to it) containing the following:
edit -c commit -c

Unicode Files

UNICODE files must be marked BINARY; otherwise, CVS will corrupt them.

The latest CVSNT server can handle UCS-2 (NT UNICODE) and UTF-8 files. UCS-2 files "cvs add -ku"

Suggested File Types To Not Check In

With the recommended cvsignore file saved to theCVSROOT folder, CVS "import" will automatically filter out files with the following extensions; however, CVS "add" will duly add them.

When using WinCVS's import, unless you copy the above cvsignore to .cvsignore in your HOME directory (note that the filename has a period in front of it), you will have to manually exclude unwanted files.

For COM projects, you should avoid checking in the MIDL generated files:

dlldata.c
<project name>.h
<project name>_?.c

`aps`	`dep`	`lib`	`res`
`bak`	`dpd`	`lnk`	`sbr`
`bpt`	`err`	`log`	`scc`
`bro`	`exp`	`mdp`	`suo`
`bsc`	`get`	`ncb`	`tlb`
`cdb`	`gid`	`opt`	`tlh`
`class`	`idb`	`out`	`tli`
`clw`	`ilk`	`pch`	`trg`
	`jar`	`pdb`	`zip`
		`pjt`
		`plg`

Suggested Tag Naming Conventions

Prefix	Used for...
B	Branch
D	Development build placed by build agent
Q	Release build for QA
R	Release build for public consumption

Don't Delete Files From CVS

Once files become tagged as part of a build, deleting them is problematic since it makes re-creating older builds impossible.

Instead of deleting the file, use the cvs remove command. Use the -f option.

To obsolete an entire directory, remove all the files from it.

Adding New Projects to CVS

After adding a new project, you *must* checkout the project from CVS and attempt to build it. It's very likelythat a binary file got added as a text file, or a required file didn't get addedfor one reason or another.

First, delete files that you don't want to check in

Optionally, create a new CVS module

modify the file CVSROOT/modules (use CVS to do this) as described in Starting a Project with CVS
Read the comments at the top of this file for more instructions

There are two ways to check in new code: manually and automatically. Automatic is the easiest way.

Manual: Create a new directory

Create the new directory in your sandbox.
Change current directory to one level above your new directory.
cvs add <dirname>
Proceed to the next section to manually add each file.

Manual: Add files to the repository

Change current directory to the directory containing your new files in the sandbox.
cvs add <filename>
cvs commit
Note: Binary files need to be added in a special way. The best way to add binary files is to use WinCVS and choose "Add Binary Files" from the Cvs Files menu, or "Add selection binary" from the right-mouse button.
See the list of file types to check in and not check-in. Note: CVS import automatically filters out files that aren't supposed to be checked in.

Automatic: Import

Use WinCVS or the "cvs import" command to import the files

Import Command - Warning!

The import command was meant for importing third-party files into the repository. When you use 'import', CVS creates a branch on which all checkouts and commitsoccur. This separates your organization's changes from that of the vendors, which allows you to merge in changes made by the third party later.

The branch that CVS creates becomes the new module's default branch, meaning that whenever the module is checked out, CVS retrieves revisions on the branch rather than on the trunk. Again, it's assumed that only the third party vendor's changes appear on the trunk.

This model, although convenient, is unnecessary when you use "import" as merely a convenient way to add new folders to the repository. In this case you want to make the trunk the default branch. Here's how to do it:

Import a module to CVS
Check out the new module from CVS
Change your current directory to the directory containing the new module in your sandbox
Run the following commandcvs admin -b
Update your sandbox
cvs update -A newmodule

This is a fast way to create a module and ensures that you (and everyone elsewho does a subsequent checkout) will be poised to work on the trunk.