2.5 Snapshot View: Selecting and Loading Elements

After you set up version-selection rules for a snapshot view, the View Creation Wizard starts the VOB Namespace Browser (Figure 10) from which you select the files and directories to load into the view.

Figure 10 Choosing Elements to Load

To Choose Elements

To choose the elements you want to load into your view, browse through the Available Elements list. To load an element, move it to the Selected Entries list. Keep the following in mind:

• If you load a directory element, all of its files and subdirectories are loaded into the view.

• If you load a specific file element, only that file is loaded into the view. To maintain the file's path, ClearCase also copies into the view the empty directories leading up to the VOB directory.

Figure 11 illustrates the results of the load operation.

Figure 11 A View with Loaded Elements

For each element specified in the Entries to Load box, the View Creation Wizard adds a load rule to your config spec. For example, the Choose Elements to Load box shown in Figure 10 creates these two load rules:

load \design\func_specs
load \dev\hello_world\lib.c

Using these rules, ClearCase loads the directory element \design\func_specs and every element below it, along with the file element \dev\hello_world\src\lib.c. To maintain the path to lib.c, the View Creation Wizard creates the directory \dev\hello_world\src in the view.

Case-Sensitivity

If you're selecting elements from VOBs located on a UNIX host, you may encounter problems that are due to case-sensitivity. Because native file systems for UNIX are case-sensitive, it is possible to create two elements from a UNIX host whose names differ only in capitalization. For example, in a UNIX VOB, these two elements are distinct:

/design/func_specs/bas
/design/func_specs/Bas

However, Windows does not support case-sensitive file lookups and does not distinguish the two elements in the previous example. If you were to load these two elements, only one of them would have the correct data when copied into the view; duplicated files are reported as hijacked. (Hijacked files are discussed throughout Appendix A, Working in a Snapshot View While Disconnected from the Network.)

The Administrator's Guide for Rational ClearCase discusses case-sensitivity issues in depth. We suggest that you not use mixed-case names for elements that you store in VOBs.

Setting Up for a New Development Project

If none of your development project's files and directories are under ClearCase source control, you can close the Choose Elements to Load box by clicking OK. The section To Add Elements for a New Development Task describes how to add elements to the VOB for a new development project.

Loading Versions of Elements into a View

When you close the Choose Elements to Load box, ClearCase loads elements as follows:

1. It uses the version-selection rules to select one version of each element specified by a load rule.

2. It copies the version into the snapshot view.

3. It records which version it copies into the view.

As ClearCase loads files and directories into your view, it shows a progress indicator in the Snapshot View Update dialog box. The complete list of files copied into your view appears in the Snapshot View Update window.

Under the Hood: VOB Links

A VOB link makes a file element or directory element accessible from more than one location in the VOB namespace. There are two kinds of VOB links: symbolic links, which are available for file and directory elements, and hard links, which are available for file elements only. We recommend that you use VOB symbolic links instead of VOB hard links whenever possible. In Figure 12, the directory element include is linked.

Figure 12 VOB Link

You use the cleartool ln command to create VOB links. For more information, see the ln reference page in the Command Reference.

Symbolic Links and Hard Links in Dynamic Views

In dynamic views (which use the MVFS, or multiversion file system), VOB links behave similarly to symbolic links or hard links in a UNIX file system: symbolic links point to a file or directory element in a different location, and hard links are alternate names for a single file element.

You cannot check out a VOB symbolic link; you must check out the symbolic link target.

When you check out a hard-linked element from a given pathname, ClearCase considers other pathnames for the element as "checked out but removed." That is, to prevent you from modifying the element from multiple pathnames, ClearCase executes standard checkout behavior at only one pathname (the one from which you entered the checkout command), but does not create view-private files at other pathnames. For information about standard checkout behavior, see the checkout reference page in the Command Reference.

Symbolic Links in Snapshot Views

Snapshot views created from a Windows host do not support links. ClearCase approximates VOB symbolic link behavior in the following ways:

• If a load rule selects a symbolic link, ClearCase copies the link target into the view at the link's pathname.

We recommend that you do not load a linked directory more than once in your view unless it is necessary for build purposes. Although ClearCase keeps track of multiply loaded elements accurately, you may become confused and modify the wrong copy of a file, losing information upon checkin. For more information, see Caution: Losing Data Because of VOB Hard Links.

• You cannot check out a file element from a symbolic link pathname; you must check out the link target. In ClearCase Explorer, the shortcut menu for a symbolic link includes the Explore Link Target command, which displays the link target's parent directory. Use this command to find and check out the link target.When you check in the modified link target, ClearCase updates all associated symbolic links loaded in your view. Unlike directory link targets, you can check out a file link target only if it is loaded in your view.

• The Add to Source Control command (available from ClearCase GUIs) checks out, modifies, and checks in the link target directory whether you issue the command from a directory symbolic link or from the link target (and whether or not the target directory is loaded into the view).

If you issue the cleartool checkout command from a symbolic link directory, you must use the following syntax:

cleartool checkout .

A checkout command issued for the current directory checks out the link target whether or not the target directory is loaded into the view.

However, if you use the cleartool checkout dirname form of the command to check out a different directory, dirname must be a link target.

When either you or ClearCase checks in a link target directory, ClearCase updates the associated symbolic links that are loaded in your view.

• If you hijack a file symbolic link, the Update Tool detects it. However, you cannot check out the hijacked symbolic link. To add your hijacked changes to the VOB, you must check out and modify the link target.

Hard Links in Snapshot Views

Each time a load rule selects a hard link, ClearCase loads the element into the view as a standard file.

Caution: Losing Data Because of VOB Hard Links

If you load multiple instances of a hard-linked element into a snapshot view, you must be careful to check out, modify, and check in only one instance of the file.When you check in a hard-linked file (or a file below a symbolic-linked directory), ClearCase updates all other instances in your view, which could result in loss of data if you modified multiple copies of the same file. (Note that, when updating instances of files because of a checkin, ClearCase renames any hijacked file to filename.keep before updating it.)

For example, the following sequence of events will lead to lost data:

1. You check out the hard-linked file src\util.h.

2. ClearCase removes the read-only attribute from util.h in the src directory only (which is the location from which you issued the checkout command).

3. You modify src\util.h but do not check it in.

4. Later, you lose track of which file you checked out. You then remove the read-only attribute and modify util.h in the temp directory.

5. You check in temp\util.h. Even though you checked out and modified src\util.h, ClearCase does not prevent you from checking in temp\util.h; with a VOB hard link, temp\util.h is just another name for src\util.h.

6. Any changes you made to src\util.h are lost upon checkin because ClearCase updates all copies of duplicated files when you check in an element. Note that ClearCase does not consider any copy of util.h to be hijacked (even if you change attributes), because you checked out the element in the VOB.