Inside a Depot: Versions and Files

Let’s look inside a depot, to examine its architecture. This will help explain how AccuRev works, and will illuminate some of its most important, and unique, features.

Developers working on their files is the principal activity in any software development environment. With AccuRev, a developer’s files are stored in an ordinary directory structure — perhaps on the hard drive of a personal computer or laptop, perhaps in a designated area of a well-backed-up disk farm, etc. The only thing special about this “developer’s work area” is that AccuRev keeps track of its association with a particular depot. (The work area is called a workspace — for more information, see AccuRev Workspaces and Reference Trees.)

A developer can use any software tools to create and edit files, compile and build modules and applications. AccuRev doesn’t get involved in these operations at all, so there’s no performance penalty. Every so often, the developer tells AccuRev to save the current contents of a file (or a group of files) to the depot’s repository. This operation, called a keep, does two things:

•	Copies the current contents of the file to a container file in the depot’s file storage area.

•	Creates an associated version object in the depot’s schema.

This association is permanent: no matter what happens in the future, the contents of the file will always be available, through a reference to the version object. (For now, we’ll skip the details of how to specify a version — it’s just a bit more complicated than saying “version 45 of file gizmo.c”.)

In addition to providing access to the actual file contents, the version object stores additional information relating to the “keep” operation: the date and time of the operation, the user who performed the operation, a user-supplied comment, etc. This kind of information is often termed “metadata”.

In general, version objects are much smaller than the corresponding container files. (Developers often work with large source files; they also work with audio, image, and multimedia files, which are often even larger.) As developers create more and more versions, the depot’s file storage area may grow to many gigabytes, requiring it to be split among multiple disk drives. But since the metadata stored for the depot contains the relatively small version objects, it grows much more slowly. Most likely, it will never outgrow its original storage location.

Versions of Non-File Objects

In all modern operating systems, files are organized into directories (or folders). Some operating systems also support additional kinds of file system objects: symbolic links, hard links, device files, named pipes, etc.

AccuRev provides full version-control of directories. A new version of a directory records the renaming of the directory or the moving of the directory to another location in the depot’s directory hierarchy.

AccuRev provides file-link and directory-link objects, which can be used to version-control hard links and symbolic links / junction points.

Promotion: Real Versions and Virtual Versions

Software development is much more than just creating and modifying files. A typical development project involves many phases, possibly including initial development, integration of work done independently, internal system testing, external testing, and final production. AccuRev uses a “promotion model” to manage files in these multiple development phases. Files progress through the phases, one by one: when a set of files pass the tests (if any) mandated for a particular phase, a user working on that phase promotes them to the next phase.

AccuRev keeps track of each promotion by creating a new version of each promoted file. But promotion doesn’t change the contents of a file; it only changes the file’s “approval level”. Thus, each new version object created by promotion is merely an additional reference to (or “alias for”) the same file in the depot’s file storage area.

AccuRev distinguishes between the original version, created by a keep operation, and all the additional versions created by a promote operation:

•	A real version is created by operations like keep, add, merge, rename, etc. The operation creates a new version object in the metadata stored for the depot and places a new file in the depot’s file storage area.

•	A virtual version is created by a promote. It creates a new version object in the metadata stored for the depot, which provides an additional reference to an existing file in the file storage area. Conversely, a demote operation removes a virtual version.