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:
xlink <pathname> from
<workspace> to
<backing-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:
\.\doc\.\src
\.\tools
\.\doc\chap01.doc
\.\doc\chap02.doc
\.\src\commands.c
\.\src\topaz.c
\.\src\topaz.h
\.\tools\cmdshell
\.\tools\perl
\.\tools\python
\.\tools\tools.readme
\.\tools\cmdshell\bash
\.\tools\cmdshell\csh
\.\tools\cmdshell\bash\end.sh
\.\tools\cmdshell\bash\start.sh
\.\tools\cmdshell\csh\end.csh
\.\tools\cmdshell\csh\start.csh
\.\tools\perl\add_cr.pl
\.\tools\perl\remove_cr.pl
\.\tools\python\setup.py
\.\tools\python\vars.py
Since this set of depot-relative pathnames defines a hierarchy, it’s often clearer to list the pathnames component-by-component, like this:
\.\ doc
chap01.doc
chap02.doc
src
commands.c
topaz.c
topaz.h
tools
tools.readme
...
To locate an element, AccuRev interprets its specified pathname component-by-component (just like the operating system does). The cross-links facility provides a way to make AccuRev switch namespaces in the middle of the pathname-interpretation process.
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.
|
•
|
directory element \.\tools\cmdshell\csh has been renamed to \.\tools\cmdshell\c_shell
|
•
|
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:
|
•
|
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.
|
The procedure in the first bulleted paragraph can be described as “Include then Update”; the second bulleted paragraph’s case can be described as “Update then Include”. The final result is the same in both cases: the changes to the cross-linked elements in their new backing stream are incorporated into your workspace. We consider the second case to be an AccuRev best practice:
Best Practice:
Update your workspace before performing an
Include from Stream command
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).
AccuRev can traverse two or more cross-links in the same pathname. For example, you might use this pathname in workspace
W:
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:
“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.
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.
•
|
Move file tools.readme to the depot’s root directory, and rename it to README-tools.txt.
|
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:
> accurev name -e 28 -v topaz_refact
\.\tools\tools.readme
\.\README-tools.txt
Section Multiple Cross-Links: Chaining on page 48 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.