Volume Number: 14 (1998)
Issue Number: 6
Column Tag: Tools Of The Trade

Version Control and the Single Developer

by Richard Wesley

How Version Control Can Make Your Life Safer and More Productive

So here you are, writing the next great application in your basement. Maybe you are by yourself, or maybe like me you only have one other developer to worry about. Why should you bother with version control software? After all, you are probably use to being able to modify anything you want at any time, and the worst you might have to do is yell across the room "Dave - I'm going to work on the filter code now, so don't touch it until I'm done!" Why give up all this freedom?

This article will attempt to convince you that there are many practical reasons to use version control, even if you are just by yourself. Here at Electric Fish, we develop many small projects for clients that require only one developer, yet we use version control for every project. This article is intended to introduce the basic concepts of version control and discuss what specific problems it can solve for you, the small developer.

In this article, I will present all the basic version control commands and discuss the problems that they solve. I will be using the CodeWarrior Version Control menu terminology as it provides a simple interface to an abstract version control system, and I will using examples from various source control systems, including Projector, CVS, Perforce and PVCS, all of which have CodeWarrior VCS plugins.

Version control systems are a means of tracking various versions of a set of files. Most of them also include facilities for tracking groups of files (although PVCS does not). All of them deal with the issue of interaction between developers, although there are many different ways of doing this. All systems have some notion of a database that stores the various versions of a file.

There is a general sequence of events that happens when you use most version control systems.

• First of all, a database must be set up somewhere. This may be on a local file system (Projector, PVCS) or on a TCP file server (CVS, Perforce) or somewhere else. Generally, all you need to know is where it is. This is the Connect operation.
• Now that you have a database, you need to be able to add files to it. This includes all the files you have now and any new files you may wish to add. This is the Add operation.
• Once you have files in the database, you need to be able to modify them. Some systems require you to tell the database you are working on them, but some (like CVS) allow you to just modify the files at will and submit all the changes when you are done. This is the Checkout operation.
• If you change your mind, you may want to revert to the last state of the file. This is the Undo Checkout command.
• Once you have made your changes and tested them, you need to put them back in the database for safekeeping and so that others can see them. Generally, this involves giving the database not only where the new version is, but also a description of what you did. This is the Checkin operation.
• After all the changes have been made and the software is ready, it is common practice to label all the file versions that go into the shipping version so that they can be referred to later. This is the Label operation.
• At some point, you may wish to go back and look at older versions of a file or groups of files, or you may simply wish to get the latest versions of all the files in the project after a coworker has made some changes. This is the purpose of the Get operation.
• After a while, a file may become obsolete or need renaming. These are the Rename and Delete operations.
• Version control systems can generate various useful reports about files. These are the Difference, History, Properties and Status operations.
• There are a few more operations provided for in the CodeWarrior IDE, but we will not be dealing with them. Included in this list are Variables, Comment, Rollback, Destroy and Purge.

These are the basics of version control. Here is how it can make your life more pleasant and productive. To facilitate the discussions, each operation will be introduced by a particular problem that it solves. I suspect that some of these problems frustrate you on a regular basis.

Why can't I mount my hard drive?!!

One of the most important things that version control can do for you is automatically make copies of your work on a drive or machine other than your development drive. Your development drive takes a lot of abuse, and having a copy of your work on another disk increases your safety margin. Not that you should use this in place of a regular backup strategy, but it can help.

You could do this the old fashioned way by making copies of your source tree, but most version control systems make this a lot easier and less confusing. We have all run into the old "Which copy of the source tree is this?" With a version control system, you have all versions of your files in one place and you can not only determine which source tree you have, but you can obtain any source tree you ever had.

The most important source tree is, of course, the latest version. With version control you (and anyone you may be working with) never has to ask "Where is the latest version of the code?" This is the purpose of the Connect operation -- to connect you to a separate copy of your work that is well organized.

Am I using this file?

We have all been in the situation of wondering whether a file is actually being used. The problem is that once we figure it out (usually by moving it and seeing if the project will still build!), we have only our memory to rely on when we ask the question again two weeks later. This is the purpose of the Add operation -- it allows us to mark a file as being used when we first create it.

Conversely, you may determine that a file is no longer needed in a project for some reason. This is the purpose of the Delete operation. Delete does not remove old copies of the file from the database, it simply says that this file will not be needed in future versions of the project. All the old versions are still there, but you need to perform some special request to get it back. Most systems will even allow you to resurrect files if you later decide you need them again.

I didn't mean to change that file!

One of the things that I particularly hate about every development environment I have ever worked with on desktop computers is that the library header files provided by the compiler vendor are not locked. All it takes is for one of my cats to walk across the keyboard and there goes Menu.h or something.

At least I have the vendor's originals safely burned onto a CD somewhere. More likely though, I will open a project file to look at something, get lost in the mess of windows I usually have open at one time, and blow away something important. It really helps to have to deliberately say "I want to modify this file" before you can do so.

This is the purpose of the Checkout operation -- it allows you to be deliberate about what changes you make. Some systems (like Projector) even allow you to enter a comment describing what you plan to do when you do a Checkout which can be very useful when it comes time to check in all the files for a major change.

Some readers may be wondering why we haven't discussed the other common meaning of Checkout, namely that the file is marked so that no one else can modify it until the developer doing the Checkout releases it. Projector works this way, but many other version control systems do not. CVS just merges your changes back into the database version, which is why in CWCVS I made the Checkout operation simply unlock the file - to preserve this deliberate decision to modify a file in a system that nominally allows you to modify anything at any time.

What was I thinking?

Of course, sometimes even with the best of intentions we decide to do the wrong thing and wish we could go back. This is the purpose of the Undo Checkout operation -- to gives you a higher level of undo related to the conceptual changes you were making to the file. Even if you were to use file locking and unlocking to be deliberate about your modifications, you would still have to go find you last copy of the source tree if you decide that you have made a mistake. With version control, this is a simple problem to solve.

Have I backed up the changes to this file?

If you are working with copies of your source tree, there is always these issues of "When do I make a copy of the tree?" and "Where do I save it?" and "What do I call it?" And even if you solve these problems somehow, you then come back the following week and wonder "Now when did I break that dialog box?"

This is the purpose of the Checkin command - to mark when conceptual changes have been made to a file by commenting them and backing them up. When you check a file in to a version control system, you are making a copy of the current state of a file that you can refer back to later. Most version control systems allow you to describe the changes that were made (some, like CVS, even require you to do so) which can be very useful for answering the dialog box question above.

Some systems (like CVS and Perforce) even allow you to check in groups of files all at once. If you have finished making changes to five files that all solve the same problem or implement the same feature, this can be very handy. The CodeWarrior term for this is Recursive Checkin, meaning that all checked out files found recursively in the project source are checked in together. Perforce even guarantees that this is done atomically (that is all or nothing.) For systems that do not have this operation (like Projector and PVCS), CodeWarrior helps you to fake it by selecting all the changed files in the IDE, choosing Checkin and then allowing you to indicate that the Checkin comment should be the same for all of the files.

Where is the source tree for Beta 1?

So you're in the beta cycle and you're up to Beta 3 or something and a user who still has Beta 1 finds a nasty bug that you can't reproduce in the latest version. This means that you want to find the source tree you saved with Beta 1 to help track down the problem. What did you call it? Where did you put it? Did you delete it when Beta 2 came out? This is the purpose of the Label command -- to allow you to collect file versions into functional groups.

The most common group is all the files currently in the project, and CodeWarrior's term for naming this groups is Recursive Label, meaning that all files found recursively in the project source will be collected together into a group. This is how you would find the Beta 1 source code you need. Moreover, since the database only stores changes, you probably wouldn't need to throw out Beta 1 to make room for Beta 2!

It is also useful at times to label a few file versions that are related before you go and rewrite a subsystem. Suppose you change the way you implement your toolbar, and you would like to be able to refer back to the old toolbar implementation. You could collect all the file versions in the old implementation together into a group for later reference. Then if you ever wanted to go back and look at that implementation, you could refer to them as a group without disturbing the rest of your code.

How did I do that?

Have you ever wished you could go back and look at an older version of a file? Maybe you are having second thoughts about part of how you solved a problem, or maybe a file just got thrown out by accident. This is the purpose of the Get operation -- to retrieve versions of files from the database. The most common version you might wish to retrieve is the latest version, but you can Get any version of a file that has been checked in to the database. If you are working with other developers, the Get operation is also used to retrieve your co-worker's latest changes to a file.

From time to time, you just want to get a copy of everything in the database as it currently stands. The CodeWarrior term for this is Recursive Get, meaning that all files found recursively in the project source are retrieved. This can be very handy for quickly moving your workspace onto another machine or drive. it is also how you retrieve saved groups of files created with the Label operation.

When did I do that?

Bugs don't always show up right away. Trying to determine when you introduced a change and what you changed can be very difficult if you are using copies of your source tree. Often, the actual change you are looking for is no longer around, or if it is, you have no way of tracking it down other than a vague memory of which week you think you made the change. This is the purpose of the History operation - to provide a list of change comments and dates in the order that they happened. From such a list you can usually easily determine when you made a particular change and go right to the version of the file that you need.

What did I change?

We have all used file comparison utilities to try to determine what innocuous looking change caused that horrid problem. This is the purpose of the Difference operation -- to allow you to easily compare various versions of a file. One very common variation on this is to compare your working version with the last version in the database. Using source trees, you would have to find the correct older version and run a file-compare utility, but since most version control systems store actually store the differences between files (called "deltas"), telling you what has changed is second nature to them. Moreover, because the files are all in once place, it is very easy to just point to a pair of revisions and get an answer.

Now that I have (hopefully) convinced you that version control is a good idea, it is time to move on to deciding what system you should use. There are a number of considerations you should bear in mind while making this decision, including price, features, ease of use, support, server and platform.

MPW Projector

Projector is great. It is stable, fully featured, free, widely available supported by Apple and easy to set up. Its biggest liability is that it is a Macintosh only product, which is only a problem if you are doing cross-platform work and can't do all your development on a Macintosh. Another small problem is that the Difference operation is implemented via MPW scripts instead of by a specific Projector command.

There are various levels of ease of use. You can use Projector from MPW via command line directives and scripts; you can use ToolServer/SourceServer to script it from inside CodeWarrior and other ToolServer friendly applications; you can use the ProjectDrag applets (on the Developer CDs) to manipulate files in the Finder; or you can use our shareware CWProjector plugin/SourceServer combination in CodeWarrior and talk to it through the CodeWarrior VCS menu. There is also another shareware CodeWarrior plugin called ProjectorVCS available from http://www.joyspot.com.

Projector is a file-based system, which means that the databases are just files on a mounted volume (usually a server). This means that there is no special hardware (e.g. a POSIX server) to set up and backup is as easy as backing up any other drive. You can also work off-line with Projector and just check in any files that you made writeable when you get back on-line.

GNU Concurrent Version System

CVS is a widely used POSIX based version control system. In the past year, two Macintosh clients have been written and under the terms of the GNU license, both are in the public domain (read "free"). CVS is unsupported, but there are many on-line resources for getting assistance, including the info-cvs@gnu.org mailing list, the comp.software.config-mgmt newsgroup. and the Cyclic web site http://www.cyclic.com. You can also grab the source and do your own thing if you like -- as far as I know there is no MPW tool for CVS.

CVS is very different from Projector. For starters, it uses a copy-modify-merge paradigm, which means that you can modify any file at any time and then submit all your changes to be merged back into the main database when you are ready. CVS is also TCP-based, which means that you must have a POSIX machine with a cvs daemon running in order to use it. This has advantages - CVS is also kerberized, which means that you can use the MIT Kerberos protocols to talk to a server securely over the internet, which can be very useful if you are working remotely for a client. CVS is also available on just about any platform you can think of, which makes it a good choice for cross-platform development. On the down side, setting it up can be a bear for Macintosh users and doing repository backups requires working with some sort of POSIX backup system. It has been suggested that one could use an AppleShare client but we have not tried it.

Ease of use comes down to choosing a client. I use the MacCVS 3.0 client developed last year at Strata (available at the Cyclic site) and our shareware CodeWarrior plugin that talks to it. You can also interact directly with MacCVS via various menu options and command-line windows. MacCVS is based on the GNU source so it will be able to track changes easily.

The other client I know of is MacCVSClient-1.3.3 written last year at FontWorks (also available at the Cyclic site). This is a threaded PowerPlant application that knows the cvs pserver protocols but as far as I can tell, it only works with pserver and does not support Kerberos. Because it is not based on the GNU distribution, it is not clear how it will track future changes. On the other hand, it has a fabulous GUI, seems very easy to use (no mean feat for CVS!) and looks really sharp. At the moment, the two client authors and I are all talking vaguely about integrating the Strata back end, the FontWorks front end and the Electric Fish plugin, but this will probably not happen any time soon.

Perforce

Perforce is a nice commercial system from Perforce Inc. (http://www.perforce.com) that runs on a wide variety of platforms. The demo version of the system is a two-workspace license, which means that it is free for single developers. Because it is a commercial product, it is supported and updated, but unless you pay for some sort of license, you will not be able to get much help from them (fair enough). Their documentation is all on line at the site and also comes with the demo package.

For clients, Perforce has both an MPW tool (p4) and a CodeWarrior plugin (CWPerforce). The p4 tool is a bit awkward to use as it launches a local client application, but the plugin (which I wrote) can perform most basic operations from within CodeWarrior. You will still need to use the MPW tool for more complex operations.

Perforce is a TCP-based system and requires a non-Mac server. It has no security features that I am aware of, so it is only good for in-house development. We used the Linux version to develop the plugin with no problems.

VOODOO

Aside from the Perforce free demo, VOODOO (Versions Of Outdated Documents Organized Orthogonally) from Uni software (http://www.unisoft.co.at) is currently the cheapest ($229/seat) commercial system available for the Macintosh. Like Projector, it is a Macintosh only system and stores databases using the file system. VOODOO runs as a standalone application and is integrated with both CodeWarrior and BBEdit.

VOODOO's orthogonal organization scheme was described in the December 1996 MacTech article "Keeping Things Straight, Orthogonally" by Christoph Reichenberger. There is a free demo that you can download from the web if you would like to investigate it further.

Other systems

I know of two other version control systems with Macintosh clients, both commercial. Pricing on them is high (over $400/seat) but they may do exactly what you need.

Metrowerks sells Visual SourceSafe, which is (of course) well integrated into the CodeWarrior environment and is based on Microsoft's Visual SourceSafe product. SourceSafe can be used in a cross-platform environment with Windows developers using Microsoft Visual SourceSafe.

PVCS Version Manager from Intersov is another widely used cross-platform system for tracking individual files. Synergex ported Version Manager to the Macintosh last year and they are currently working on a CodeWarrior plugin. PVCS is very powerful and flexible, but configuring it is not for the faint of heart.

Conclusion

Until about two years ago I had never used version control. I had worked at several small companies all of which used the source tree method referred to above. I even had one manager tell me in a meeting to temporarily restrict new features in a cross-platform application with #ifdefs because they were "the sign of professional code"!

The first time I used version control was on a project in MPW with four developers and I was amazed at how smooth it made our interactions. To be sure, Projector's locking occasionally caused conflicts, but compared to what I was used to, it was heaven. About a year after that project ended, we started Electric Fish with a port of a big Windows graphics package and we decided to use Projector and the ProjectDrag applets (this was before CodeWarrior added version control capabilities) It was so pleasant that we have never looked back, and we started using it for every small project that came along, even if only one of us was working on it. Eventually, we were using Projector so much that last summer I decided to write a Projector plugin for CodeWarrior.

Every day, my partner thanks me for convincing him to use version control. I hope that I have convinced you as well.

Richard Wesley, hawkfish@electricfish.com, is a Software Development Consultant and Co-President of Electric Fish, Inc. He has been developing Macintosh software since 1984 and is the author of the CWProjector and CWCVS version control plugins for CodeWarrior.