Change and Synchronization: The Four Basic Commands

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 the File Browser toolbar; Keep is also available from the Actions and context (right-click) menus. Note that you can also keep new files, like requirements.txt in the preceding illustration -- its status is (external) because it has not yet been added to AccuRev.

Tip: The File Browser helps organize your workspace using Outgoing Changes (your work), Incoming Changes (others’ work), and Conflicts modes (conflicting changes in your work and that of a teammate).

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 of these are:

•

Rename and 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. When you promote a defuncted file, other users will continue to see the file until they update their workspaces, at which point the file will be removed. (Defunct differs from a simple Delete in that Defunct removes the file from your workspace, while Delete removes the physical file from your local directory.)

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 velo_dfoster\2 (which translates as "the 2nd version of this file created in workspace velo_dfoster").

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.

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 the File Browser toolbar; Promote is also available from the Actions and context (right-click) menus.

Tip: You can Promote files that you have not yet kept
-- AccuRev performs the necessary Keep action for you. In the case of new files, AccuRev first adds the file to the AccuRev repository.

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, Update: Incorporating Others’ Changes into Your Workspace.

The Promote command sends data to -- and the Update command gets data from -- an AccuRev data structure called a stream. The stream (named talon_dev in this illustration) 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.

A stream is not, as you might initially suppose, a set of copies of promoted files. Rather, it is more like a list of version-IDs.

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 logic.xml, 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 in their own workspace). 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.

Before you can promote your changes to the stream, you must first perform a merge on the file that has an overlap. This command is described in Merge: When Changes Would Collide.

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, updating 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.

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 figure shows how to invoke the Update command from the File Browser toolbar; Update is also available from the File and context (right-click) menus.

Tip: You can Update your workspace from any File Browser mode, but the Incoming Changes mode shows you exactly how your workspace will change.

Note: the stream’s role as a provider of data -- through Update operations -- 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 updating 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 do not want his changes to wipe out the changes that you have been making! This situation is another instance of an overlap, which was introduced in Promote: Making Your Private Changes Public. You can encounter an overlap during a promote (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). You can use the merge operation to resolve all such overlap situations. See Merge: When Changes Would Collide.

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.

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.

•

Will not allow John to Promote his version of logic.xml to the backing stream (there is no reason to assume that John’s changes should take precedence over the changes Mary has already made and promoted).

•

Will not overwrite John’s copy of logic.xml when he updates his workspace (again, AccuRev does not assume that a version in the backing stream should take precedence over changes made to the version in the workspace). The Update command skips over this file, but continues its work on other files.

Before John can either promote or update logic.xml, he 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 the File Browser toolbar; Merge is also available from the Actions and context (right-click) menus.

Tip: Use the File Browser Conflicts mode to view overlap and other conditions that prevent files from being updated and promoted.

Often, a merge operation is unambiguous, and so can be performed automatically. For example, suppose Mary’s changes to file logic.xml all occur in lines 30–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 20 lines with Mary’s. Now, the edited version of logic.xml 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!