With the usage model described above, you’ll be able to accomplish most of your AccuRev work with four simple commands:
Keep,
Promote,
Update, and
Merge. We describe these commands in the following sections. Each section has a subsection titled “The Fine Print”, in which we present additional usage details, notes on the way AccuRev implements certain features, and other items of interest. You might want to skip over these sections on your first reading of this material.
Keep: Preserving Changes in Your Private Workspace
An AccuRev workspace is just a normal directory tree, in which you make changes to version-controlled files. You can work with the files using text editors, build and test tools, IDEs, and so on, just as if the files were not version-controlled at all. For example, you might edit a source file and invoke the editor’s
Save command a dozen times over the course of an hour or two. These operations do not involve AccuRev at all — the operating system changes the contents and the timestamp of the file in your workspace.
You do not need to perform a “check out” operation or otherwise get permission from AccuRev before editing a file in your workspace. (Some legacy SCM systems do impose such a regimen, and AccuRev can be configured to require checkouts, if your organization requires them.)

Every so often, you want AccuRev to preserve the current contents of the file as an official new
version of the file. You accomplish this using AccuRev’s
Keep command. This figure shows how to invoke the
Keep command from a file’s context (right-click) menu in the AccuRev File Browser tool. You can also invoke
Keep with the

toolbar button.
You can continue modifying the file, using Keep to preserve the latest changes, as often as you like. Other team members will not complain about “thrashing” because these new versions stay within your workspace and do not affect any other user’s workspace.
AccuRev retains all the versions that you
Keep. This makes it possible for you to roll back to any previous version you created.
Several other operations are similar to Keep, in that they create a new version of a file in your workspace, without affecting any other user’s workspace. The most important are:
•
|
Rename/ Move: You can rename a file or move it to a different directory (or both), using AccuRev commands. Other users will continue to see the file at its original pathname in their workspaces.
|
•
|
Defunct: You can remove a file from your workspace with the AccuRev command Defunct. Other users will continue to see the file in their workspaces.
|
We said earlier that AccuRev “retains all the versions that you
Keep”. But where? Each time you
Keep a file, its current contents are copied to the AccuRev repository, located on the machine where the AccuRev Server runs. You do not need to care about the name and precise location of this copy. Each version you create has a
version-ID, such as
talon_dvt_john/12 (“the
12th version of this file created in workspace
talon_dvt_john”).
AccuRev keeps track of the
status of each file in a workspace. After you
Keep a file, the Status column in the AccuRev File Browser contains the indicator
(kept). It also contains the indicator
(member), meaning that the file belongs to the set of files you are actively working on. (See
Active and Inactive Files for more information.) The Version column displays the version-ID.
A change to the data within a file, recorded by Keep, is termed a
content change; the change made by
Rename/
Move or
Defunct is termed a
namespace change. (Many SCM systems do not handle namespace changes at all, or have very limited capabilities in this area.) As noted previously, AccuRev saves a new copy of the file in the repository whenever you make a content change. But it does not need to copy the file when you make a namespace change; rather, the AccuRev Server just records the change in its database.
To perform version control on directories, AccuRev only needs to keep track of namespace changes — renaming, moving, or deleting a directory. Unlike some legacy SCM systems, AccuRev does not need to record a new directory version when you make a content change — for example, adding a new file to the directory.
Promote: Making Your Private Changes Public

At some point, after you have used
Keep to create one or more new, private versions of a file in your workspace, you typically want to share the changes you have made with the other team members. To make your (most recent) new version “available to the public”, you
promote it. This figure shows how to invoke the
Promote command from a file’s context (right-click) menu in the AccuRev File Browser. You can also invoke
Promote with the

toolbar button.
Promoting your new version of a file does not automatically “push” it into the workspaces of the other team members. When a user decides that she is ready to incorporate versions of files that other team members have
Promoted, she “pulls” them into her workspace with the
Update command. This process is described in the following section.
The Promote command sends data to — and the
Update command gets data from — an AccuRev data structure called a
stream. The stream acts as a central data exchange for the set of workspaces used by a development team. A stream also has a bit of “traffic controller” built in, preventing team members’ efforts from colliding and providing other mechanisms to control the flow of data.
In SCM vernacular, a stream is a configuration of a collection of version-controlled files. The term “stream” is apt, because it implies the ongoing changes happening in a development project. Each time a user promotes a version of file
brass.c, the stream configuration changes for that file — for example, from “the 5th version created in workspace
talon_dvt_derek” to “the 7th version created in workspace
talon_dvt_mary”.
Sometimes, AccuRev does not allow you to promote a file to the development team’s stream, because another team member has already promoted the same file (after modifying it and performing a
Keep on it). AccuRev prevents you from overwriting your colleague’s change to the team’s shared stream. This situation is called an
overlap: two users working at the same time on the same goal, to create the stream’s next version of a particular file.
As you work with a file using the commands described above, AccuRev considers the file to alternate between being
active in your workspace and
inactive:
Later, you might restart this cycle, making the file active again by creating another new version of it. Alternatively, an update of your workspace might overwrite your inactive file with a newer version that another team member promoted.
AccuRev keeps track of the set of active files in your workspace. Officially, this set is called the
default group. You might find it easier to think of it as the workspace’s “active group”.
The Promote command does not copy the promoted version to the AccuRev repository. It does not need to. Promotion just gives an additional name to a version that
already exists in the repository — having been placed there by a previous
Keep command (or
Rename/
Move or
Defunct). For example, promoting “the 7th version created in workspace
talon_dvt_mary” might give that version the additional name “the 3rd version promoted to stream
talon_dvt”.
Just to emphasize the previous point: a stream does not reside in the file system, but in the database used by the AccuRev Server. Promoting a version to a stream does not create a copy of a file; it just creates an additional file-reference in the database.
It might seem strange at first that deleting a file with the Defunct command makes the file
active. The File Browser continues to list the file — with a
(defunct) status — even though the file has been removed from your workspace’s disk storage. This design feature enables AccuRev to implement the file-deletion operation using the same private-change/public-change scheme as all other changes.
We have discussed the stream that is the basis for a set of workspaces. But a typical development project has many streams, organized into a hierarchy. Promoting a version to a higher-level stream from a lower-level stream makes that version “even more public” — for example, available to users outside your local development team.
Update: Incorporating Others’ Changes into Your Workspace
As users work independently of each other, the contents of their workspaces increasingly diverge. Typically, some of the differences between workspaces are inconsistencies. For example, changes that John makes in a report-library routine might cause errors in the report program that Mary is writing. To minimize the time and effort required to resolve inconsistencies during the integration phase of a project, it makes sense to have users synchronize their workspaces on a regular basis.
With AccuRev, synchronization does not mean incorporating data into your workspace directly from one or more other workspaces. Instead, synchronization involves copying data into the workspace from the stream to which all team members
Promote their changes. This operation is performed by the
Update command. This figure shows the
Update toolbar button (

). You can also invoke this command as
File > Update from the main menu.
Note: the stream’s role as a provider of data — through
Updates — to a set of workspaces motivates the term
backing stream. Think of restocking a store’s shelves with merchandise retrieved from “the back room”.
So an update operation on your workspace copies versions of certain files from the backing stream to the workspace, overwriting/replacing the files currently in the workspace. But which files?
Update changes a file if:
Update will not overwrite an active file, even if there is a new version of it in the backing stream. No matter how good someone else’s code is, you don’t want his changes to wipe out the changes that you have been making! This situation is another instance of an
overlap, which we described in the
Promote section above. You can encounter an overlap during a promotion (if you are trying to make your private changes public), or during an update (if you are trying to bring already-public changes into your private workspace). In all such situations, AccuRev resolves the overlap situation with a
merge operation. See
Merge: When Changes Would Collide, below.
Update handles namespace changes as well as content changes. Thus, if your colleague renamed a file and promoted the change, an update will cause the file to be renamed in your workspace. And if your colleague removed a file using the
Defunct command, an update will cause the file to disappear from your workspace.
Here is how AccuRev prevents an update from overwriting your changes: the first thing
Update does is to analyze your workspace, determining whether each version-controlled file is “active” or “inactive”. Initially, all the files in a workspace are inactive — each one is a copy of some version in the repository. (For each version-controlled file, AccuRev keeps track of
which particular version.)
A file is deemed to be active in your workspace if you have created a new version of it, using the Keep,
Rename/
Move, or
Defunct command. (There are other AccuRev commands that “activate” a file.) When
Update copies versions from the repository into your workspace, it skips over all active files.
Note: Update can tell if you have modified a file but have not yet stored the changes in the repository as a new
Keep version. It uses timestamps and checksums to determine this. The presence of such files prevents the update from proceeding if updating would overwrite one or more of them with the backing-stream version. You can use the
Anchor command to activate such files, enabling
Update to do its work.
Merge: When Changes Would Collide
The preceding sections on the Promote and
Update commands both discuss the situation in which two users concurrently work on the same file. Their changes to the file are said to
overlap. Both
Promote and
Update decline to process a file with overlap status, because doing so would cause one user’s changes to overwrite another’s changes.
•
|
Mary Promotes her latest new version of brass.h to the backing stream.
|
•
|
Promote John’s version of brass.h to the backing stream.
|
•
|
Overwrite John’s copy of brass.h during an update. (The Update command skips over this file, but continues its work on other files.)
|
To enable either a promotion or an update of brass.h, John must incorporate, or
merge, the version in the backing stream — which contains Mary’s changes — into his own copy of the file. The
Merge command is essentially a text editor, which combines the contents of two versions of a text file. The resulting “merged version” replaces the file in John’s workspace.

This figure shows how to invoke the
Merge command from a file’s context (right-click) menu in the File Browser. You can also invoke
Merge with the

toolbar button.
Often, a merge operation is unambiguous, and so can be performed automatically. For example, suppose Mary’s changes to file
brass.h all occur in lines 1–50, and all of John’s changes occur in lines 125–140. In this case, merging the two versions involves replacing some or all of John’s first 50 lines with Mary’s. Now, the edited version of
brass.h in John’s workspace contains both users’ changes.
Note: We do not claim that the two sets of changes are semantically consistent with each other. That is what the build-and-test cycle is for!
After performing a merge, AccuRev automatically
Keeps the merged version to preserve the results of the merge operation. You can then
Promote the merged version to the backing stream. After that, other team members can use
Update — or perhaps
Merge — to bring all the changes into their workspaces.
The graphical Merge tool performs a “three-way merge”, which uses the common ancestor of the two versions being merged. This algorithm helps to automate the merge operation, often completely eliminating the need for human intervention. AccuRev performs merge operations on text files only. Binary files are “merged” by choosing which version to take.
AccuRev keeps track of all merge operations. This greatly simplifies subsequent merge operations on files that have been merged previously: you do not need to resolve the same conflicts over and over again.
The most common overlap situation happens when AccuRev prevents you from promoting a file, because someone else “got there first” in creating a version in the backing stream. AccuRev can also detect
deep overlaps, in which another user “got there first” in creating a version in the
parent of the backing stream, or in other higher-level streams.