The Version Browser

Opening a Version Browser Tab

Version Browser Tab Layout

Ancestry Lines

Ancestry Relationships

Direct Ancestor -- Modification of an Existing Version

Alias -- Virtual Version Ancestry

Merge -- Merging of Two Versions

Patch -- Selective Inclusion of Another Version's Changes

Revert -- Selective Removal of Changes from a Version

Closest Common Ancestor

Operations on Versions

User Preferences

AccuRev maintains complete ancestry The entire set of versions of an element. See version graph. information for each element A file or directory that is under AccuRev version control. See version.. The Version Browser displays some or all of an element's versions A particular revision of an element, reflecting a content change (files only) or a namespace change (files and directories). All versions are originally created in workspaces, and can subsequently be promoted to dynamic streams. The original (workspace) version is termed a 'real version'. Each promotion to a dynamic stream creates a 'virtual version', which serves as an alias for (pointer to) the original real version., using color-coded lines to indicate the way in which each version was created. You can perform various version-related operations, such as comparing any two versions (text files only) and copying any version to your workspace.

Opening a Version Browser Tab

The names of elements appear in many contexts in the AccuRev GUI. These include the Details pane of the File Browser, the versions pane of the History Browser, and the Changes tab (change package) of a AccuWork issue record. In any of these contexts, you can select one element and invoke the Browse Versions command. (In some cases, this command is a subchoice, under a History menu choice.)

Version Browser Tab Layout

The Version Browser display contains:

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.

Ancestry Lines

The Version Browser uses these color-coded lines to indicate ancestry relationships

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 A version of an element, created in some user's workspace, recording a change to the contents and/or pathname of the element. See version, virtual 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 In the version graph of an element, version A is an ancestor of version B is there is a direct line of descent (possibly including merges) from A to B. or predecessor) with the new version.

[explanation of direct ancestor lines]

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 A version of an element, created in some user’s workspace, recording a change to the contents and/or pathname of the element. See version, virtual version., which represent changes to elements. By contrast, all versions in dynamic streams are virtual versions A version of an element, created in a dynamic stream as an alias for (reference to) a previously created real version., 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.

[explanation of alias lines]

In the figure above:

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.

[explanation of alias lines]

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:

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:

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 An operation that takes just a set of 'recent changes' from a version of an element, and applies those changes to another version of the same element. See merge. operation is similar to a merge An operation that combines the contents of two text files (contributors), which are versions of the same file element. AccuRev uses a '3-way merge' algorithm: it compares the two files line-by-line with a third file, the version that is the closest common ancestor of the other two. 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:

When you select a version created by the Patch command, the Version Browser highlights in red the versions contained in that patch.

Notes (click to view):

Revert -- Selective Removal of Changes from a Version

A revert An operation that 'removes' a selected set of changes from a specified version, by creating a new version that does not contain the change operation is the opposite of a patch A selected set changes (typically, the 'recent changes' made by one user) to a text-file element. Also, the merge-like operation that incorporates those changes in another version of the same element. See merge, basis version, head version, change package, reverse 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:

Click here for more information on how these ancestry lines are created.

Closest Common Ancestor

It's instructive to follow all the black and solid-red lines in an element's Version Browser display. This traces the entire ancestry of real versions of an element. In particular, you can use the real-version ancestry to determine the closest common ancestor of any two versions. This is the most recent version upon which the two versions are both based, by some combination of direct ancestor and merge connections. (When considering a virtual version in a closest-common-ancestor analysis, first follow the green line back to the corresponding real version.)

You can also use the CLI command accurev anc -c to find the closest common ancestor of two versions.

In the Merge command, AccuRev determines the closest common ancestor of the two versions to be merged, and uses this version to perform a 3-way merge The kind of algorithm that AccuRev uses to combine the contents of two versions (contributors) of a text-file element: it compares the two files line-by-line with a third version, the closest common ancestor of the contributors.. Click here for more information on the merge algorithm.

Operations on Versions

You can perform several operations on a selected version, using its context menu or the Version Browser toolbar.

Open (equivalent to double-click)

Windows: run the appropriate command on the file, according to its file type. [note The Windows file-typing system ("file associations") does not provide for assigning a file type if the filename has no suffix.] UNIX: open a text editor on the file.

View

Open a text editor on a temporary copy of the currently selected file (text files only).

Save As

Copy the currently selected file to another filename.

Merge From

Merge the selected version into the version in the workspace from which the Version Browser was invoked.

Patch From

Patch the selected version into the version in the workspace from which the Version Browser was invoked.

Show History

Open a History Browser tab, showing the transaction that created the selected version.

Diff Against Other Version

Compare the selected version with another version of the element. AccuRev changes the mouse pointer, to prompt you to select the other version. You can click on any version in the Version Browser display. You can also click on a stream or workspace label to indicate the version currently in that stream or workspace.

Diff Against File in the Workspace

Compare the selected version with the file in the workspace from which the Version Browser was invoked. This workspace is listed at the bottom on the AccuRev GUI window. This enables you to invoke a comparison with a file that you have changed in your workspace, but have not yet preserved in the repository with a Keep command.

Diff Against File On Disk

Compare the selected version with the an arbitrary file on your machine. A File Chooser dialog appears, in which you specify the file.

Send to Workspace

Activate the selected element in the workspace from which the Version Browser was invoked. The element must currently have (backed) status in the workspace -- that is, it must not be active.

Send to Issue

Record the selected version(s) in the change package section (Changes tab) of one or more issue records. The default query of the issue database is executed, and you are prompted to choose one or more of the records selected by the query. You can also create a new issue record, to which the selected version(s) will be sent.

Send to Issue (specifying basis)

Record the selected version in the change package section (Changes tab) of one or more issue records. You are prompted select a version in the Version Browser display; this version will become the basis version in the change package entry. [note The basis version you specify must be an ancestor In the version graph of an element, version A is an ancestor of version B is there is a direct line of descent (possibly including merges) from A to B. See predecessor (or direct ancestor). of the head version. If it isn't, an "Invalid Change Package" error occurs.] Then, the default query of the issue database is executed, and you are prompted to choose one or more of the records selected by the query. You can also create a new issue record, to which the selected versions will be sent.

Properties

Displays information about the selected element in a pop-up window. The data items displayed vary with the type of element.

User Preferences

The Tools > Preferences command opens a dialog that includes a Version Browser tab, where you can control settings that affect the Version Browser.