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 a Keep to save the changes in a new version. The existing version might have been created by you -- for example, with a previous Keep operation. Or it might have been created by someone else: that user promoted the version, then you brought it into your workspace with an update.

The version in your workspace that is created by Keep is termed a real version, because it represents a change to the element. Other operations 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. (Exception: a version created by a revert operation is connected to its direct ancestor by a dashed blue line.)

In the figure above:

•	The left-hand box labeled “2” was created in a workspace within Workspace Group 1. If you mouseover the box, you would see that this is Version 2 in workspace WS1 (“WS1_username/2”).

•

The right-hand box labeled “2” was created in a different workspace within in the same workspace group. (If you mouseover the box, you would see that this is Version 2 in workspace WS2 (“WS2_username/2”). It is just a coincidence that they are both Version 2 in their respective workspaces.) The black line connecting them indicates that version WS2/2 was created in part by updating WS2 with the changes from WS1 and then editing and promoting the file.

•	Version 1 in WS3 was also created by updating from the changes from WS1 and then editing and promoting the file. However, these changes conflicted with the changes made by the user in WS2, and had to be merged. That is why there is red line rather than a black line between these two version.

Alias -- Virtual Version Ancestry

Workspaces contain real versions, which represent changes to elements. However, almost all versions in dynamic streams are virtual versions, created with Promote. (The one exception is real versions that are created in a dynamic stream using Revert.) 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 ac_doc_build is an alias for (was promoted from) version 10 in a workspace within Workspace Group 1.

•	version 5 in stream ac_doc_build is an alias for version 12 in a workspace within Workspace Group 1.

•	version 11 in Workspace Group 2 is an alias for version 10 in a workspace within Workspace Group 1.

There's one exception to this scheme. The Anchor or Send to Workspace operation 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 promotes are aliases for the same real version. The Version Browser shows how all the virtual versions relate back to the original real version.

The default display shows all versions in a straight line. However, each virtual version is actually connected directly back to the real version in the workspace within Workspace Group 1, which can be seen by clicking and dragging each version box.

Merge -- Merging of Two Versions

A standard merge operation combines the contents of 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: 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 most recent version in the backing stream.

The result file of the merge operation is kept as a new version in the workspace stream. 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 that necessitated the merge.

Example: This screen shot shows a merge from the backing stream vb to a workspace within Workspace Group 1.

The new, merged version is 2 which is in a workspace within Workspace Group 1. (You can see which workspace by mousing over the version box. In this example, it is WS2.)

Its ancestors are:

•	Real version WS1/2 (again, you can see workspace WS1 by mousing over the ancestor version box labeled “2”).

•	Real version WS3/1, which was promoted to become virtual version vb/4 in the backing stream.

A solid red line shows the merging of data from one workspace, WS3, to a different workspace within Workspace Group 1.

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 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. See Patch and Patch From for full a discussion of patches.

When you select a version created by Patch, the Version Browser highlights in green 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 Revert 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 Revert 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 for more information on how these ancestry lines are created.

Purge -- Revert to Basis

The CLI purge command is analogous to the Revert to Basis function in the GUI. Assume that you have started to work on a file and that you have made one or more keeps in your workspace. Then something happens: perhaps the changes are no longer required due to a new project direction, or you’ve come up with a better approach and want to start over from scratch. So you perform a Revert to Basis (purge) to abandon all your keeps and restore the file to the way it was when you started working on it. This means that your keep versions are something of a dead-end. This is represented in the Version Browser by a magenta line and an asterisk in the version box.