► ► ► Module 4

Working with Elements and Views

IBM Software Group

Essentials of Rational ClearCase

Module 4: Working with Elements and Views

Topics
Objectives............................................................................................................ 4-2
Adding Files to Source Control.............................................................................. 4-4
Comparing File and Directory Versions ............................................................... 4-11
Moving an Element ............................................................................................ 4-14
Viewing an Element History................................................................................ 4-20
The lost+found Directory................................................................................... 4-21
Finding Checkouts.............................................................................................. 4-23
Canceling a Checkout ........................................................................................ 4-25
Using a Version-Extended Name ........................................................................ 4-28
Removing a View ............................................................................................... 4-29

© Copyright IBM Corp. 2003 4-1

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Objectives

Objectives
Upon completing this module, you should be able to:
Š Add files to source control
Š Compare versions of elements
Š Move, rename, and remove elements and versions
Š View an element history
Š Find checkouts
Š Change an element checkout status
Š Cancel a checkout
Š Select versions other than those in your view
Š Remove a view

4-2 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Module Topics

Module Topics
Š Working with Elements
ƒ Adding files and directories to source control
ƒ Comparing versions of elements
ƒ Moving, renaming, and removing elements and versions
ƒ Viewing an element history
ƒ The lost+found directory
Š Working with Views
ƒ Finding checkouts
ƒ Changing a checkout status
ƒ Canceling a checkout
ƒ Specifying versions using version-extended names
ƒ Removing a view

© Copyright IBM Corp. 2003 4-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Adding Files to Source Control

Adding Files to Source Control

Š As you work on a project, you may create view-
private files that you want to add to source control
Š You can add
ƒ Files
ƒ Directories
Š Add files to source control
ƒ GUI — Add to Source Control
ƒ Command Line — mkelem
ƒ Utility — clearfsimport

You can add files to source control using the GUI, the CLI, or the clearfsimport utility.
The next few slides discuss the process and procedure for adding files to source control.
To find your view-private files within a directory, refer to the Kind column in ClearCase
Explorer. To search for view-private files across directories in dynamic views, you can
use the lsprivate command.
CLI Procedure
Usage:
lsprivate (dynamic views only)
Example:
<pat_r2_dev_view>% cleartool lsprivate
/vobs/Hardware/src/hello
/vobs/Hardware/src/test.c
/vobs/gui/motif/util.c [checkedout]
/vobs/gui/motif/util.o

4-4 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Adding Files to Source Control (cont.)

Adding Files to Source Control (cont.)

When you add a file to source control, ClearCase:
ƒ Determines the file type
ƒ Creates an element
ƒ Creates the /main branch and an empty version 0
ƒ By default, leaves the element checked out

You can create new ClearCase elements by adding files or directories to source control.
When you add a file or directory to source control, ClearCase determines the file type
and creates a new element. It automatically creates the /main branch and populates
the version tree with the empty version 0. On UNIX, the default is to leave the newly
added element checkedout.

© Copyright IBM Corp. 2003 4-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Adding a File to Source Control: CLI

Adding a File to Source Control: CLI

mkelem [-nco | -ci] [ -ptime ] [-c comment | –dfile pname | -cq |
-cqe | -nc] element-pname ...

1
Find the file to
add to source
control.
2
Checkout the
current directory.

3
Add the file to source control.

When you add a file to source control, you create a new element using the cleartool
mkelem command.
Check out the current directory before you execute the mkelem command.

4-6 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Adding a File to Source Control: GUI

Adding a File to Source Control: GUI

2
Click File > VOB object > Create element
from file.

3
Enter a
comment, and
then click OK.

1
Select the file to add to
source control.

You can also add files to source control through the File Browser.
By default, ClearCase keeps the file checked out once it has been added to source
control. In the Add to Source Control dialog box, clear the Keep checked out box if you
want ClearCase to check in the file.

© Copyright IBM Corp. 2003 4-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Adding a New Directory to Source Control

Adding a New Directory to Source Control

cleartool mkdir [-nco | -ci] [-c comment | -cfile pname | -cq |
-cqe | -nc] dir-pname ...

1
Checkout the current directory.

2
Make the new versioned directory.

When you add a parent directory to source control, ClearCase does not automatically
add all child objects to source control. They remain view-private unless you specifically
add them to source control.

4-8 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Adding Many Files or Directories

Adding Many Files or Directories

Š When you must add a number of files or directories
to source control use clearfsimport
Š clearfsimport is a command-line utility that converts
file system directories and files to ClearCase
elements
Š clearfsimport creates new elements or adds new
versions to existing elements

You must be root (UNIX) or the VOB owner to run clearfsimport unless you invoke it
with the -nsetevent option.

© Copyright IBM Corp. 2003 4-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Working with VOB Symbolic Links

Working with VOB Symbolic Links

Š A VOB symbolic link
makes a file element or
directory accessible from
more than one location in
the VOB
Š VOBs and directories are
sometimes symbolically
linked for organizational
purposes
Š Links are generally created
by the ClearCase
Administrator

10

Symbolic links make a file element or directory accessible from more than one location
in the VOB.
VOB symbolic links are usually set up by a ClearCase administrator and are generally
transparent to uses performing typical checkout/checkin activities.
However, if you want to change the contents of a symbolically linked directory, you
must check out the directory from its actual location and not its symbolic location.

4 - 10 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Comparing File and Directory Versions

Comparing File and Directory Versions

Š ClearCase allows you to compare element and directory
versions
Š Can compare a version with predecessor or with any
other previous version in the tree

Select the file,

and then click
Versions > Diff.

11

You can compare with the previous version or with another version in the tree.
For example, you might want to compare your checked-out version of an element to its
predecessor to see what changes you have made. Or, you might want to compare your
checked-out version to a particular historical version or a version being used by one of
your colleagues.
If the versions are identical, ClearCase asks you if you want to proceed with the
comparison.
The diff algorithm uses the appropriate utilities for the comparisons.
You can also use the ClearCase compare utilities to compare Rational Rose models,
Rational XDE models, XML, and HTML files.

© Copyright IBM Corp. 2003 4 - 11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Comparing File Versions

Comparing File Versions

The Compare tool displays a graphical comparison of
text files.

12

When you compare element versions graphically, the Compare tool displays the
contents of the file in side-by-side windows that scroll in unison. It points out
differences between the versions.
The Navigate menu allows you to jump easily from one difference to another.
This window, as you will see, is also the basis for merging. Many of the options will be
the same when we discuss merging in a later module.
CLI Procedure
Usage:
diff [-serial_format | -diff_format | -columns n] [-options pass-through-opts]
[-predecessor] pname ...
Example:
/vobs/Hardware/src% cleartool diff hello.c@@/main/1 hello.c
********************************
<<< file 1: hello.c@@/main/1
>>> file 2: hello.c
********************************
------------[changed 1-3]--------------|------------
[changed to 1-9]-----------
main() { +| #include "hello.h"+
printf("Hello, %s!\n", env_user() +

4 - 12 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Comparing Directory Versions

Comparing Directory Versions

The Compare tool enables you to view, side-by-side,
the elements appearing in two versions of a directory.
hello2.c was
changed to hello.c

util.h and newfile.c

test.c and Makefile2 were added
were deleted

13

CLI Procedure
Example:
/vobs/Hardware% cleartool diff -pre src
********************************
<<< directory 1: /vobs/Hardware/src@@/main/1
>>> directory 2: src
********************************
--------------|--------[ added ]---------------
| hello.h 03-Sep-2002 alex
--------------|--------[ added ]---------------
| util.c 03-Sep-2002 alex

© Copyright IBM Corp. 2003 4 - 13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Moving an Element

Moving an Element
move | mv [-c comment | -cfile pname | -cq | -cqe | -nc]
pname target-pname

1
Check out the to and from directories.

2
Move the file from
the source directory
to ../bin.

3
Checkin the source and destination
directories to complete the move.

14

During a development project, changes to the project may require you to move
elements from one directory to another, or even to another VOB.
Before you move an element, check out both the source and destination directories.
Moving elements affects other project members. Check with the project manager or a
ClearCase administrator before you move elements.
• Use the cleartool mv command to move an element from one VOB directory to
another.
• Use cleartool relocate to move an element between VOBs.

4 - 14 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Removing References to an Element: GUI

Removing References to an Element: GUI

Š Remove the name of an element or VOB symbolic link
from a directory list
Š The element still exists in the VOB

15

Because directories as well as files are under version control, you can remove elements
from a specific version of the directory. This will render the element invisible in the
directory, but does not permanently delete the element from the VOB. Moving or
removing elements creates new versions of the parent directories to record the
modifications.
For example, version 4 of /vobs/Hardware/src contains an element named util.c. If you
remove util.c from the src directory, ClearCase creates version 5 of vobs/Hardware/src,
which does not contain the util.c file element. The element util.c itself remains
unmodified, just not visible in the current (version 5) and future versions of the src
directory.
Removing references to elements affects other project members. Check with the project
manager or ClearCase administrator before you remove references to elements.

© Copyright IBM Corp. 2003 4 - 15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Removing References to an Element: CLI

Removing References to an Element: CLI

rmname [-c comment | -cq | -cqe | -nc][-nco [ -force]] pname ...

1
Check out the directory where
the element resides.

2
Remove the element name.

3
Check in the directory.

16

4 - 16 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Renaming an Element

Renaming an Element
1
Select element, and then click
File > VOB object > Rename 2
element or link. Enter the new file name,
and then click Ok

17

Renaming an element creates a new version of the parent directory to catalog the new
element name. The element uses its new name in subsequent versions of its parent
directory, but previous versions of the parent directory refer to the element by its
previous name.
Renaming elements affects other project members. Check with the project manager or
ClearCase administrator before you rename elements.
The cleartool move command can be used to move and rename elements form the
CLI.
CLI Procedure
Usage:
move | mv [-c comment | -cfile pname | -cq | -cqe | -nc] pname target-pname
Example:
/vobs/Hardware/src% cleartool move util.c newutil.c
Moved “util.c" to “newutil.c".

© Copyright IBM Corp. 2003 4 - 17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Removing a Version

Removing a Version
Š Deletes one or more
versions of an element
from the VOB
Š Removes all metadata
items that were attached
to the deleted version(s)

In the Version Tree Browser,

select the version, and then click
Version > Destroy > Version.

18

When you remove a version, other versions before and after the removed version(s)
remain accessible.
To remove a version, you must be one of the following:
• Version creator
• Element or VOB owner
• root
When removing versions, remember:
• If removing a non-text file element version, the data container is deleted.
• If removing a text file element version, ClearCase logically removes the version
from the data container. No disk space is recovered.
• The version-ID of a deleted version is never reused.
• You cannot delete a version from which there is currently a checkout.
• Subsequent references to a removed version produce an error.
CLI Procedure
Usage:
rmver [-force] [-version version-selector | -vrange low version high-version]
[-c comment | -cfile comment-file-pname |-cq | -cqe | -nc] pname ...
Example:
/vobs/Hardware/src% cleartool rmver
util.c@@/main/r2_int/pat_r2/2
Removing these versions of "util.c":
/main/r2_int/pat_r2/2
Remove versions? [no] y
Removed versions of "util.c".

4 - 18 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Removing an Element

Removing an Element
Removes an element COMPLETELY from the VOB;
there is NO WAY to restore it

Removes all references to it in ALL

directory lists

You cannot remove elements that

have checked-out versions

To remove an element, you must

be the element owner, VOB owner,
or have ClearCase administrative privileges

19

There may be rare instances when you want to remove an element completely from the
VOB.
CLI Procedure
Usage:
rmelem [-force] [-comment comment | -cfile comment-file-pname | -cquery
| -cqeach | -ncomment] pname ...
Example:
cleartool> rmelem util.c
CAUTION! This will destroy the element, all its branches and
versions, including all data, meta-data and history, and will
remove the element from all directory versions that now
contain it. Once you destroy the element, there will be no
way to restore it to its current state.
If you want to preserve the element, but remove references to
it from future directory versions, use the "rmname" command.
Element “util.c" has 1 branches, 2 versions, and is entered
in 1 directory versions.
Destroy element? [no] y
Removed element “util.c".

© Copyright IBM Corp. 2003 4 - 19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Viewing an Element History

Viewing an Element History

Š An element history is recorded in event records in the VOB
Š A ClearCase operation, such as checkout, causes an event
record to be created
Š Event records include: who, what, when, where, and
comments associated with the event

20

ClearCase records each operation, for example check in, check out, reserve and
unreserve, as an “event record.”
Events that change the content of elements are considered major, while other events
are considered minor.
CLI Procedure
Usage:
lshistory [-long | -short | -fmt format] [-eventid] [-minor] [-nco] [-since date-time]
[-pname] pname ... | object-selector ...]
Example:
/vobs/Hardware/src% cleartool lshistory hello.c
25-Oct.09:43 pat create version
"hello.c@@/main/r2_int/pat_r2/2"
"Working on changing the text of the STDOUT"
20-May-1993 rick create version "hello.c@@/main/3"
(R1)
"include name, home dir, and time in message”
"hello.c@@/main/1"
"first implementation"
04-May-1993 akp create branch "hello.c@@/main"
04-May-1993 akp create file element "hello.c@@"
"first implementation"

4 - 20 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

The lost+found Directory

The lost+found Directory

Š Found in every VOB at the highest directory level
Š Contains orphaned elements, which are elements
that are no longer cataloged in any version of any
directory
Š Orphaned elements can result when
ƒ User adds file or files to a directory, but then cancels
the directory checkout
ƒ User deletes a directory, but not its elements

21

Elements can become orphaned if a user:

• Cancels a checkout of a directory after adding a new element—it removes the
directory element, but not the file elements created in it.
• Removes a directory element without removing the file elements within the
directory.
Example:
/vobs/Hardware/src% cleartool co -nc src
/vobs/Hardware/src% cleartool mkelem -nc src/test.c
<modify test.c and check it in>
/vobs/Hardware/src% cleartool unco src
cleartool: Warning: Object “test.c" no longer referenced.
cleartool: Warning: Moving object to vob lost+found directory
as “test.c.96c93d305a5111ceb0200080c880e47f".
Checkout cancelled for "src".

© Copyright IBM Corp. 2003 4 - 21

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Module Topics

Module Topics
Š Working with Elements
ƒ Adding files and directories to source control
ƒ Comparing versions of elements
ƒ Moving, renaming, and removing elements and versions
ƒ Viewing an element history
ƒ The lost+found directory

Š Working with Views

ƒ Finding checkouts
ƒ Changing a checkout status
ƒ Canceling a checkout
ƒ Specifying versions using version-extended names
ƒ Removing a view
22

4 - 22 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Finding Checkouts

Finding Checkouts
The checkout reporting tool enables you to search for
checkouts based on user-defined criteria.

23

You can query ClearCase to find existing checkouts based on the criteria you designate.
CLI Procedure
The cleartool lsco command displays all checkouts of elements in the current directory
by any view.
Usage:
lscheckout | lsco [-long | -short | -fmt format] [-cview] [-me | -user login-name]
[-recurse | -directory | -all | -avobs ] [pname ...]
Example:
/vobs/Hardware/src% cleartool lsco -all
29-Oct.15:17 alex checkout directory version
"/vobs/Hardware/src" from /main/2 (reserved)
29-Oct.15:14 pat checkout version
"/vobs/Hardware/src/Makefile" from /main/r2_int/pat_r2/1
(reserved)
"updating file to reflect file renaming"
29-Oct.15:14 pat checkout version
"/vobs/Hardware/src/hello.c" from /main/r2_int/pat_r2/2
(reserved)
"Working on fixing typo in source"
29-Oct.15:17 alex checkout version
"/vobs/Hardware/src/hello.h" from /main/1 (reserved)
"updating header"

© Copyright IBM Corp. 2003 4 - 23

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Finding Checkouts

Finding Checkouts
Based on selection criteria, ClearCase displays a list
of the checked-out files in the checkouts window.

24

4 - 24 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Canceling a Checkout

Canceling a Checkout
Š Cancel a checkout when you do not want to save
changes or want a fresh copy
Š You can rename and save a view-private version of the
file: filename.keep. If you do not save the file, all
changes are lost

25

When you cancel a checkout, ClearCase asks if you want to save a view-private version
of the file. If you choose not to save a view-private version, any changes you made to
the checked out version are lost and cannot be restored. Be certain you do not need
the data before you decide not to keep a view-private version.

© Copyright IBM Corp. 2003 4 - 25

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Canceling a Checkout from the File Browser

Canceling a Checkout from the File Browser

Once you cancel a checkout, your view selects the
predecessor version.
2
Click Versions > Uncheckout,
and then choose the type of
uncheckout to perform.

1
Select the checked-
out element.

26

You can cancel a checkout at any time. When you do, your view selects the
predecessor version of the element. Once you undo a checkout, any changes you
made to the file are lost.
When you cancel a checkout, you can save a copy of the file with a .keep extension.
CLI Procedure
Usage:
uncheckout | unco [-keep | -rm] [-cact | -cwork ] pname ...
Example:
/vobs/Hardware/src% cleartool unco util.c
Save private copy of “util.c"? [yes] yes
Private version of “util.c" saved in “util.c.keep".
Checkout cancelled for “util.c".

4 - 26 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Selecting a Version Other Than Those in Your View

Selecting a Version Other Than Those in Your View

Š Enable you to specify a version that may not be
visible in your dynamic view
Š @@ (extended-naming symbol) denotes a path into
the version tree of an element
ƒ Specific integer versions
hello.h@@/main/r2_int/1
ƒ User-defined version labels
util.c@@/R1

27

Each version of an element has a unique identifier. From the command line interface,
you can use version-extended pathnames to access versions other than the ones
currently selected by your view.
Version-extended pathnames are useful when:
• Comparing
• Rebuilding objects
• Merging
CLI Procedure
To construct a version-extended pathname:
1. Enter the element name followed by the extended-naming symbol.
2. Add the branch pathname.
3. Add the version selector:
Full version-extended pathname example:
/vobs/Hardware/src/hello.h@@/main/r2_int/1
Where:
• hello.h@@ is the element name followed by the extended-naming symbol.
• /main/r2_int is the branch pathname.
• 1 is the version selector.

© Copyright IBM Corp. 2003 4 - 27

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Using a Version-Extended Name

Using a Version-Extended Name

Š Using a standard name, you access the version of the file
that your dynamic view selects:
/vobs/Hardware/src% cat hello.c
#include "hello.h"
printf("Hello, %s!\n", env_user() ); int main() {

printf("Your home directory is %s.\n", env_home()

);
printf("It is now %s.\n", env_time() );
return 0;
}

Š To see a version other than the one selected by your

dynamic view, use a version-extended pathname:
/vobs/Hardware/src% cat hello.c@@/main/r2_int/11
main() {
printf(“Hello there, world!\n);
}
28

Any time a version-extended name is NOT used in place of the file pathname itself,
ClearCase uses the version currently selected by the config spec of the view.

4 - 28 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Removing a View

Removing a View
Š Views are temporary, task-related objects; once a
specific development task or project is complete, remove
the view
Š Before removing a view, add all important view-private
files to source control or copy them to another location
Š Removing the view will:
ƒ Clean up VOB references to the view
ƒ Remove the view storage directory
ƒ Remove the view tag and unregister the view
ƒ Stop view server processes
Do NOT use UNIX Utilities to remove a view’s storage
directory
29

We recommend that views be considered task-related objects. When the task is

complete, remove the task-related view.
Before you remove a view, be sure to add all view-private files to source control or
move them to another location.
The Remove View tool:
• Purges view related records from all accessible VOBs.
• Removes view storage directory.
• Shuts down the view_server process.
• Removes entries from the ClearCase view registry.
NOTE: Objects created using ClearCase commands should only be removed with
ClearCase commands.Do not remove a view using UNIX utilities. Views are more than
just a directory; there is a server process and registry entries to remove.
CLI Procedure
Usage:
cleartool rmview [-force] {-tag dynamic-view-tag | dynamic-view-storage-pname}
Example:
/vobs/Hardware/src% cleartool rmview -tag pat_r2_view

© Copyright IBM Corp. 2003 4 - 29

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Module Review

Module Review
Š What does ClearCase do when you add a file to source
control?
Š What is the easiest way to add many files and directories to
source control in ClearCase?
Š What is the lost+found directory? Why is it significant?
Š How can you find out which VOB elements are checked out?
Š How do you access versions of elements other than those
selected by your view config spec?
Š Why would you want to remove a view?
Š Why should you not use operating system utilities to remove
a view?

30

4 - 30 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 4 - Working with Elements and Views

Module Lab

Module Lab
Š In this lab, you perform the following tasks:
ƒ Add files to source control
ƒ Move and rename an element
ƒ View an element history
ƒ Find checkouts
ƒ Access versions not selected by your view
ƒ Remove a view

31

© Copyright IBM Corp. 2003 4 - 31

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

4 - 32 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.