oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Version Control on Mac OS X, Part 1

by Kevin O'Malley

Editor's note: Previously, James Duncan Davidson explained how to share information among your personal Macs using CVS in his article In Sync with CVS. But at heart, CVS and other version control tools are vital for projects that involve multiple developers. As the Mac continues to gain favor in the developer community, we thought that a complete overview of version control would be a useful series residing on the Mac DevCenter. Kevin O'Malley begins this exploration today with a look at what version control is, its terminology, what systems are available under Mac OS X, and some basic examples.

Imagine the following scenario. You are part of a development team that is writing a new compiler. The team is composed of two developers: you and Bart. You will work on the front end of the compiler: lexical and syntax analyzer, and parser. Bart will implement the back end. The project uses many shared files that perform common operations, such as debugging and logging. These files are placed in a public directory that developers copy to their local workspace as needed.

Suppose Bart implements a shared library for logging and places it into the shared space; other developers copy it and use his library. Over time, Bart adds more functionally, each time copying the new versions to the shared space. One night before going home, Bart fixes several bugs in the library and, as usual, overwrites the version in the shared space with the new version. Bart takes off for the night. Later that night, you copy the new library to your local space, overwriting the current version, and continue development. The problem is Bart did not test his changes and has introduced bugs into the library that break your code. Now you're stuck, because you overwrote your previous version and Bart is gone for the night. At this point, your work stops until Bart comes in and fixes the bugs.

Now, imagine Bart returns the next day, finds out there is a problem and begins fixing the bugs. After a while, he sees that there are to many problems, and decides to return to an earlier version. Unfortunately, his last backup was a week ago, and many changes happened over the week. His only choices are to start over from the old version or debug the latest copy.

This is by no means how most projects are run, but there is some truth to this (somewhat contrived) example. In fact, I'm sure we have all been on projects where this has happened. What this example illustrates is that projects run without some form of software management can be costly, error-prone, and very not much fun.

A response to managing a project in this way is to implement some form of version control. Version control is a simple and effective process that will support any development effort -- from single-person to large projects. If you are not using version control now, or have never used it on a project, here's your chance.

This is the first of a short series of articles designed to give you all of the information you need to understand the basics of version control and show you how to easily integrate it into your development process. Knowing this will not only help you in your own projects, but also enable you to join and contribute to open source projects, where version control software is commonly used to access project source files and create releases.

This article presents the basics of version control by exposing you to what version control is, its terminology, what systems are available under Mac OS X, and some basic examples. The second article applies this knowledge by showing you how use Concurrent Versions System (CVS) and its commands under Project Builder, Apple's freely available Integrated Development Environment (IDE) for writing Mac OS X applications. The final article presents some advanced CVS topics for creating and managing software releases, tips for using CVS with Mac OS X, and concludes by comparing the CVS command-line interface with Mac OS X GUI-based interfaces such as Project Builder and BBEdit.

After reading this series, you will be well on your way to adding version control to your development process, and understand what it takes to use CVS under Mac OS X.

What is Version Control?

Let's start by looking at what version control is. At its most basic, version control is a process, supported by software, that helps you record changes to your project's source files, manage releases, and control access to shared files. Most projects implement some form of version control, even if its just tar-ing up your project directories at defined points of the project. The truth is, without some form of version control, your project can easily become a tangled mess and become very difficult to manage as it grows.

By using version control software, you facilitate the efficient management of the modification and revision history of files throughout a project's life cycle. Version control is a topic within a discipline of software engineering called Software Configuration Management (SCM). SCM is a mechanism, instituted through defined processes, whose goal is to ensure the classification, control, and traceability of a software system, throughout its life cycle. It is implemented using software tools and procedures designed to address these objectives. Configuration management was rooted in the defense industry of the early 1960s, and was an early attempt by management to control the increasing complexity of designs and the design process.

Conceptually, think of version control in similar terms as static code analysis (compiler warning or lint tools). For example, turning on compiler warning messages to their highest level tells the compiler to check for language and programming constructs that are potentially dangerous or may lead to runtime errors or unexpected results. This effectively places a net under your build cycle and provides you with some assurance that subtle errors will be detected upstream, at compile time. Adding version control provides similar assurances for your development process by providing support for managing many important elements of your project's life cycle.

For example, version control enables you to go back to past versions of your source code and create and administer releases of your program, and helps mediate source code changes on multiple-developer projects. In essence, it provides you with a proven mechanism for solving many software management problems that, in the past, most of us have resolved with different homegrown, sometimes chaotic, techniques.

The default load of the Mac OS X system does not include RCS or CVS -- they come with the Apple developer tools. To get and install the developer tools on your system, you need to register for a free Apple Developer Connection (ADC) account.

One of the first version control systems available on the UNIX platform was Source Code Control System (SCCS), developed by Marc Rochkind at Bell Telephone Laboratories in 1972. At the present time, the two most popular version control systems from the UNIX world that operate under Mac OS X are Revision Control System (RCS), written by Walter F. Tichy in the early 1980s while at Purdue University, and Concurrent Versions System (CVS), which is built on top of RCS and uses many RCS programs to perform its actions. Both RCS and CVS are available for Mac OS X. You install them as part of Apple's developer tools.

A primary difference between RCS and CVS lies in how they interact with multiple users. RCS implements the so-called "lock-modify-unlock" model (see Open Source Development with CVS, 2nd Edition, by Karl Fogel and Moshe Bar) where a single developer acquires exclusive write access to a resource through file locking. When a file is checked out, RCS places a lock on the file, which prevents anyone else from checking out and writing to the same file (though it can be checked out for reading). Once the file is checked back into RCS, the lock is released, enabling others to check out and edit the file. This model simplifies version control and sidesteps many unnecessary problems. For example, multiple developers editing a file simultaneously can lead to one developer breaking the other's code. Single checkout forces them to talk to each other and resolve any conflicts before changing code.

CVS, on the other hand, make use of "copy-modify-merge." (Also see Open Source Development with CVS, 2nd Edition, by Karl Fogel and Moshe Bar). Here, multiple developers are allowed to check out, edit, and check in the same file. If conflicts occur, CVS records them and attempts to merge the changes into each developer's code base. Conflicts can arise, but they are usually simple to resolve. This technique permits many people to work in parallel and CVS will fold in each developer's changes as necessary.

Both CVS and RCS are excellent choices for version control systems. Both are enormously popular, exceptionally stable, and are available under Mac OS X. For this series of articles, we will use CVS as our version control system.

A CVS Example

Now that you understand the fundamentals, let's look at some basic CVS terminology. CVS stores the complete modification history of your project in a central location called a repository. The repository acts as a storage area for all of the different versions of your files placed under version control. In fact, a single repository frequently holds several different projects. To track a file's modification history, CVS does not store the complete version of each changed file, but only the differences between files. These differences, or revisions, are just the modifications between each successive version of a file. Storing only the differences between files is a compact and efficient mechanism for recording a file's change history. The most current version of a file stored under CVS is called the head version. Each different version of a file is called a revision.

Let's look at a very simple example of how you would use CVS on a project. Imagine you plan to develop a new Cocoa program. First, you launch Project Builder, select New Project, and create your new Cocoa application. After creating your project, the first thing to do is tell CVS to place the project under version control. By doing this, you inform CVS to begin tracking your project throughout its life cycle. To place your project under version control, you check in, or import, your new project into CVS as the first version of the program. Then you check out the project, which copies the project files, as well as some CVS administration files, to your local workspace. The details of the administration files are not important; they are used internally by CVS to track changes to your project. Now, you have the first version of your program under version control and a local copy that you can develop. The local copy is called your working copy.

Once you place a project under version control, CVS takes on the role of tracking changes to your files and managing its stored history. However, CVS is a passive, not active, system. In order for CVS to do its job, you need to provide it with information along the way. For example, as you begin development, adding functionally and features to your program, you will want to tell CVS about the changes so it can add them to your project's history. To do this, you commit your changes to CVS, and CVS records them to the project's repository.

As development continues, you add files to the project and possibly remove files from the project. This information also needs to be conveyed to CVS. To add a file to CVS, you first add the file so that CVS knows about it, and then commit the file, which tells CVS to include it to your project's history. CVS also supports the deletion of files through the remove command.

Throughout the course of the project, you may wish to get information on the various files under version control. For example, imagine that you wish to see what changes were made between two revisions of a file. To accomplish this, you use the CVS diff command, which compares the specified files and displays their differences.


Concurrent Versions System (CVS Home)

Official RCS Homepage

Software Configuration Management (SCM), The Software Engineering Institute (SEI)

"Applying RCS and SCCS," by Don Bolinger and Tan Bronson

Open Source Development with CVS, 2nd Edition, by Karl Fogel and Moshe Bar

CVS Pocket Reference, 2nd Edition, by Gregor N. Purdy

"Top 10 CVS Tips," by Gregor N. Purdy

"RCS - A System for Version Control," by W. F. Tichy, Software - Practice and Experience, vol. 15, pp. 637-654, 1985.

Configuration Management (Trends in Software, No. 2), by Walter F. Tichy (Editor)

Once the first version of your program is ready to go, you need to create a release. CVS has two commands to help you accomplish this: the tag and branch commands. I will cover both commands in detail in the final article, but briefly, a tag is a label you give to a set of related files in your project. As you continue developing the working copy, and commit revisions to CVS, the tag remains fixed, or stuck, with its associated files. At any point, you can retrieve all files associated with the tag with one CVS command. Branches enable you to create and manage different versions of your software (release versions, debugging versions, optimized versions, etc.) without disturbing the code you are currently developing.

As I said earlier, CVS was designed to handle concurrent editing of files. In this example, that's not an issue. However, on multiple developer projects, a common task is getting files that other developers have added to the project, and getting new changes to existing files. To accomplish this, you tell CVS to update your working copy. The update command copies any new files in the repository to your working copy, and updates any existing files with the newest revisions in the repository. Because CVS implements "copy-modify-merge," it attempts to merge any new versions of a file with your working copy. If conflicts occur, CVS will mark them, and it's up to you to manually resolve the conflicts.


This article has tried to convey the basics of version control by describing what version control is and how it can help you on a project. CVS is a very good version control system that is very powerful and is freely available under Mac OS X. In future articles, I will show you how to apply this knowledge by developing a Cocoa program under Project Builder, and how to use CVS to manage software revisions and releases.

I hope you have enjoyed this brief introduction to version control and CVS, and are looking forward to learning more. Make sure you check out the Resources section for more information on SCM and version control systems.

Kevin O'Malley is a long time Macintosh and UNIX developer. His articles have appeared in Dr. Dobb's Journal, IEEE Internet Computing, and The Perl Journal, and he is the author of Programming Mac OS X: A Guide for UNIX Developers.

Return to the Mac DevCenter.