Rational ClearCase Commands Referenceannotate
apropos
catcr
catcs
cc.icon
cc.magic
cd
chactivity
chbl
checkin
checkout
checkvob
chevent
chflevel
chfolder
chmaster
chpool
chproject
chstream
chtype
chview
clearaudit
clearbug
cleardescribe
cleardiffbl
cleardiff
clearexport_ccase
clearexport_cvs
clearexport_pvcs
clearexport_rcs
clearexport_sccs
clearexport_ssafe
clearfsimport
cleargetlog
clearhistory
clearimport
clearjoinproj
clearlicense
clearmake
clearmake.options
clearmrgman
clearprojexp
clearprompt
cleartool
clearviewupdate
clearvobadmin
comments
config_ccase
config_spec
cptype
credmap
creds
deliver
describe
diffbl
diffcr
diff
dospace
edcs
endview
env_ccase
events_ccase
export_mvfs
exports_ccase
file
find
findmerge
fmt_ccase
getcache
get
getlog
help
hostinfo
init_ccase
ln
lock
lsactivity
lsbl
lscheckout
lsclients
lscomp
lsdo
lsfolder
lshistory
ls
lslock
lsmaster
lspool
lsprivate
lsproject
lsregion
lsreplica
lssite
lsstgloc
lsstream
lstype
lsview
lsvob
lsvtree
makefile_aix
makefile_ccase
makefile_gnu
makefile_pmake
makefile_smake
makefile_sun
man
merge
mkactivity
mkattr
mkattype
mkbl
mkbranch
mkbrtype
mkcomp
mkdir
mkelem
mkeltype
mkfolder
mkhlink
mkhltype
mklabel
mklbtype
mkpool
mkproject
mkregion
mkstgloc
mkstream
mktag
mktrigger
mktrtype
mkview
mkvob
mount_ccase
mount
msdostext_mode
mvfslog
mvfsstorage
mvfstime
mvfsversion
mv
omake
pathnames_ccase
permissions
profile_ccase
promote_server
protect
protectvob
pwd
pwv
query_language
quit
rebase
recoverview
reformatview
reformatvob
register
relocate
rename
reqmaster
reserve
rgy_backup
rgy_check
rgy_passwd
rgy_switchover
rmactivity
rmattr
rmbl
rmbranch
rmcomp
rmdo
rmelem
rmfolder
rmhlink
rmlabel
rmmerge
rmname
rmpool
rmproject
rmregion
rmstgloc
rmstream
rmtag
rmtrigger
rmtype
rmver
rmview
rmvob
schedule
schemes
scrubber
setactivity
setcache
setcs
setplevel
setsite
setview
shell
snapshot.conf
softbench_ccase
space
startview
type_manager
umount
uncheckout
unlock
unregister
unreserve
update
version_selector
view_scrubber
vob_restore
vob_scrubber
vob_sidwalk
vob_snapshot
vob_snapshot_setup
wildcards_ccase
winkin
xclearcase
xcleardiff
xmldiffmrg
DESCRIPTION
A version selector identifies a version of an element in a version tree. You can use it with the –version command-line option, as part of a rule in a config spec, and as part of a version-extended pathname. The version selector has three general forms. Each identifies a version in a different way:
- By version ID
- By the version label attached to it
- By a query on the metadata attached to it, or some other version characteristic
A version selector selects one version of an element, no version of an element, or generates an error, if ambiguous.
Branch Pathnames
The branch pathname in a version selector identifies the branch on which a version resides. A branch pathname consists of a series of branch type names separated by slashes (UNIX) or backslashes (Windows). The root of a version tree is the main branch (default name: main), which must be the first entry in the branch pathname unless you use the ellipsis wildcard (not valid in version-extended pathnames). Examples:
| /main | main branch |
| \main\bugfix | bugfix branch, off the main branch |
| /main/motif/bugfix | bugfix branch, off the /main/motif branch) |
| \main\win32\bugfix\anne | jpb branch, off the \main\win32\bugfix branch |
SELECTION BY VERSION ID
Selects the version with the specified version ID. This form requires a branch pathname.
Examples:
| /main/2 | Version 2 on main branch |
| /main/bugfix/5 | Version 5 on bugfix branch off main branch |
| /main/motif/bugfix/1 | Version 1 on subbranch of /main/motif branch |
In a version-extended pathname, the version ID follows the element name and extended naming symbol (default: @@). For example:
| hello.c@@\main\4 | Version 4 on main branch of file hello.c |
| include@@\main\4\hello.h\main\3 | Version 3 on the main branch of file hello.h, in version 4 on the main branch of directory include |
Restriction: In a version-extended pathname, you cannot use the ellipsis wildcard (...):
| include.h@@/.../bugfix/REL2 | Is not valid |
SELECTION BY VERSION LABEL
Selects the version with the specified label. The branch pathname is optional, but the slash or backslash is required. Examples:
| \main\LATEST | Most recent version on main branch |
| ...\bugfix\REL2 | Version labeled REL2 on a branch named bugfix, at any branching level |
| \main\bugfix\REL2 | Version labeled REL2 on a bugfix branch that is a subbranch of main |
| \main\sunport\openlook\BUG3 | Version labeled BUG3 on a particular third-level branch |
| REL2 | Version labeled REL2 on any branch |
Restriction: In a version-extended pathname, you cannot use the ellipsis wildcard (...):
The label LATEST is predefined; it evaluates to the most recent version on each branch of an element. If the most recent version on the main branch is version 4, these two version selectors identify the same version:
A version selector can consist of a standalone label, such as REL2. But standalone labels can be ambiguous. For example, /main/bugfix/REL2 and REL2 may or may not be equivalent for a given element:
- If the REL2 label type was created as one-per-element (default), the two version selectors must be equivalent.
- If REL2 was created with mklbtype –pbranch, the label can be used once per branch. If the label is actually attached to two or more versions of an element, an error occurs. No error occurs for elements that happen to have only one instance of a one-per-branch label type.
Version Labels
Version labels appear as UNIX hard links or as additional Windows file system objects in an element's directory tree in version-extended namespace. (See the pathnames_ccase reference page.) If a version label was defined to be one-per-element, an additional link/file system object appears at the top level of an element's directory tree. For example, if BL3 is a one-per-element label, these version-extended pathnames are both unambiguous references to the same version:
In effect, this feature allows you to reference a version without knowing its exact location in the version tree.
If a label was defined with the –pbranch option, it does not appear in the element's top-level extended namespace directory (as implied earlier). Thus, if the one-per-element label, BL3, and the one-per-branch label, TEST_LBT, was attached to version \main\1 of file hello.c, its top-level extended namespace directory would look like this:
SELECTION BY QUERY
Selects the version that satisfies the specified query. The branch pathname is optional.
The query expression consists of one or more query primitives and operators, organized according to the syntax rules listed in the query_language reference page. Enclose the query expression in braces ({ }).
UNIX—Quoting
Enclose the entire version selector in single quotes (' ')—or double quotes (" ") if it includes spaces or characters that have special meaning to the shell. Use double quotes to set off string literals within the query expression.
| /main/{TESTED=="yes"} | The latest version on the main branch for which the TESTED attribute has the value yes |
| {hltype”(design_spec,<-)”} | The version on any branch that is the to-end of a hyperlink of type design_spec |
| /main/bugfix/”{!lbtype(REL2)}” | On bugfix branch, the latest version that is not labeled REL2 |
| “{created_by(jpb)&&pool(sr1)}” | The version on any branch created by user jpb that is stored in the sr1 storage pool |
Windows—Quoting
Additional quoting and/or character escaping conventions must be used, depending on the command interpreter you are using and whether or not you are using interactive mode cleartool.
The following examples assume interactive mode cleartool (cleartool> prompt), which removes the command interpreter's command-line processing behavior from consideration. In general, enclose the entire version selector in quotes if it includes spaces, and make sure to enclose string literals in double-quotes within the query expression.
| \main\{TESTED=="yes"} | The latest version on the main branch for which the TESTED attribute has the value yes |
| “{hltype(design_spec,<-)}” | The version on any branch that is the “to” end of a hyperlink of type design_spec |
| \main\bugfix\”{!lbtype(REL2)}” | On bugfix branch, the latest version that is not labeled REL2 |
| “{created_by(anne)&&pool(sr1)}” | The version on any branch created by user anne which is stored in the sr1 storage pool |
Branch Pathnames
If the version selector includes a branch pathname, the view_server selects the latest version on the branch that satisfies the query. If the version selector does not include a branch pathname, the view_server selects the version on any branch that satisfies the query. However, without a branch pathname, a query is ambiguous when more than one version of the element satisfies the query; versions on different branches, or two versions on the same branch, for example.
The version-selection operation fails if the query selects no version or is ambiguous.
A version-extended pathname can include a query, but is subject to the same restrictions as other version selectors of this form. That is, the query must select exactly one version to succeed. For example, this command displays the most recent version that has an attribute of type TESTED:
Note the use of quotes to prevent interpretation of the brace and parenthesis characters. As an alternative, you can quote the entire pathname:
If multiple branches have versions with a TESTED attribute, the version selector used in the examples above is ambiguous, and an error occurs.
Restriction: In a version-extended pathname, you cannot use both a branch pathname and a query:
| % cat "include.h@@/main/{attype(TESTED)}" | Is not valid |
| % cat "include.h@@/main/rel2_bugfix/{attype(TESTED)}" | Is not valid |
On UNIX systems, you can use the describe command to work around this restriction: