5. The History Browser : Version Browser Tab Layout

Version Browser Tab Layout
The Version Browser display contains:
A yellow box for each version of the specified element. These boxes are arranged in rows, according to the workspace or stream in which the versions were created.
One yellow box has a blue outline. This is the version that currently appears in the workspace or stream from which you opened the Version Browser tab.
A timestamp above each version box, indicating when the version was created. The tooltip for the version box itself contains the number of the transaction that created the version.
Tip: Use your mouse to drag the Version Browser display -- place the pointer on the display background, press and hold mouse button one, and then move the mouse to change the view.
Ancestry Lines
The Version Browser uses these color-coded lines to indicate ancestry relationships
direct ancestor (black) -- A user started with the earlier version, modified (or overwrote) it, and then performed a Keep, creating the later version. (There are a few other commands, including Rename, that might have created the later version. See below for details.)
alias (green) -- A user promoted the earlier version to create the later version.
merge (red) -- A user executed the Merge command to create the later version. There are always two earlier versions: the black line indicates the direct ancestor (see above) of the later version; the red line indicates the version that was merged with the direct ancestor.
patch (dashed red) -- Similar to merge above; instead of the Merge command, the Patch command was used to create the later version.
revert (dashed blue) -- The later version was created by a 'reverse patch', performed by the Revert command. This effectively 'undoes' the changes in a specified transaction or change package.
Ancestry Relationships
The following sections discuss the kinds of ancestry in more detail.
Direct Ancestor -- Modification of an Existing Version
Probably the most common AccuRev operation is starting with an existing version, making changes, and then executing the Keep command to save the changes in a new version. The existing version might have been created by you -- for example, with a previous Keep command. Or it might have been created by someone else: that user Promote'd the version, then you brought it into your workspace with an Update.
The version in your workspace created by the Keep command is termed a real version, because it represents a change to the element. Other commands can create real versions in your workspace, too: Rename, Defunct, Undefunct.
The Version Browser uses a solid black line to connect the existing version (termed the direct ancestor or predecessor) with the new version.
In the figure above:
Version 9 in the flax_dvt_mary workspace stream was revised to create version 10 in the same stream.
Workspace stream flax_dvt_john was updated to incorporate version flax_dvt_mary/10. Then, this version was revised to create version flax_dvt_john/2.
Version 2 in the flax_dvt_john workspace stream was revised to create version 3 in the same stream; and version 3 was revised to create version 4.
Exception: a version created by a revert operation is connected to its direct ancestor by a dashed blue line.
Alias -- Virtual Version Ancestry
Workspaces contain real versions, which represent changes to elements. By contrast, all versions in dynamic streams are virtual versions, created with the Promote command. Each virtual version is an alias for -- that is, a pointer to -- some real version in a user's workspace. The Version Browser uses a green line to connect a virtual version in a dynamic stream to the corresponding real version in a workspace.
In the figure above:
version 4 in stream brown_dvt is an alias for (was promoted from) version 15 in workspace brown_dvt_john
version 5 in stream brown_dvt is an alias for version 17 in workspace brown_dvt_john
version 6 in stream brown_dvt is an alias for version 3 in workspace brown_dvt_mary
There's one exception to this scheme. The Anchor or Send to Workspace command creates a virtual version in a workspace. It's a virtual version because it doesn't represent a change to the element, but merely the restoration of an existing version to the workspace.
Successive Promotions. In a depot with a deep stream hierarchy, it's common to successively promote a particular version to the parent stream, then to the grandparent stream, then to the great-grandparent stream, etc.
All the versions created by this series of Promote's are aliases for the same real version. The Version Browser shows how all the virtual versions relate back to the original real version.
The versions in streams brown_dvt, brown_tst, and brown are all aliases for the real version 2 in workspace stream brown_dvt_mary. (The display does not indicate the fact that the version was promoted from brown_dvt to brown_tst, and from brown_tst to brown.)
Merge -- Merging of Two Versions
A standard merge operation combines the contents of these two versions of a file:
Note: It's possible -- but not a best practice -- to perform a merge on a file with (modified) status. Since you haven't preserved the recent changes with Keep, AccuRev will have no way to restore the file to its state just before the merge. This can be painful if you change your mind or make an error during the merge process.]
The result file of the merge operation is kept as a new version in the workspace stream. (You can think of merging as a fancy text-editing operation; as with any edit to a file, you preserve the results with Keep.) This new, merged version has two ancestors: the two versions listed above.
This is all simple enough. There's a twist, though, which shows up in the Version Browser display: AccuRev always records real versions, not virtual versions, as the two ancestors of a new, merged version. Thus, the ancestors in the standard merge scenario described above are:
Example: This screen shot shows a merge from the backing stream brown_dvt to the workspace stream brown_dvt_john.
The new, merged version is brown_dvt_john/12.
Its ancestors are:
Real version brown_dvt_john/11
Real version brown_dvt_mary/1, which was promoted to become virtual version brown_dvt/3 in the backing stream.
A solid red line shows the merging of data from one workspace, brown_dvt_mary, to a different workspace, brown_dvt_john . The black line ("direct ancestor") between versions 11 and 12 in the brown_dvt_john workspace reflects the viewpoint that merging is just a fancy text-editing operation, automating the creation of the next version of a file in a workspace.
Patch -- Selective Inclusion of Another Version's Changes
A patch operation is similar to a merge operation. In both, text from another version (the "from" version, at the left end of the dashed red line) is incorporated into your workspace's version. Here's the difference:
A patch operation considers only some of the changes in the "from" version. Typically, it's the 'recent changes' made by one user, recorded in one version or a set of consecutive versions. See Patches and Change Packages on page 170 for full a discussion of patches.
When you select a version created by the Patch command, the Version Browser highlights in red the versions contained in that patch.
Note: Patching and the closest common ancestor
AccuRev tracks patch ancestry separately from merge ancestry. In determining the closest common ancestor of two versions for a merge operation, AccuRev takes into account previous merge operations (solid red), but not previous patch operations (dashed red) or revert operations (dashed blue).
Revert -- Selective Removal of Changes from a Version
A revert operation is the opposite of a patch operation. (And we describe the Revert command as performing a 'reverse patch' operation.) Whereas a patch adds a selected set of changes, a revert removes a selected set of changes.
A version created by the Revert command has two ancestry lines:
A dashed blue line indicates the version from which Revert removed some changes.
A solid black line indicates the basis version of the removed patch or change package entry.
See Reverse Patch: Removing Content Changes on page 243 for more information on how these ancestry lines are created.

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com