Rules for selecting versions of elements to appear in a view
Product | Command Type |
---|---|
ClearCase | data structure |
ClearCase LT | data structure |
Platform |
---|
UNIX |
Windows |
Standard Rule:
Create Branch Rule:
mkbranch branch-type-name [ -override ]
...
[ end mkbranch [ branch-type-name ] ]
Time Rule:
time date-time
...
[ end time [ date-time ] ]
File-Inclusion Rule:
Load Rule (for snapshot views):
A view's config spec (configuration specification) contains an ordered set of rules for selecting versions of elements. The view's associated view_server process populates a view with versions by evaluating the config spec rules. For more information about view_server, see the Administrator's Guide.
In a dynamic view, version selection is dynamic. Each time a reference is made to a file or directory element-either by ClearCase software or by standard programs-the view_server uses the config spec to select a particular version of the element. (In practice, a variety of caching techniques and optimizations reduce the computational requirements.)
In a snapshot view, users invoke an update operation to select versions from the VOB.
UCM config specs are different from those for base ClearCase and base ClearCase LT in that their rules are generated, not user-specified-read UCM CONFIG SPECS before reading any other section of this reference page.
Each view is created with a copy of the default config spec, default_config_spec:
element * CHECKEDOUT | (For any element, select the checked out version, if any) |
element * /main/LATEST | (otherwise, select most recent version on the main branch) |
Modifying this file changes the config spec that newly created views receive, but does not affect any existing view.
An individual view's config spec is stored in its view storage directory, in two forms:
Source format - The user-visible version, config_spec, contains only the series of config spec rules.
Compiled format - A modified version, .compiled_spec, includes accounting information. This version is created and used by the view_server process.
Do not modify either of these files directly; instead, use the commands listed below. Different views' config specs are independent: they may contain the same set of rules, but changing one view's config spec never affects any other view.
Commands for manipulating config specs:
catcs | Lists a view's config spec. |
Makes a specified file a view's config spec. | |
Revises the current config spec of a view. | |
update -add_loadrules | Adds load rules to the config spec of a snapshot view while updating the view. |
The set of elements considered for version selection is different for the two kinds of views:
In a dynamic view, all elements in VOBs mounted on the current host are considered for version selection.
In a snapshot view:
If you are updating a loaded element, the behavior is the same as in a dynamic view and the selected version is loaded into the view.
If you are not updating and the element is loaded, the selection from the last update is used.
If the element isn't loaded at all, the behavior is the same as in a dynamic view.
For each element, the following procedure determines which version, if any, is in the view.
The view's associated view_server process tries to find a version of the element that matches the first rule in the config spec:
If such a version exists, that version is in the view.
If multiple versions match the rule, an error occurs, and no version of the element is in the view. ClearCase and ClearCase LT commands that access the element print errors like this one:
cleartool: Error: Trouble looking up element "ht.c" in directory ".".
Standard commands that access the element print errors like this one:
The request could not be performed because of an I/O device error.
If no version matches the first rule, the search continues.
If no matching version was found for the first rule, the view_server tries to find a version that matches the second rule.
The view_server continues in this way until it finds a match or until it reaches the last rule.
Because the rules in a config spec are processed in order, varying the order may affect version selection. For example, suppose this rule appears near the beginning of a config spec:
element * /main/LATEST
Any subsequent rules in the config spec will never be used, because the rule will always provide a match; every element has a most-recent version on its main branch.
NOTE: The order in which the load rules for a snapshot view are specified is not important.
The config spec for a snapshot view must contain element * CHECKEDOUT as the first element rule.
If no version of an element matches any rule in the config spec:
In a dynamic view:
The element's data is not accessible through the view. The operating system listing command and other standard programs print a not found
error when attempting to access the element.
The ClearCase/ClearCase LT ls command lists the element with a [no version selected]
annotation. You can specify the element in commands that access the VOB database only, such as describe, lsvtree, and mklabel.
In a snapshot view, the element will not be loaded.
A view's config spec has no effect on the private objects in a view, such as view-private files, links, directories; or, in the case of a dynamic view, derived objects. View-private objects are always accessible.
Exception: (Dynamic views only) If a config spec lacks a CHECKEDOUT rule, the view-private file that is a file element's checked-out version is not visible. See Special Version Selectors below.
Each config spec rule must be contained within a single physical text line; you cannot use a backslash (UNIX), caret (Windows), or other line continuation character to continue a rule onto the next line. Multiple rules can be placed on a single line, separated by semicolon (;) characters.
Lines that begin with a number sign (#) are comments.
Extra white space (SPACE, TAB, vertical-tab, and form-feed) characters are ignored, except within the version selector. If a version selector includes white space, enclose it in single quotes.
If a load rule specifies a file or directory name that includes one or more SPACE characters, you must enclose the entire pathname in either single-quotes (`) or double quotes (").
In general, VOBs, views, and the ClearCase and ClearCase LT tools that access them are case-sensitive. Therefore, config spec rules must use case-correct pathnames.
You can use slashes ( / ) or backslashes ( \ ) as pathname separators in pathname patterns and version selectors unless you are sharing the config spec between UNIX and Windows hosts. In that case, you must use slashes. (See SHARING CONFIG SPECS BETWEEN UNIX AND WINDOWS HOSTS.)
Windows and UNIX clients can share config specs, which are portable between the two operating systems. That is, clients on both systems, using views whose storage directories reside on either kind of host, can set and edit the same set of config specs. However, Windows and UNIX network regions often use different VOB-tags to register the same VOBs. Only single-component VOB-tag names, like \src2vob, are permitted on Windows clients; multiple-component VOB-tags, like /vobs/src/proj1, are common on UNIX. When the VOB-tags diverge between regions, config spec element rules that use full pathnames (which include VOB-tags) are resolvable (at config spec compile time) only by hosts in the applicable network region. This implies a general restriction regarding shared config specs: a given config spec must be compiled only by hosts on one operating system or the other-the operating system for which full pathnames in element rules make sense. That is, a config spec with full pathnames can be shared across network regions, even when VOB-tags disagree, but it must be compiled in the right place.
This restriction does not apply if any of the following are true:
The config spec's element rules use relative pathnames only, which do not include VOB-tags.
Shared VOBs are registered with identical, single-component VOB-tags in both Windows and UNIX network regions. (The VOB-tags \r3vob and /r3vob are logically identical, differing only in their leading slash characters.)
The config spec does not include any load rules or element rules.
An in-use config spec exists in both text file and compiled formats (both of which are visible in the view's storage directory). A config spec in its compiled form is portable. The restriction is that full VOB pathnames in element rules must be resolvable at compile time. A config spec is compiled if a client executes either of these cleartool commands: edcs or setcs -current. Therefore, if a client on the "wrong" operating system recompiles a config spec with one of these commands, the config spec becomes unusable by any client using that view. If this happens, simply recompile the config spec on the "right" operating system.
A sample element rule that could be problematic:
element /vob_p2/src/* /main/rel2/LATEST
If the VOB is registered with VOB-tag \vob_p2 on a Windows network region, but with VOB-tag /vobs/vob_p2 on a UNIX network region, only Windows clients can compile the config spec.
When writing config specs to be shared by Windows and UNIX clients, use the slash (/), not the backslash (\), as the pathname separator in pathname patterns and version selectors. ClearCase and ClearCase LT on Windows can parse either separator in pathnames; ClearCase and ClearCase LT on UNIX recognizes / only.
A standard version-selection rule takes this form:
The following subsections describe these components.
The scope specifies that the rule applies to all elements, or restricts the rule to a particular type of element.
Selecting Versions of VOB Symbolic Links. There is no VOB symbolic link scope. A VOB symbolic link is cataloged (listed) in one or more versions of a directory element. The link appears in a view if both of these conditions are true:
One of those directory versions is selected by the view's config spec.
The config spec includes any element rule, even a -none rule.
A pathname pattern, which can include any ClearCase/ClearCase LT wildcard (see the wildcards_ccase reference page for a complete list). For example:
A view-extended pathname pattern is not valid.
A relative pathname pattern must start below the VOB-tag (VOB mount point, VOB root directory). For example, if the VOB-tag is /vobs/project, project/include/utility.h is not a valid pattern.
A full pathname pattern must specify a location at or beneath a valid VOB-tag. For example, if the VOB-tag is /vobs/project, then /vobs/project/... and /vobs/project/include/... are both valid.
The setcs or edcs command fails if it encounters an invalid location in any config spec rule:
cleartool: Error: No registered VOB tag in path: "..."
VOB symbolic links are not valid in pathname patterns.
On Windows systems, patterns can be specified using either backslashes (\) or slashes (/).
You can use a version label, version-ID, or any other standard version selector. See the version_selector reference page for a complete list. Some examples follow:
Standard version selectors cannot select checked-out versions in a config spec rule. (They can in other contexts, such as the find command.) Instead, you must use the special version selector, CHECKEDOUT, described below.
Special Version Selectors. The following special version selectors are valid only in a config spec rule, not in any other version-selection context:
No such file or directory
) error when a standard UNIX operating system program references the element. For dynamic views:
|
|
|
error on reference
.Some config spec rules can include an additional clause, which modifies the rule's meaning.
date | := | day-of-week | long-date |
time | := | h[h]:m[m][:s[s]] [UTC [ [ + | - ]h[h][:m[m] ] ] ] |
day-of-week | := | today |yesterday |Sunday | ... |Saturday |Sun | ... |Sat |
long-date | := | d[d]-month[-[yy]yy] |
month | := | January |... |December |Jan |... |Dec |
create version
event records. (No error occurs if you use a -time clause in a rule that does not involve the version label LATEST; the clause has no effect.)/main/LATEST -time 10-Jul.19:00 | Most recent version on main branch, as of 7 P.M. on July 10. |
.../bugfix/LATEST -time yesterday | Most recent version on a branch named bugfix (which can be at any branching level), as of the beginning of yesterday (12 A.M.). |
/main/bugfix/LATEST -time Wed.12:00 | Most recent version on subbranch bugfix of the main branch, as of noon on the most recent Wednesday. |
-time 5-Dec.13:00 | December 5, at 1 P.M. |
-time 11:23:00 | Today, at 11:23 A.M. |
-time 12-jun-99 | June 12, 1999, at 00:00 A.M. |
-time now | Today, at this moment. |
-time 9-Aug.10:00UTC | August 9, at 10 A.M. GMT. |
|
|
A config spec can include a cascade of auto-make-branch rules, causing checkout to create multiple branching levels at once. checkout keeps performing auto-make-branch until version 0 on the newly created branch is not selected by a rule with a -mkbranch clause; then, it checks out that version. For example:
(1) |
element * CHECKEDOUT |
(2) |
element * .../br2/LATEST |
(3) |
element * .../br1/LATEST -mkbranch br2 |
(4) |
element * MYLABEL -mkbranch br1 |
(5) |
element * /main/LATEST |
(1) |
element * CHECKEDOUT |
(2) |
element * ...\br2\LATEST |
(3) |
element * ...\br1\LATEST -mkbranch br2 |
(4) |
element * MYLABEL -mkbranch br1 |
(5) |
element * \main\LATEST |
If you check out an element in a view that currently selects the version labeled MYLABEL:
A branch of type br1 is created at the MYLABEL version (Rule (4)).
Rule (3) now selects the newly created version .../br1/0, so a branch of type br2 is created at that version.
Version .../br1/br2/0 is checked out. The checked-out version has the same contents as the MYLABEL version, and is selected by Rule (1). When you edit and check in a new version, .../br1/br2/1, the view will select it with Rule (2).
A create branch rule takes the following form:
mkbranch branch-type-name [ -override ]
<config spec lines>
[ end mkbranch [ branch-type-name ] ]
This rule is similar to the -mkbranch clause; use it when you want to add a -mkbranch clause to many lines in a complex config spec.
mkbranch and end mkbranch rules may be nested. For example:
element * .../branch2/LATEST
mkbranch branch2
element * .../branch1/LATEST
mkbranch branch1
element * /main/LATEST
end mkbranch branch1
end mkbranch branch2
Checking out foo.c creates foo.c@@/main/branch1/branch2/CHECKEDOUT. This is a multiple-level mkbranch.
time date-time
[ end time [ date-time ] ]
It is analogous to the -time clause. A time rule modifies the meaning of the special version label LATEST in subsequent rules, with the following exceptions:
An optional -time clause in a particular rule overrides any general time rule currently in effect.
A subsequent time rule cancels and replaces an earlier one.
Use end time to limit the effect of a time rule to a certain range. The date-time argument is optional with end time, but if you include it, it must match the date-time argument specified with the time rule.
The date-time specification is evaluated when you set or edit the config spec, and whenever the view_server process is started (for example, with startview or setview (dynamic views only)). Thus, the meaning of a relative specification, such as today, may change over time. However, the date-time is not evaluated at run time. So if you last performed one of the commands listed above four days ago, the meaning of a relative specification, such as today, has the value of the date four days ago, not the value of the date today.
Time rules may be nested. They may not include any query language constructs.
A file-inclusion rule takes this form:
The argument specifies a text file containing one or more config spec rules (possibly other include rules). Include files are reread on each execution of setcs and edcs. A file-inclusion rule must be the last rule in a line. For example,
time date-time; include config-spec-pname
Load rules define which elements are loaded (copied) into a snapshot view (by contrast, element rules define which version of an element is selected). A load rule takes this form:
The argument specifies one or more file or directory elements. Naming a directory element implies the directory and all elements below the directory. Naming a file element specifies that element only. Wildcarding is not supported: you must explicitly specify all elements to be loaded.
More than one load rule can appear in a config spec; you must have at least one to see any files in a snapshot view. (Load rules in the config spec of a dynamic view are ignored.)
Load rules can be positioned anywhere in a config spec, and their order is irrelevant.
An element can be selected by more than one load rule without causing an error.
On UNIX systems, hard VOB links are followed; symbolic links are copy-created.
On Windows systems VOB links (both symbolic links and hard links) are followed.
In all cases, the link target is copied into the snapshot view at the location in which the link appeared.
UCM config specs are unlike config specs for base ClearCase and base ClearCase LT in that they are generated by mkstream and regenerated from time to time by chstream and rebase. You may edit UCM config specs only as follows:
To add custom element-selection rules.
To add custom load rules for snapshot views.
Only custom rules that are correctly delimited are preserved when a UCM config spec is regenerated.
NOTE: Never use UCM-generated rules in config specs for base ClearCase or base ClearCase LT.
Add custom element-selection rules only between the custom element delimiters, as follows:
#UCMCustomElemBegin - DO NOT REMOVE - ADD CUSTOM ELEMENT RULES AFTER THIS LINE
rule
.
.
.
#UCMCustomElemEnd - DO NOT REMOVE - END CUSTOM ELEMENT RULES
The typical use for custom element selection is to add an include rule that enables the UCM view to see the contents of base ClearCase or base ClearCase LT VOBs. See FILE-INCLUSION RULES.
Add custom load rules after the custom load delimiter, as follows:
#UCMCustomLoadBegin - DO NOT REMOVE - ADD CUSTOM LOAD RULES AFTER THIS LINE
rule
.
.
.
See LOAD RULES for more information.
NOTE: In the UNIX examples that follow, arguments and output that show multicomponent VOB tags are not applicable to ClearCase LT, which recognizes only single-component VOB tags. In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf-for example, /vobs/src. A single-component VOB tag consists of a leaf only-for example, /src. In all other respects, the examples are valid for ClearCase LT.
Include a standard set of rules to be used by every user on a particular project.
include /proj/cspecs/v1_bugfix_rules
Modify the meaning of "most recent" to mean "as of 7 P.M. on July 10."
time 10-Jul.19:00
element \atria\lib\* ...\new\LATEST
element * \main\LATEST
end time
Select version 3 on the main branch of a particular header file.
element /usr/project/include/utility.h /main/3
Select the most recent version on the main branch for all elements with a .c file-name extension.
element *.c \main\LATEST
Select the most recent version on the bugfix branch.
element * .../bugfix/LATEST
Select versions of elements from a particular development branch, or with a related label.
Select versions of C language source files (.c file extension) based on the value of an attribute. A config spec such as this may be used by a developer to select versions of files for which he is responsible.
Use the -mkbranch qualifier to create a new BL3 branch automatically. Create the branch off the version labeled BL2.6, or the latest version on the main branch if no version is labeled BL2.6.
Same as above, but use a mkbranch rule.
element * CHECKEDOUT
element * .../bl3_bugs/LATEST
mkbranch bl3_bugs
element -file * BL2.6
element -file * /main/LATEST
end mkbranch bl3_bugs
Select the version labeled REL3 for all elements, preventing any checkouts to this view:
element * REL3 -nocheckout
Select the most recent version on the bug_fix_v1.1.1 branch, making sure that this branch is a subbranch of bug_fix_v1.1, which is itself a subbranch of bug_fix_v1.
element * CHECKEDOUT
element * bug_fix_v1.1.1\LATEST
element * ...\bug_fix_v1.1\LATEST -mkbranch bug_fix_v1.1.1
element * ...\bug_fix_v1\LATEST -mkbranch bug_fix_v1.1
element * \main\LATEST -mkbranch bug_fix_v1
When a user checks out an element for which none of these branches yet exists, a cascade of
auto-make-branch activity takes place:
Z:\myvob>
cleartool checkout -nc .
Created branch "bug_fix_v1" from "." version "\main\0".
Created branch "bug_fix_v1.1" from "." version "\main\bug_fix_v1\0".
Created branch "bug_fix_v1.1.1" from "." version
"\main\bug_fix_v1\bug_fix_v1.1\0".
Checked out "." from version
"\main\bug_fix_v1\bug_fix_v1.1\bug_fix_v1.1.1\0".
Modify the previous config spec to create branch bug_fix_v2 off an existing branch rather than creating multiple subbranches.
element * CHECKEDOUT
mkbranch bug_fix_v2 -override
element * .../bug_fix_v1.1.1/LATEST
element * .../bug_fix_v1.1/LATEST -mkbranch bug_fix_v1.1.1
element * .../bug_fix_v1/LATEST -mkbranch bug_fix_v1.1
element * /main/LATEST -mkbranch bug_fix_v1
end mkbranch bug_fix_v2
For a snapshot view, select the most recent version on the main branch. Use load rules to select in the applets VOB all elements below the \cmdlg directory and one specific element in the \testdlg directory.
element * CHECKEDOUT
element *... \main\LATEST
load \applets\cmdlg
load \applets\testdlg\opendlg.h
/usr/atria/default_config_spec
view-storage-directory/config_spec
view-storage-directory/.compiled_spec
ccase-home-dir\default_config_spec
view-storage-directory\config_spec
view-storage-directory\.compiled_spec
catcs, checkout, checkin, edcs, ls, mkbranch, setcs, setview, version_selector, csh(1), Administrator's Guide
Feedback on the documentation in this site? We welcome any comments!
Copyright © 2001 by Rational Software Corporation. All rights reserved. |