Version Control of Namespace-Related Changes : Twin Elements and Stranded Elements

Twin Elements and Stranded Elements
The improvements affect these areas of namespace-related functionality:
Handling of “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”; we won’t make that judgment.) AccuRev now tracks element names consistently, provides better information about the existence of twins, and provides tools for resolving unintended twin situations.
Detection of “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 significant improvements to the detection and reporting of 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 the changes to namespace-related functionality in detail.
Preventing Creation of Twins in Workspaces
Two checks performed by the Add to Depot command (CLI command: add) help to prevent twins from being created:
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 to Depot command is cancelled. If the element is (defunct) in the parent stream, an Add to Depot command succeeds.
In previous releases, the first check was performed for renamed elements as well as for defuncted elements. This check no longer takes place — see Ability to Reuse an Element Name after a Rename Operation below.
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 in the folders view and in the results of a Default Group or Defunct search. (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 File Browser’s Stranded search, 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.
Ability to Reuse an Element Name after a Rename Operation
AccuRev now offers improved support for “refactoring” operations over previous releases. Now, 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 new 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 Backed (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 File Browser’s Stranded search, and equivalently, the AccuRev CLI command stat –i now detect all known cases of stranded files:
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).
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 now provides improved tools for relieving situations involving stranded elements. The move, defunct, and undefunct commands now 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 on page 54.
More Sophisticated Analysis of Namespace-Related Changes
AccuRev now distinguishes between these two changes to the pathname of an 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) now uses the more sophisticated 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

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com