This note clarifies and supplements the basic documentation of AccuRev’s cross-link feature.
A cross-link is created in a workspace by the Include from Stream command (CLI: incl –b). The command name implies that a connection is being established from a specified backing stream to the workspace. But an existing cross-link is listed by the CLI command lsrules like this:
|
•
|
|
•
|
The designated backing stream is the cross-link’s target stream.
|
Each AccuRev stream (including snapshot streams and workspace streams) provides a namespace: a set of pathnames to some or all of the depot’s elements. For example:
Since this set of depot-relative pathnames defines a hierarchy, it’s often clearer to list the pathnames component-by-component, like this:
And suppose you’ve created a cross-link at subdirectory cmdshell, with workspace W as the source stream and stream S as the target stream. AccuRev will process the pathname, component-by-component, as illustrated here:|
•
|
Pathname components up to and including the cross-linked component, are interpreted in the original (source stream) namespace.
|
Note that in workspace W, you continue to access the cross-linked element, subdirectory cmdshell, through its “local” name in the workspace’s namespace. It’s quite possible (but you don’t need to know) that this element has a different name — even a different pathname — in the target stream:
Pathname components below “cmdshell” are interpreted in the namespace of stream S, the target stream. For example, if script end.csh has been renamed in stream S to topaz_exit.csh, then that’s the name you must use in workspace W, as well:
The File Browser and the CLI commands stat and files make this namespace-switching transparent: AccuRev shows you the element names and pathnames that will enable you to access the data from your current workspace or stream context.
|
•
|
In a dynamic stream, the Include from Stream command incorporates all changes from the target stream immediately. This reflects the fact that a dynamic stream inherits versions from its backing stream automatically and instantly.
|
|
•
|
In a workspace, the Include from Stream command respects the workspace’s update level. That is, it incorporates only those changes that occurred in the target stream before the workspace’s most recent update. A subsequent Update command will bring in the more recent changes from the target stream.
|
|
•
|
|
•
|
|
•
|
file element \.\tools\cmdshell\c_shell\start.csh has been edited
|
You use the Include from Stream command to create a cross-link from your workspace to stream topaz_mnt, at pathname \.\tools\cmdshell. The immediate change to your workspace depends on its update level:
|
•
|
If the changes in stream topaz_mnt occurred after your workspace’s most recent update, you won’t see the changes immediately in your workspace: directory cmd will still exist, directory csh won’t be renamed to c_shell, and you won’t see the edits to file start.csh. But the status of these elements includes the (stale) indicator, showing that the changes are in the backing stream, waiting to be incorporated:
|
At this point, performing an Update will bring the changes into the workspace.
|
•
|
If the changes in stream topaz_mnt occurred before your workspace’s most recent update, all those changes will be brought into the workspace immediately.
|
If you Update first, other backing-stream changes won’t be “mixed in” with the Include from Stream changes during the next workspace update. Moreover, fully establishing the link from your workspace to the target stream will involve a single step (Include), rather than two steps (Include then Update).
Note: because it respects — but does not change — your workspace’s update level, Include from Stream more closely resembles the Populate command than the Update command.
|
•
|
|
•
|
As AccuRev traverses the pathname component-by-component, it interprets the components as illustrated here. As it progresses down the pathname, AccuRev also traverses a “chain” of cross-links:|
•
|
start in workspace W, then ...
|
|
•
|
cross-link to stream S1, then ...
|
|
•
|
“Chaining” of cross-links can continue to any number of levels. The same principle applies repeatedly: a cross-linked pathname component is interpreted in the source stream’s namespace; subsequent non-cross-linked components are interpreted in the target stream’s namespace.
But you must take care when “chaining” cross-links in this way. It is possible to create ambiguous configurations, which AccuRev handles by removing the affected elements. See Cross-Link Overlaps.
A special case of cross-link chaining occurs when you create a configuration in which two or more cross-links occur at the same pathname component. For example, consider again this pathname:
|
•
|
|
•
|
In workspace W, the subdirectory will continue to have its “original” name, cmdshell. But the subtree under the subdirectory will come from the stream S2 namespace. By extension, you could chain any number of cross-links at the cmdshell component: W > S1 > S2 > S3 > S4 ... As above, the directory retains its “original” name in the workspace, and the workspace sees the directory’s subtree as it exists in the final target stream.
One consequence of AccuRev’s cross-link facility is that two (or more) different versions of the same element can appear at different pathnames in the same workspace or stream. We call this phenomenon double vision. This is not an error — at least, not from AccuRev’s perspective. Seeing the same element twice might be exactly what you intended, or it might signify that you’ve left some refactoring work unfinished.
|
•
|
|
•
|
|
•
|
Improve the source file comments in the src directory.
|
You perform this work in your workspace, named topaz_refact. But when the dust settles, you find that the programs in the tools subdirectory no longer work. You are not sure whether the problem is in the tools directory or the src directory. So you decide to “back out” your refactoring of the tools directory, by cross-linking to the known-to-work version of the tools directory in snapshot stream topaz_2.3.9.
Now, you have two different versions of the “README” element in your workspace! In your refactoring, you created a new version in your workspace, at pathname \.\README-tools.txt:
But your workspace now cross-links to the Release 2.3.9 version of the tools subdirectory, which contains the Release 2.3.9 version of the same element, at pathname \.\tools\tools.readme:
This case of double-vision is clearly an error, reflecting the fact that your refactoring work is still ongoing. In other cases, you might want two (or more) versions of a commonly used source file, say topaz.h, to appear in a workspace. Perhaps several different versions of the file are required, in order to build different executables using that file. Version skew is the executables’ other dependencies might mandate the different versions of topaz.h.
The accurev name command lists the pathname for a given element (specified by element-ID) in your workspace. It can also list the pathname for a specific version of an element, or the version in a specific stream:
In a double vision situation, the name command can list all of an element’s pathnames in a workspace or stream:
Section Multiple Cross-Links: Chaining describes how a set of cross-links can define a “chain” of backing streams to be used at different components in a pathname:
In this case, the second link in the cross-link chain (S1 > S2) occurs at a higher pathname component, DDD, than the first link (W > S1, at component GGG). AccuRev recognizes this situation as a cross-link overlap.
When a workspace that has a cross-link overlap gets updated, AccuRev removes the subtree below the component where the first link was created.