Handling Stranded Elements

As described above, an AccuRev workspace or stream can contain one or more elements that are stranded. An element is stranded in a particular workspace or stream if it is a member of the default group, but cannot be accessed because there is no pathname to the element in that workspace or stream. An element can be stranded in one stream but not be stranded in other streams.

In the AccuRev GUI, stranded elements are listed in the File Browser’s Stranded filter. In the CLI, the command stat –i lists stranded elements. A stranded element is listed by its element-ID, along with a pathname that was once (but is not currently) valid in that stream.

The sections below describe the ways in which elements can become stranded, along with procedures for handling each situation.

Defunct element obscured by element with same name

Elements under a defunct parent

Elements under an excluded parent

Dangling directory elements

Elements under a non-existent (purged) parent directory

Elements under a stranded parent directory

Active element refers to a purged version

Defunct element obscured by element with same name

This occurs in the parent stream of two workspaces if:

•	The user in workspace #1 defuncts an element, then promotes this change to the parent stream.

•	The user in workspace #2 updates the workspace (to incorporate the defuncting), creates a new element with the same name, then promotes the new element to the parent stream.

At this point, the defuncted element is stranded in the parent stream. It cannot be promoted to the “grandparent” stream by name, because it doesn’t have a name in the parent stream. The new element cannot be promoted to the grandparent stream at all, because the name in the grandparent stream belongs to the defuncted element.

Note: through repeated add-promote-defunct-promote cycles, it’s possible to have multiple elements with defunct status in the parent stream, all of which were created at the same pathname.

Resolving the Situation

To get the defuncted element out of the way, promote it by element-ID to the grandparent stream: promote –e <eid> –s <parent_stream>.

To recover the defuncted element in workspace #1, use undefunct –e <eid> on the defuncted element. This has the side effect of making the new element inaccessible in workspace #1. Depending on your needs, use defunct –e or move –e on the new element.

Elements under a defunct parent

This occurs in the parent stream of two workspaces if:

•	The user in workspace #1 defuncts a directory element, then promotes this change to the parent stream.

•	The user in workspace #2 modifies a file element in that directory, then keeps and promotes it to the parent stream.

At this point, the file element is stranded in the parent stream. In addition, the user in workspace #1 cannot access the file element by name.

Resolving the Situation

To propagate the file element’s change to the grandparent stream, promote it by element-ID: promote –e <eid> –s <parent_stream>.

To access the file’s contents, use its element-ID: cat –e <eid> –v <version-ID>.

The only way to work with the file element in workspace #1 is to first undefunct the directory, which makes the file visible again.

Elements under an excluded parent

This occurs in the parent stream of two workspaces if:

•	The user in workspace #1 modifies a file element in that directory, then keeps and promotes it to the parent stream.

•	The user in workspace #2 sets a rule that excludes a directory element from the parent stream (excl –s <parent-stream> <directory-name>).

At this point, the file element is stranded in the parent stream. In addition, the user in either workspace cannot access the file element by name (after updating the workspace).

Resolving the Situation

To propagate the file element’s change to the grandparent stream, promote it by element-ID: promote –e <eid> –s <parent_stream>.

To access the file’s contents, use its element-ID: cat –e <eid> –v <version-ID>.

The only way to work with the file element in either workspace is to first remove the exclude rule (clear command) from the parent stream, and then update the workspace. This makes the file visible again.

Dangling directory elements

This contradictory situation — a particular directory seems to be both above and below another directory — occurs in the parent stream of two workspaces if:

•	The user in workspace #1 moves directory A under directory B, then promotes directory A.

•	The user in workspace #2 moves directory B under directory A, then promotes directory B.

At this point, both directories are stranded in the parent stream. An update of workspace #1 causes directory B to be removed; an update of workspace #2 causes directory A to be removed.

Resolving the Situation

The only way to untangle this knot of inconsistency is to checkout (co command) a previous version of each directory that has the “correct” (that is, consistent with the other directory) pathname, then promote these old versions to the parent stream.

The simplest way to do this is to specify the transaction that created the directory at its correct pathname: co –t <add-transaction-number>. But this method can be “messy” if the add transaction also created other elements, such as the files within the directory.

Another method is to use a workspace under a time-based stream to see the relevant directories with their correct pathnames. Checkout the “old” directory versions, promote these versions from the workspace to the time-based stream, then use promote –s <time-based-stream> –S <parent-stream> to promote to the parent stream.

Note: with either method, you’ll probably need to use the –O option to the promote command, in order to avoid the need to merge the “old” directory versions.

Elements under a non-existent (purged) parent directory

This occurs in the parent stream of a workspace if:

•	The user creates a new directory and file within the new directory, and promotes both new elements to the parent stream.

•	The user purges (GUI: Revert to Basis) the new directory from the parent stream.

At this point, the new file is stranded in the parent stream.

Resolving the Situation

You cannot propagate the file element’s change to the grandparent stream, because the new directory never existed in that stream.

To access the file’s contents, use its element-ID: cat –e <eid> –v <version-ID>.

The only way to work with the file element is to first checkout (co command) the version of the directory that was originally created in the workspace. The simplest way to do this is to specify the transaction that created the directory: co –t <add-transaction-number>. But this method can be “messy” if the add transaction also created other elements.

Another method is to use a workspace under a time-based stream to see the directory before it was purged from the parent stream. Checkout the directory, promote it from the workspace to the time-based stream, then use promote –s <time-based-stream> –S <parent-stream> to promote to the parent stream.

Note: with either method, you’ll probably need to use the –O option to the promote command, in order to avoid the need to merge the “old” directory version.

Elements under a stranded parent directory

To access an element under a stranded parent directory, restore the accessibility of the parent, as described in the sections above. This restores the accessibility of the element in question.

Active element refers to a purged version

This occurs when an element (file, directory, or link) is active in a dynamic stream. The dynamic stream’s virtual version is a reference to a version that has been purged, so that there is no active version of the element in a higher-level stream (and no version in the depot’s root stream).

The only known scenario involves promoting an active element from a dynamic stream to one of its child streams, then purging the element from the original stream.