References Created by Branching Views

When you create a branching view, each folder or item automatically shared from the parent view to the child view acquires an additional reference. In the view hierarchy (which you can display from View > Select View ), the new reference is a child of the original reference.

Folder References Created by Branching Views

Suppose that when the 1.0 version of Big Product ships, the team leader creates a branching view (based on the ship date for the 1.0 version) to be used for service packs, while new development on version 2.0 still continues in the project root view. These actions would result in the following view hierarchy:

  • Big Product
  • blank Big Product 1.0 Plus Service Packs
  • blank Reference view for reviewers

At this point, two references display in the Folder References dialog box. When you are in the root view, Big Product, the Folder References dialog box for the Source Code folder contains the following information:

  • indentedtopcurrent Big Product::Big Product::Big Product\Source Code, 1.2
  • indentedsecondcurrent Big Product::Big Product\Big Product 1.0 Plus Service Packs::Big Product\Source Code, 1.2

When you are in the child view, Big Product 1.0 Plus Service Packs, the Folder References dialog box for the Source Code folder contains the following information:

  • indentedtopcurrent Big Product::Big Product::Big Product\Source Code, 1.2
  • indentedsecondcurrent Big Product::Big Product\Big Product 1.0 Plus Service Packs::Big Product\Source Code, 1.2

The Current (You Are Here) Current Icon 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. StarTeam indents the reference for a child view beneath the reference for its parent. The references in bold indicate which revisions of the folder or item are descendants of the folder or item with the Current (You Are Here) Current Icon icon. In other words, the current folder or item is part of the history for the revisions that are in bold.

In the previous two examples, both references were represented in bold text. In the next example, this is not the case. This is because the properties of the Source Code folders in both the parent view and the child view have changed. The folder for the parent has revision 1.3, and the folder for the child has revision 1.2.1.0. Both folder histories have gone in different directions.

  • indentedtopcurrent Big Product::Big Product::Big Product\Source Code, 1.3
  • bottom Big Product::BigProduct\Big Product 1.0 Plus Service Packs::Big Product\Source Code, 1.2.1.0

The current folder is a descendant of itself, so it is always represented in bold text. However, it has evolved from the parent folder, so it is no longer in the history of the current folder. Accordingly, the Folder References dialog box for the parent folder would present the following information:

  • IndentedNotCurrentTop Big Product::Big Product::Big Product\Source Code, 1.3
  • indentedsecondcurrent Big Product::BigProduct\Big Product 1.0 Plus Service Packs::Big Product\Source Code, 1.2.1.0

File References Created by Branching Views

When you look at the history of a folder or item, you see its ancestors, not its descendants. However, if you change the tip revision in one location and that revision is an ancestor of the tip revision in another location, you might also want to apply your change to the tip revision in the other location (the object of the first descendant). The way to tell if a revision has descendants is to look at its references. Consider the following example showing the references for a file (AUDITSCC.DOC):

  • IndentedNotCurrentTop Help Files::Help Files::Help Files\starteamp::AUDITSCC.DOC, 1.8
  • Indentedfoldericon Help Files::Help Files\Freeze Check::Help Files\starteamp::AUDITSCC.DOC, 1.1
  • Indentedfoldericon Help Files::Help Files\Freeze Check::New View2::starteamp::AUDITSCC.DOC, 1.1.1.0
  • blank indentedsecondcurrent Help Files::Help Files\varc::Help Files\starteamp::AUDITSCC.DOC, 1.6
  • blank bottom Help Files::Help Files\variant 2::starteamp::AUDITSCC.DOC, 1.2

As the bold text indicates, if the current revision is 1.6, then 1.8 is its only descendant. This also means that you would find revision 1.6 in the history for 1.8.

If a defect is found in revision 1.6 of AUDITSCC.DOC, the bold text helps you determine the descendants of 1.6 that may also need the corrected lines. In this case, 1.8 may need to be updated. The other references are for revisions of the file that:

  • Have already diverged (branched) and may be quite different than the current file.
  • Are ancestors of the current file and less likely to need a change. For example, they may be in views that are read-only or no longer in use. Whatever the reason for the gap, the ancestors might require far more work than the changes you are about to check in.

You should check for descendants before (and perhaps after) you create a new revision of a folder or item. Before the change becomes a new revision in the application, you can see the descendants. Afterwards, you may see what other references have the same revision number as the newly-changed folder or item. If they, too, have the new revision number, then they, too, already have the new change. For example, the file may be floating in other views.

Parent topic: References Overview