Direct Ancestor -- Modification of an Existing Version
Alias -- Virtual Version Ancestry
Merge -- Merging of Two Versions
Patch -- Selective Inclusion of Another Version's Changes
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.
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.)
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.
The name of the workspace or stream, at the right edge of the display.
Color-coded ancestry lines connecting the versions, indicating how the later version was derived from the earlier version.
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 A record in the AccuRev repository database that indicates a particular change: promoting of a set of versions, changing the name of a stream, modification to an issue record, etc. or change package A set of entries, each in the form of a basis-version/head-version pair, recorded on the Changes tab of an issue record. The change package records the changes to one or more elements, made to implement the feature or bugfix described in that issue record. Each entry in the change package describes changes to one element: the changes between the basis version and the head version. See patch..
The following sections discuss the kinds of ancestry in more detail.
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]
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.
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.
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.)
A standard merge operation combines the contents of these two versions of a file:
The most recently kept version in your workspace stream. This version contains the changes that you have made to the file in your workspace. [note ]
The most recent version in the backing stream.
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:
The most recently kept version in your workspace stream.
The version in some other workspace stream that was promoted to the backing stream, causing the overlap Version X, in a workspace or stream, has '(overlap)' status if the parent stream's current version of the element contains changes that are not reflected in version X. (That is, the parent stream's version is not an ancestor of version X.) Such a version cannot be promoted to the parent stream; the user must create a new version with a merge operation, combining version X with the parent stream's version. The new, merged version can then be promoted. Similarly, an overlap can exist between the versions in two dynamic streams. See deep overlap. that necessitated the merge.
[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.
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:
A merge operation considers the entire contents of the "from" version.
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. Click here 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.
Notes (click to view):
Patching and the closest common ancestor
AccuRev tracks patch ancestry separately from merge ancestry. In determining the closest common ancestor (of two versions of an element) The most recent version that is an ancestor of two specified versions. Used in a merge operation to minimize the amount of work required to combine the contents of the two specified versions. See merge, version graph. of two versions for 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, AccuRev takes into account previous merge operations (solid red), but not previous patch operations (dashed red) or revert operations (dashed blue).
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:
A dashed blue line indicates the version from which Revert removed some changes.
A solid black line indicates the basis version A particular ancestor of the version specified in a Patch, Revert, Diff, or Send to Issue command. The series of versions between the basis version and the specified version constitute the 'recent changes' to be patched into (or removed from) the target. Similarly, a change package entry consists of all the versions between a specified basis version and a specified head version. of the removed patch or change package entry.
Click here for more information on how these ancestry lines are created.
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.
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 ] 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.
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 ] 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.
The Tools > Preferences command opens a dialog that includes a Version Browser tab, where you can control settings that affect the Version Browser.