Views

How many Views do I needGenerally, one per discrete task is a good idea, though this is not a requirement. Views should be regarded as "cheap" entities that are easily created and destroyed. Create one for each task you need to do and when that task is done, delete the view.

How to Create a View

cleartool mkview -tag atag storage-location

Where "atag" is the view-tag (the "name" of the view which should be a mnemonic name that you can easily remember) and storage-location is the location of a place on a disk where the view can store information.

How to Delete a ViewWhere "atag" is the view-tag of the view you want to remove.

Modifying Files

CheckoutTo modify an element you need to check it out. Do this with the following command:

cleartool co anelement

where "anelement" is the name of the file or directory you want to check out.

CheckinOnce you are happy with the changes you have made to a checked-out element, you can check it in with the following command:

cleartool ci anelement

where "anelement" is the name of the file or directory you want to check in. Once you check-in an element, the changes you made to that element are usable by everyone on your project.

UncheckoutIf you want to cancel a checkout, you can do so with the following command:

cleartool unco anelement

where "anelement" is the name of the file or directory you want to check in.

Creating New Files

CreationTo create a new file, you can use whatever editor or command you would normally use to create the file. The new file will be a view-private entity until you take the next step to put it under ClearCase control.

Putting a File Under Version ControlTo put a file under ClearCase control you must first check-out the directory that will be containing the file, issue the command to tell ClearCase to put the file under version control, and then check-in the directory containing the new file. Here are commands to perform these steps:

cleartool co thedirectory cleartool mkelem thefile cleartool ci thedirectory

After this sequence is performed, the file "thefile" is still checked-out and can be modified further before you check it in.

Deleting ElementsTo remove an element you should use the "cleartool rmname" command. This command removes the name of the specified element from the directory in which it is contained. Similar to placing an element under ClearCase control, you must first check-out the directory containing the element to be removed, do the "cleartool rmname" of the element, and then check-in the new version of the directory. Here is an example:

cleartool co thedirectory cleartool rmname anelement cleartool ci thedirectory

After this sequence, "anelement" is no longer listed in subsequent versions of "thedirectory". It is, however, still listed in previous versions of the directory. If, at a later date you want to re-add "anelement" to a new version of "thedirectory" (or any other directory), you can do so easily.

Renaming ElementsRenaming an element is similar to deleting it. First you check-out the old

directory containing the element, and you also check-out the new directory to which the element is to be moved. Then you use the "cleartool mv" command to perform the move operation. Be sure to check-in the old and new directories when you are done.

cleartool co . cleartool co newdirectory cleartool mv anelement newdirectory cleartool ci . cleartool ci newdirectory

Renaming an element is also accomplished using the "cleartool mv" command except the old directory and the new directory are the same.

cleartool co . cleartool mv anelement anewname cleartool ci .

In subsequent versions of the directory, the name "anelement" will not appear, having been replaced by "anewname" but the name "anelement" will still appear in prior versions of the directory. Both the names "anewname" and "anelement" will still refer to the same element; only the name associated with the element in the directory will have changed.

Getting Information

About ViewsWhat View am I in?

At any given time you can tell what view you are in by issuing the following command:

cleartool pwv

"pwv" means "print working view" in the tradition of the UNIX command "pwd" for "print working directory"

What is my "config-spec"?Recall that a configuration specification (config-spec) is the set of rules that tells ClearCase what configuration of elements you want to work with. You can see that set of rules by issuing the following command:

cleartool catcs

How do I change my config-spec?You can edit your config-spec by issuing the following command:

cleartool edcs

Your favorite editor , as specified by the environment variable WINEDITOR (first choice), VISUAL (second choice), or EDITOR (third choice) will be invoked for the editing operation. If none of these environment variables is set then vi will be invoked for the editing operation on UNIX systems and Notepad will be invoked for the editing operation on Windows systems.

About Files/Directories

What is checked-out and to whom?If you want to see who has what checked-out, you can use the "cleartool lsco" command. This command has a number of possible arguments to use depending on the specific information you want. Here are some common ones:

cleartool lsco

Lists all checkouts of elements in the current directory.

cleartool lsco anelement

List checkout information about the element "anelement".

cleartool lsco -recurse

Lists all checkouts of elements in the current directory and below.

cleartool lsco -cview

Lists checkouts of elements in the current directory that are checked-out to the current view.

cleartool lsco -cview -recurse

Lists checkouts of elements in the current directory and below that are checked-out to the current view.

cleartool lsco -me

Lists checkouts of elements in the current directory that the current user has checked-out.

cleartool lsco -user fred

Lists checkouts of elements in the current directory that the user with login id "fred" has checked-out.

Please refer to the ClearCase Reference Manual for more detailed information about the "cleartool lsco" command.

What is the change history of this file/directory?If you want to see the change history associated with a particular element, you can use the "cleartool lsh" command.

cleartool lsh anelement

Where "anelement" is the name of an element under ClearCase control

What versions of what files/directories am I looking at?To see exactly what versions of elements are being projected to you by your view and why, you can use the "cleartool ls" command.

cleartool ls

What are the differences between this version of a file/directory and a different version?To view the differences between the versions of an element visible in your view and another version of the element you can use the "cleartool diff" command.

cleartool diff -g -pred anelement

Graphically presents the differences between the version of "anelement" selected by your view and it's immediate predecessor version.

cleartool diff -g anelement anelement@@/main/5

Graphically presents the differences between the version of "anelement" selected by your view and version 5 on the main branch of "anelement"

You can also use this command without the "-g" option to present the difference information to you textually rather than graphically.

See the "cleartool diff" entry in the ClearCase Reference Manual for more detailed information on these commands.

What does the version tree look like for this file/directory?To view a graphical representation of the version tree associated with an element you can use the "xlsvtree" command.

cleartool lsvtree –g anelement

You can view a textual representation of the version tree associated with an element with the "cleartool lsvtree" command.

cleartool lsvtree anelement

I want more information about this element?You can get more detailed information about a particular element with the "cleartool describe" command.

cleartool describe anelement

Lists information about "anelement" such as the version selected by your view, who created it and when, the comment associated with the version, the element type and the predecessor version.

From the Command Line,

 

Command Help Provided

cchelp Launches hypertext-based help system which includes all manuals and has a search mechanism

ct help Lists all cleartool subcommands

ct help

<command> OR

ct <command> -help

Shows syntax of <command>

ct man <command> Man page on <command>

ClearCase Commands : Basics

01. To get help

DOS bigots will appreciate the intuitive nature of the Unix equivalent of 'Help': 'man' (aka Manual Pages)

To get help on the entire command set enter:cleartool man

To get help on a specific command enter:cleartool man command(eg: cleartool man co for help on the checkout command)

02. To enter Cleartool

cl<return>The prompt will change to cleartool.

03. To exit Cleartool.

exit<return>orquit<return>

04. To navigate inside Cleartool

Use the standard cd or cd .. commands to navigate the directory tree.

Warning! Be aware that if you exit from Cleartool back to the shell after having moved around in the directory tree within Cleartool, that you will NOT be returned to the directory that you were in when you entered Cleartool from the shell.

The pwd (present working directory) command can help you keep track of where you are.

05. To enter graphics mode (slow but gorgeous).

cl xlsvtree filenameorxcleartool

The xlsvtree graphics viewer is a powerful tool for viewing the version tree of a file. It is very useful for visual diffing of one version of the file against another, labelling versions or moving labels around.

ClearCase Commands : File Checkin Checkout

06. To check out a file.

cleartool checkout file.extorcl co file.extcl co -c "comment" file.ext

End comment with: <ret>.<ret>or <ctrl><d>

Cleartool will prompt for a comment if you do not use the third format to supply one.

Although you may not be used to providing a description of the changes at checkout time ot is good practice to enter the reason you are checking out the file.

Other team members can then see who has the file out and why.

When you check the file back in this text will be presented as the default ci change description, which you can override. If you are forethoughtful about the comment most often it will not need to be re-typed when you do the checkin.

The file checked out stays in the same directory but the permission changes from read only to read/write.

07. To cancel a checkout.

cl unco file.ext

08. To check out a previous version of a file.

This should be:cl co file.ext@@/main/version#>and it is a defect in the tool that this command is not implemented.

Instead, you will have to do a tap dance to get the version you want in your view:

#1. cl co file.ext

#2. cl exit to return to the shell

#3. pwd to make sure you are in the right directory at the shell level. If not, navigate to the right directory.

#4. cp file.ext/main/version# tmpfile.ext

You can then change tmpfile as required, cp/copy it to the atria directory with the correct name, enter cleartool again and check the file in. Exit cleartool to the shell to rm/delete the temporary file. Using a tmp_name will help ensure that you don't screw up and delete the atria archive file by mistake!

09. To find what you have checked out.

cl lsco -me -all

Remember to do this at the end of your session to make sure you have not forgotten to check back in files and directories.

Other team members cannot access the files for update until you have checked them back in, and will have to waste time diffing and merging your changes with theirs if they are forced to use private copies.

10. To find out what other files are checked out.

cl lsco -all

11. To check in a file.

cleartool checkin file.extorcl ci -c "comment" file.ext

Cleartool will display the comment you entered at co time as the default. You may override this if you want to.

End comment with <ret>.<ret> or <ctrl>-d

Do NOT use -nc which means no comment.Comment your versions!!!!

12. To checkin or checkout multiple files.

To check in, or check out multiple files at once with the same comment:

cl ci -c "comment" *cl co -c "comment" *

ClearCase Commands : Labels

13. To list existing labels.

cl lstype -lbtype

14. To observe the naming conventions for branches and labels.

branch names: all lower case eg: forwarding, ip, gap

LABELS : ALL UPPER CASE eg: BETA_2.5, PRE_GAP_MERGE

15. To Make a label.

cl mklbtype BETA_1.1B

Note: The convention for labels is as above: all caps.

16. To label a version of a file.

cl mklabel -c "comment" -rec x.

Warning! Do not confuse these foolishly named operations:mklbtype makes (creates) a new label.whereasmklabel ATTACHES the label made by mklbtype to a specific file.

17. To apply a label to the entire source tree.

This is typically done for alpha, beta, final releases so that the entire set of files with the label can be built.

#1 Use 'catcs/edcs' (Tip 43) to set up your configspec withelement * MyLabelelement * /main/LATEST

#2 mklbtype MyLabel and enter appropriate comments.

#3 Be in the top level (/src) directory.To apply the label throughout the tree:mklabel -recurse -c "X Release" MyLabel .Wait a long time.

18. To move an existing label down to the latest elements.

mklabel -recurse -replace MY_LABEL

will move existing label MY_LABEL down to the latest revision of each file in the directory, and below, from which you invoke this command.

'replace' is a poorly named option: it really means 'move-down'.

19. To see if a label is on the latest version of a file or on a branch.

cl find -version 'lbtype(LABELNAME) && version(/main/LATEST)' -print orcl find . -version 'version(/main/LATEST) && ! version(/main/GAP)' -print

You can do lots of mix and match to find what you want.

ClearCase Commands : File and Version Information

20. To change the comment for a revision.

Many revision control tools won't let you change a comment once committed, on grounds of theology (Tichy didn't permit it), or control freakieness (typically MIS installations).

Cleartool is realistic, and accomodating, so you have a chance to correct and revise comments as needed.

chevent -c "comment" -rep file.name@@/main/version#will replace an existing comment for revision n on the main trunk.

chevent -c "comment" -rep *will replace the existing comments on the latest revisions of all files in the current directory.

21. To change the content description for a file.

When you set up a file initially on atria with -mkelem, you can use the -c "comment" qualifier to record a description of the contents of the file.

To change this subsequently:

chevent -c "content description" -rep file.ext@@/main/version#

22. To list the history (versions with comments) of a file.

cl lshist -all -since 08:00 file.ext

will list all changes made to the file since the time specified.

23. To Find out what files have been worked on since a given date.

It is sometimes very useful to get a list of all the changes made to the source tree since a given date.

cl lshist -all -since 31-Jul-96.23:59

24. To find out the file_type of a file.

This is useful to confirm that a file is stored by Cleartool in an appropriate format.

Element type : Use withtext_file : Flat ascii text filefile : Any binary file that you don't mind Cleartool compressing for storage.compressed_file : Binary file that's already compressed and you want Cleartool to store as-is.

To find this out enter:describe file.extordescribe *

25. To setup cleartool to send email on a file change.

You may want to cause e-mail to be sent to email handle 'supercon' when a particular file has been updated.

This is particularly useful, for example, if you have patched the source in a commercial library and you want to be sure that when the library is upgraded your changes do not get overwritten, as the newest version of the library may or may not have corrected the error your patches peviously corrected.

The e-mail notification acts as a helpful reminder to re-test for the bug which was encountered in the earlier version, and re-update and re-build the commercial library if the library vendor did not fix the problem.

How to do it:

#1: Get VOB access.

#2: Create an e-mail notification script in unix format and add it to atria. For example:

Courtesy aric kollmyer:#!/bin/shmailx -s "Cleartool warning: Reminder on zLib update" superconENDMAIL New Version of dialog.cppcreate: $CLEARCASE_PN by:$CLEARCASE_USER Comment string:

-------------Someone has really done it now, they installed a new version of zLib!.This may cause problems as I made the following patches to :dialog.cpp in the zDialogFrame::create() method to correct .....So, you had better re-test with the new zApp libraries linked in andverify that trhe new library fixes this problem-Me Self (555) 123-4567 Quincy, CA meself@hotmail.comENDMAIL

#3: Register the script file as a trigger.cl mktrtype -nc -element -postop checkout -exec <nameAndFullPathOfScriptFile> <nameOfTrigger>

Example:

cl mktrtype -nc -element -postop checkout -exec/gl/vobs/netman/src/zapp/source/glenayre.sh glenTrigger

#4: Attach the trigger to an existing element:

cl mktrigger -nattach <nameOfTrigger> <nameOfElementToAttachItTo>

Example:

cl mktrigger -nattach glenTrigger dialog.cpp

The examples shown will send e-mail document to supercon when dialog.cpp is checked-out.

ClearCase : Directory Operations

26. To add a new directory to the source tree.

Again a multi part operation as, to achieve transparency, directories are themselves vob (versioned) objects.

#1 First checkout the directory under which you want to create the new sub-directory.cl co -c "Add directory xxx" .

The period indicates that you are checking out a directory.

#2 mkdir xxx

#3 Give the new directory privilege level 775cl protect -chmod 775 .

#4 To verify the privilege level is 775ls -adl .

The directory attribute string should be: d rwr rwr r-x (7 7 5)

These last two steps will ensure that someone else can later manipulate the directory without having to come back to you to beg for the privilege!

27. To rename a directory in the /gl/vobs/netman/src tree.

Eg: /src/ui/thunk_ar

#1 Change to the directory you want to rename eg: /ui/thunk_ar and check it out:cl co .

#2 Checkout the directory above the directory you want to rename : eg /uicl cd..cl co .

#3 Rename the directory by mv'ing it:cl mv thunk_ar thunk_31

#4 Check in the directories:cl ci .

cl cd thunk_31cl ci .

28. To rename a vob directory or element.

Checkout the directory that contains the directory or element to be renamed.Docl mv oldname newnamefor the directory or element. Check it in.

ClearCase Commands : File Add Move Rename

29. To Add a new file to an existing directory.

This is multi part operation as to achieve transparency, cleartool directories are themselves versioned. So ...

#1 First, you have to checkout the directory, because adding a file will change the directory. Enter a checkout comment which can also serve as the check in comment later.

cl co -c "Add file xxx" .

The period indicates that you are checking out a directory.

#2 Make an (empty) file 'element'

cl mkelem -c "file description" file.ext

NOTE! This assumes that the new element has an extension that is known to Cleartool. If not, and you get a gobbledegook message 'Cant pick element type from...' then you must specify an element type eg:

cl mkelem -c "Config stuff" -eltype text_file cb.cfg

The file types are:

text_file : Flat ascii text file file : Any binary file that you don't mind Cleartool compressing for storage. compressed_file : Binary file that's already compressed and you want Cleartool to store as-is.

#3 Copy the source code to the new file.

#4 Checkin the file. This will be the first revision.cl ci -c "comment" file.ext

#5 Check the directory back in.cl ci .

The default comment you supplied in #1 above sbould be ok.

#6 You should check that you have set up the file with an apppropriate storage type. See: Tip 24 'To find out the file type of a File'.

30. To use symbolic links avoid duplicating an archive file in different directories.

Suppose we have directory A with archived file.ext eg: /../VOBS/.../A/file.ext and we want to have the same file in Directory B.

Rather than duplicate the file, we can place a link in directory /../VOBS/.../B to point to the 'real' archive file in directory A.

To setup the link:

Change to the B directoryCheckout the B directory: cl co -c "Link to file A" .Change to the A directoryEnter: cl ln -slink /../vobs/.../A/file.ext /../vobs/.../BChange to the B directory and do a ls -al to inspect the links.

31. To move an atria file from one directory to another.

Check out the source directory :co .

Check out the target directory :co .

In the source directory type :mv file.ext /gl/vobs/netman/src/etc/etc/newfile.ext

32. To make a view private copy of a file.

co -unreserved

33. To Cleartool 'rm' an atria archive file.

First enter the ClearCase tool:

cl

Once INSIDE the ClearCase toolrm filename

This will remove the archive from the view, but it is still accessible and can be viewed or retrieved if you need it again at some later time.

Warning! If you use rm filename outside Cleartool ie at the shell level the file is GONE!

34. To look at a file that has been Cleartool 'rm'd'.

more .@@/main/5/file.ext@@/main/LATEST

Replace '5' with the last version of the directory that contained the file.

Instead of more you can use less - see man less for info.

ClearCase Commands : Branches  35. To list existing branches.

cl lstype -brtype

36. To Make a branch.

#1 cl mkbrtype Eagleand enter appropriate comments (doesn't matter where in the tree you are).

#2 mklbtype Eaglebase and enter appropriate comments.

#3 Be in the top level (/src) directory.mklabel -recurse Eaglebase .to apply the label throughout the tree.Wait a long time.

#4 Edit your configspec to use the branch.Note that if you use the graphical (xlsvtree) viewer to look at a file at this point, the new branch will not show up. No, you didn't do anything wrong. The new branch will not be Created until you check the file out.

37. To merge a branch back to the mainline.

Finally, a chance to screw up bigtime!

#1 Use 'catcs' ( Tip 23 : Look at your configspec ) to ensure that your view is currently set to the main line.

#2 Change the directory to the root of the source tree.

#3 Label the entire source tree PRE_WHATEVER_MERGE so that if you screw up big time it'll be easier for people to check out files bsu.

#4 cl findmerge . -fver /main/BRANCH_NAME -merge -xmerge

This command will, for all the files on the branch:

present side-by-side Mainline-Branch-FinalMerged windows for all non-trivial merges back to the mainline.

Check out the file, and put the contents of the FinalMerged window in it.Create a matching file.contrib file.

We're not going to try and verify the merge here and now. Click 'y' to accept the generated merge files, until all the files are processed.

#5 In the root directory you will find a FILExxxx log, listing all the files merged. Print it.

#6 Using the log printout as a control:

Use xlsvtree or something equivalent to diff the checked out file against the predecessor file on the main-line.Verify the merged file is the way you want it and edit it if not.Build the app to verify the changes are (syntactically) valid.Regression testing the app would be nice.Checkin the verified files to the mainline.- rm the file.contrib files. Try not to rm the file object by mistake.

#7 Note! There is no such thing as a valid merged .dlg file!

Bring up the latest mainline and latest branch .dlg files in a resource editor and hand tool the changes!

ClearCase Commands : Releases

38. To build a release.

#1 Use catcs / edcs to set up your configspec withelement * LabelToBuildFrom

#2 IMPORTANT! Make sure that you have commented out with the '#' symbol:#element * /main/LATEST

Failure to do this will mean that later file versions updated AFTER the labelled versions will get into the build!

39. To obtain a directory listing of the source tree for a release.

#1 Use Tip 13 command to get a list of existing labels.

Write down the label for the release you want eg 'RELEASE_2.02'.Get it right!

#2 Use Tip 43 to add this line to your configspec:element * RELEASE_2.02before the existing:element /gl/vobs/netman/src/docs/.../main/LATESTelement * main/LATEST

Save the configuration, exit, and reply yes to confirm the configspec change.

#3 Open /install/bmp/splash.bmp or title.bmp in PaintBrush to confirm that the configspec change has worked and you are accessing the source version you require.

#4 Do a:dir s: /s > release.xxxto do a recursive directory listing of the s: source drive using the view set by the new configspec, and pipe the result to a file.

#5 Don't forget to change your configspec back to normal!

40. To obtain a list of file changes since the last release.

This is useful when you want to do a code review prior to a new release.

In the directory at the top of the src tree:

find . -version 'version(/main/LATEST)&& !lbtype(RELEASE_3.0)' -exec 'echo $CLEARCASE_PN >> pooh.bar'

This will recursively examine the source tree and output to pooh.bar a list of the files with head versions with no label ie the changes since the last label was applied to all the files.

ClearCase Commands : Administrator

41. To remove (destroy) the latest version(s) of a file.

Warning! Don't do this without being sure you know what you are doing!

This command will chop off the latest version from a file, including versions above it if the version is not the latest one! rmver file.exe@@/main/version#

42. To look at your configspec.

catcs

This will display the directives that Cleartool is currently using to filter files into your logical 's:' drive. eg:

# Setup to access the main branchelement * /main/LATEST

#Setup to build an entire labelled version#and ONLY files labelled this way#element */main/LATEST

must be commented out#or files added/changed later than this will get included in the build#element *RELEASE_3.01

# Setup to access the tigger branch# element * /main/tigger/LATEST# element * /main/tiggerBase -mkbranch tigger# element * /main/LATEST -mkbranch tigger

43. To change your configspec.

edcs