Understanding References

StarTeam creates at least one reference to a folder or item whenever:

You create or add a folder or item.
A branching child view is created that will contain that folder or item. As a branching child view is created from its parent, a subset of the folders or items in the parent becomes part of the child view. StarTeam automatically shares the folders and items in that subset into the child view.
You manually share a folder or item from one location to another.

As you add, share, or move a folder or item, more than one reference to it may occur if the view is a child view that branches and floats, or if the view has child views that branch and float.

Actions Causing StarTeam to Create References

For example, suppose you want to move a file from one folder to another in the same view. Suppose that the view has two child views, both of which contain the file. That means that there are at least three references to this file, one in each of three views. Now, you move the file to another folder in the same view. The reference in the current view is moved to represent the new location of the file. Depending on the properties of the two child views, a new reference may be created for the file in each of the child views. The references in those child views to the file in its original location still exist, because the application does not assume that you want to change those references just because you have moved the file in the current view. You may end up with five references to this file that formerly had three references.

Note: Most administrators avoid branching, floating views if users are likely to perform many operations that result in additional references. For example, moving and sharing can result in multiple unwanted references to the same folders or items, which can cause confusion.

The following table explains what references StarTeam creates in the current view, the recipient view, the parent of the recipient view, and the children of the recipient view. This is often recursive. For example, if a reference is created in the parent view, new references might be created in the other children of that view or in the parent of that view, and so on, depending on what views are floating.

When a folder or item is...	...is a reference added to the view of the recipient?	...is a reference added to the parent view of the recipient view?	...is a reference added to the child views of the recipient view?
Part of a newly-created view	Yes, unless the new view is a reference view. In this case, a new view is not really being created, because a reference view is just a new way of looking at an existing view.) There is one reference for the folder or item in the newly-created view.	No, because the parent view is the source of the folder or item, so the reference in the parent view already exists.	No, because the newly-created view has no child views.
Added to the current view	Yes, there is one reference for the new folder or item in the current view.	Yes, if the current view is a branch none, floating child of the parent view. Otherwise, no.	Yes, if the child view is a branching (either branch none or branch all), floating child of the current view. Otherwise, no.
Shared within the current view	Yes, a new reference is created for the shared folder or item in the new location in the current view.	Yes, if the current view is a branch none, floating child of the parent view. Otherwise, no.	Yes, if the child view is a branching (either branch none or branch all), floating child of the current view. Otherwise, no.
Moved within the current view	No, the original reference is updated to reflect the move.	Yes, if the current view is a branch none, floating child of the parent view. Otherwise, no.	Yes, if the child view is a branching (either branch none or branch all), floating child of the current view. Otherwise, no.

How to View References

Consider the following example of four references that would display in the Folder References dialog box:

Help Files::Help Files::Help Files::starteam,1.0
Help Files::Help Files\Freeze Check::Help Files\release 4\starteam, 1.0
Help Files::Help Files\Freeze Check\New View::\Help Files\release 4\starteam, 1.0
Help Files::Help files\variant 2::Help Files\release 4\starteam, 1.0.1.2

In the above example, the selected folder has four references.

The Current icon indicates which reference represents the currently selected folder or item. Otherwise, this dialog contains the same information regardless of the view in which you selected the folder.

Each reference shows the following, separated by double colons (::):

The project name (for example, Help Files).
The path from the root view to the view containing the folder (or item). For example, Help Files\Freeze Check\New View, where Help Files is the name of the root view, Freeze Check is a child of the root view, and New View is a child of the Freeze Check view.
The path to the folder within the view. In the case of an item, the path is to the parent folder of the item.
In the case of an item, the name or number associated with that item. This can be the filename, change request number, the requirement number, the task number, or topic number.
The tip revision number for the folder (or item) in that view. (This information is separated from the rest of the reference by a comma, rather than the double colon.) For example, the folder in the example is revision 1.0 in all views except for the variant 2 view (see the last leaf in the example tree). In the variant 2 view, the revision number for the folder is 1.0.1.2 which indicates that the folder has been branched from the 1.0 revision in its parent view and has had three revisions in the variant 2 view. Those revisions are 1.0.1.0, 1.0.1.1, and 1.0.1.2.

In this example, the name of the project, the name of the root view, and the root folder in the root view all have the same name.

You can resize the Folder References dialog box (by dragging an edge or corner). It displays scroll bars when appropriate. The references in bold indicate which revisions of the currently selected folder or item are its descendants. In other words, the currently selected folder or item is part of the revision history for the references that are in bold.

Consider the following example from the Reference tab shows the references for a file (AUDITSCC.DOC). The reference for the currently selected file indicates that revision of the file is 1.6. As indicated by the bolding of its reference, revision 1.8 is the only descendant of revision 1.6. If a defect is found in revision 1.6 of AUDITSCC.DOC, the bolding helps you determine which descendants of 1.6 may also need the corrected lines. In this case, you may only new to update 1.8.

Help Files::Help Files::Help Files\starteamp::AUDITSCC.DOC, 1.8
Help Files::Help Files\Freeze Check::Help Files\starteamp::AUDITSCC.DOC, 1.1
Help Files::Help Files\Freeze Check::New View2::starteamp::AUDITSCC.DOC, 1.1.1.0
Help Files::Help Files\varc::Help Files\starteamp::AUDITSCC.DOC, 1.6
Help Files::Help Files\variant 2::starteamp::AUDITSCC.DOC, 1.2

Initial References

When you add a folder or item to the application, StarTeam creates a reference. Consider the following example of a folder hierarchy for a newly-created project. In this example, it is the folder hierarchy for the root view of that project.

Before you make any changes to the folder properties of the Source Code folder, the Folder References dialog box would contain exactly one reference to it. For example, Big Product::Big Product::Big Product\Source Code, 1.0.

As you make changes to the folder properties of the Source Code folder, the revision number might change from 1.0 to 1.1 and later 1.2. However, there will still be only one reference to this folder in the Folder Reference dialog box.

If a reference view is created (to be used, for example, by a group of reviewers), the view hierarchy for the Big Product project would contain two views, but the Source Code folder would continue to have just one reference. A Reference view contains a subset of the folders in its parent view, but those folders are the same folders as those in the parent view. They cannot branch. For example, after creating a reference view for reviewers, the Folder References dialog box would contain the following information:

Big Product::Big Product::Big Product\Source Code, 1.2.

Once you share the folder manually or share it automatically when you create a branching child view, additional references then display in the Folder References dialog box.

Tip: Do not confuse reference views with folder and item references. A reference view looks like a new view, but it is really a subset of an existing view. A folder or item reference is like a reference count. It indicates how many copies of the object exist or can exist if the object branches in each of its new locations. The creation of a reference view does not result in the creation of any folder or item references.