Twin Elements and Stranded Elements

Namespace-related changes :

•

“twin” elements — Two or more distinct elements are described as twins if they have the same pathname within a depot. (Some SCM environments use the term “evil twins”.) AccuRev tracks element names consistently, provides better information about the existence of twins, and provides tools for resolving unintended twin situations.

Tip: AccuRev provides a wizard and other features in the AccuRev GUI to help you identify and resolve elements with a (twin) status. See Resolving (twin) Status in the AccuRev On-Line Help Guide for more information.

•	“stranded” elements — An element is stranded in a particular workspace or stream if (1) it is active in that workspace or stream, but (2) does not have a pathname in that workspace or stream. AccuRev includes stranded elements.

These two areas are related. If a stream contains a set of twins at a particular pathname, only one of those elements is visible at that pathname, for most purposes. The other twin(s) are stranded.

The following sections describe namespace-related functionality in detail.

Preventing Creation of Twins in Workspaces

Two checks performed by the add command help to prevent twins from being created:

•	If the user’s workspace currently contains a defunct element at the same pathname, the add command is cancelled.

•	If an element with the same pathname currently appears in the workspace’s parent stream — and the element does not have (defunct) status in the parent stream — the add command is cancelled. If the element is (defunct) in the parent stream, an add command succeeds.

Reporting of Twins in Dynamic Streams

The checks described in the preceding section apply to workspaces only, not to dynamic streams. There are various ways to create twins in dynamic streams — for example:

Defunct an existing element in a workspace, and promote the change to the parent stream. Then create a new element at the same pathname (in the same workspace or in a sibling workspace), and promote the new element to the parent stream. The parent stream now contains two elements at the same pathname — one is defunct, the other is “live”.

If a set of two or more twins exists in a dynamic stream (or snapshot), the File Browser shows only the one “live” element. (If every element in a set of twins has (defunct) status, the most recently defuncted element is deemed to be “live”.)

In this situation, all the other twins in the set have (stranded) and (twin) status. These elements are displayed by the Stranded search in the File Browser Outgoing Changes mode, and by the AccuRev CLI command stat –i:

> accurev stat -s tin_dvt -i
\.\doc\new.doc e:20 tin_dvt\2 (4\2) (defunct) (member) (stranded) (twin)

For more information, see Detection of All Stranded Elements, Including “Twins” below.

Tip: Twin elements are displayed in the File Browser Conflicts mode.

Ability to Reuse an Element Name after a Rename Operation

AccuRev supports “refactoring” operations, so that all element renamings and directory hierarchy overhauls can be completed and tested in the developer’s workspace before any changes are promoted to the parent stream.

This flexibility stems from the fact that after an element Rename operation (CLI command: move), the element’s former name becomes available for reuse immediately. (Previous releases “reserved” the former name, in case the change was purged from the workspace — see When a Purge Operation Causes an Element to Disappear below.)

Here’s a simple refactoring example:

> accurev move brass.h util.h
Moving \.\src\brass.h to \.\src\util.h

> copy c:\temp\temp_new_brass.h .\brass.h
1 file copied

> accurev add brass.h
Added and kept element \.\src\brass.h

> accurev promote util.h
Validating elements.
Promoting elements.
Promoted element \.\src\util.h

> accurev promote brass.h
Validating elements.
Promoting elements.
Promoted element \.\src\brass.h

Note that util.h (formerly named brass.h) must be promoted first, to “free” the name brass.h in the parent stream. Then the new element named brass.h can be promoted.

When a Purge Operation Causes an Element to Disappear

The preceding section describes flexibility for refactoring. But it does introduce a complication: what happens if you rename an element, create a new element at the same pathname, then invoke Revert to Basis (CLI command: purge) on the renamed element?

The renamed element cannot revert to its old pathname, because there’s a new element at that pathname. Accordingly, the original element simply disappears from your workspace. This element does not assume (stranded) status — the purge operation makes the element inactive in the workspace, and (stranded) status applies only to active elements.

Note that at this point, your workspace contains a new element at the given pathname, and the parent stream contains the original element at that pathname. Attempting to promote the new element would produce a “name already exists in parent stream” error. These steps remove the original element from the parent stream: (1) defunct the original element in the workspace, using defunct –e; (2) promote this change to the parent stream.

Detection of All Stranded Elements, Including “Twins”

The Stranded search in the File Browser Outgoing Changes mode, and equivalently, the AccuRev CLI command stat –i detect all known cases of stranded files:

•	Defunct elements in same workspace/stream as a “live” element at the same pathname (“twins”)

•	Elements located in a directory that is, itself, stranded

•	Elements located in a directory that is defunct

•	Elements located in a directory that is excluded from the workspace/stream

•	Elements located in a directory that has been purged from the workspace/stream

•	Elements with a “pathname cycle”

Stranded files are reported with the status flag (stranded). If a stranded file happens to be a twin of another element, it is also reported with the status flag (twin).

Tip: Twin elements are displayed in the File Browser Conflicts mode.

The final case, “pathname cycle”, occurs when two sibling workspaces make contradictory changes to the depot’s directory hierarchy, then promote the changes to the common parent stream. For example, one workspace might move directory src under directory util, while another workspace moves util under src. When both the changes are promoted to the parent stream, AccuRev won’t be able to determine the correct pathname for these directories and the elements under them. The two directories assume (stranded) status, and the elements under these directories become inaccessible.

Ability to Operate on Stranded Elements Using Element-IDs

The CLI provides tools for relieving situations involving stranded elements. The move, defunct, and undefunct commands support the –e option, which enables you to specify an element by its element-ID, rather than by its pathname. This is necessary for situations in which the desired element does not have a pathname in the workspace or stream.

See Handling Stranded Elements.

Sophisticated Analysis of Namespace-Related Changes

AccuRev distinguishes between these two changes to the pathname of an element:

•	Renaming of the directory in which the element resides. This is not considered a change to the element itself; it is a change to the parent-directory element.

•	Moving of the element from its current directory to another directory in the depot. This is considered a change to the element itself (and not a change to either of the parent-directory elements).

For example, suppose that file element commands.java resides in directory cmd_interface. A colleague changes the name of the directory to cli in her workspace, then promotes the change to the parent stream. When you update your workspace, the pathname of the file changes from .../cmd_interface/commands.java to .../cli/commands.java, as a “side effect” of the change to the parent directory. Note that this is not a change to the commands.java file element itself.

On the other hand, if the colleague moves file commands.java to another directory, say .../cmd_interface/utils/commands.java, this is a change to the file element. When you update your workspace, the pathname of the file changes accordingly (unless you have made a namespace-related change to the file, in which case a merge is required).

AccuRev implements this scheme by tracking an element’s parent directory by its element-ID (which never changes), rather than by its name (which can change, and can vary from stream to stream).

Change to Merge Algorithm for Namespace-Related Changes

The algorithm used by the Merge command (both in the GUI and the CLI) uses the analysis described in the preceding section. Merge may perform two separate namespace-related steps:

•	Element name merge — required when the simple name of the element being merged differs in the two contributor versions.

•	Path merge — required when the parent directory of the element being merged differs in the two contributor versions.

Often, either or both of these steps will be performed automatically by Merge. If only one of the two contributors differs from the versions’ closest common ancestor, then that contributor’s change is applied automatically.

(Note that Merge may also need to perform a third step — a content merge — for a file element.)

The following example of the CLI merge command involves both kinds of namespace-related changes: (1) a file’s simple name has been changed by two users, john and mary; (2) each user has moved the file to different sibling directory.

> accurev merge file01.mary
Current element: \.\dir02\sub03\file01.mary
most recent workspace version: 4/2, merging from: 5/5
common ancestor: 5/3

Both “path” and “element name” conflicts must be resolved manually, but
the contributors’ contents can be merged automatically.

Path merge will be required.
Element name merge will be required.
Automatic merge of contents successful. No merge conflicts in contents.

Path conflict for \.\dir02\sub03\file01.mary

John moved the file from directory sub02 to directory sub01 (which has element-ID 68).
Mary moved the file from directory sub02 to directory sub03 (which has element-ID 82).

Resolve path conflict by choosing path from:

(1) common ancestor: \.\dir02\sub02\ [eid=75]
(2) backing stream : \.\dir02\sub01\ [eid=68]
(3) your workspace : \.\dir02\sub03\ [eid=82]

Actions: (1-3) (s)kip (a)bort (h)elp

action ? [3] 2

John renamed the file from from file01.txt to file01.john.
Mary renamed the file from from file01.txt to file01.mary.

Resolve name conflict by choosing name from:

(1) common ancestor: \.\dir02\sub01\file01.txt
(2) backing stream : \.\dir02\sub01\file01.john
(3) your workspace : \.\dir02\sub01\file01.mary

Actions: (1-3) (s)kip (a)bort (h)elp

action ? [3] 3

The content merge is performed automatically.

Actions: keep, edit, merge, over, diff, diffb, skip, abort, help

action ? [keep]

Moving \.\dir02\sub03\file01.mary to \.\dir02\sub01\file01.mary
Kept element \.\dir02\sub01\file01.mary