► ► ► Module 2

Working with Files Under Source Control

IBM Software Group

Essentials of Rational ClearCase

Module 2: Working with Files Under Source Control

Topics
Objectives............................................................................................................ 2-2
Checkout/Checkin Model..................................................................................... 2-4
Checking Out a File: File Browser......................................................................... 2-7
What Is a Version Tree?...................................................................................... 2-12
Viewing Versions of an Element Graphically........................................................ 2-14
What Are View-private Files? .............................................................................. 2-15
Branching Enables Parallel Development ............................................................ 2-16
The Default View Config Spec ............................................................................ 2-19
Creating a New Branch Automatically................................................................. 2-22

© Copyright IBM Corp. 2003 2-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:
Š Explain the checkout/checkin model
Š Explain the difference between a reserved and
unreserved checkout
Š Check out/check in files and directories
Š Define version trees and branches and explain
how branches enable parallel development
Š Edit a view config spec to automatically create a
branch

2-2 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Typical Workflow: Work on Files

Typical Workflow: Work on Files

© Copyright IBM Corp. 2003 2-3

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

Checkout/Checkin Model

Checkout/Checkin Model
Š When a file is under source control, you check it out to
work on it
Š A file is checked out to a
view and a modifiable
copy is available to work on
Š A placeholder is created in the
version tree as the potential
successor version
Š When you check in the file,
a new version is added to the
element version tree

ClearCase protects versions in the VOB from accidental modification, even by an

administrator. File elements are read-only until they are checked out.
At checkout, ClearCase makes a read/write copy of the element available to a view. It
creates a placeholder in the version tree as the potential successor version.
At checkin, ClearCase determines if the file is automatically accepted as the successor
version or if it is necessary to first integrate the file with other potential successor
versions.

2-4 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

View Before and After Checking out hello.c

View Before and After Checking out hello.c

In the example above, before checkout, a read-only version of hello.c is visible.

Upon check out, the object is copied to the view’s physical storage area. A write-
privileged file is now available in the view to work on.
The VOB knows which elements are checked out to what view.

© Copyright IBM Corp. 2003 2-5

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

Types of Checkout

Types of Checkout
Š Reserved checkout:
ƒ Default checkout
ƒ Has exclusive rights to next place on
version tree
ƒ No checkins can be made on the same
branch until the checkout is resolved
ƒ Only allowed if no other reserved
checkouts exist for the branch
Š Unreserved checkout:
ƒ Allowed regardless of the status of other
checkouts of the version
ƒ Before check in, must be merged or
discarded if any checkin has taken place
6

Checkout types are only important when more than one person is checking out on the
same branch.
The default status for a checkout is reserved. On a reserved checkout, ClearCase
creates a placeholder version. The successor version can come only from the view that
holds the reserved checkout. This means:
• No one can check in to the branch before the reserved checkout is resolved
• The checkout has exclusive rights to the next version in the tree
An unreserved checkout does not guarantee the right to create the successor version. If
several views have unreserved checkouts, the first view to check in the element creates
the successor; developers working in other views must merge the checked-in changes
into their own work before they can check in.
Scenarios where you would use an unreserved checkout:
• To help a fellow developer debug code, you need to add a debug statement to the
code
• You are using ClearCase with legacy code, and have multiple developers using the
same versions of files, working on different sections. Several people need to check
out the same version. You can use unreserved checkouts to do this
We discuss resolving unreserved checkouts later in this module.

2-6 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Checking Out a File: File Browser

Checking Out a File: File Browser

2
Select Versions>
Checkout from
the menu.

1
Select the
file to
checkout.

CLI Procedure
Usage:
checkout | co [-reserved] [-unreserved] [-c comment | -nc] pname ...
Example:
/vobs/Hardware/src% cleartool checkout -c "making sample
changes" util.c
Checked out "util.c" from version “/main/5".

© Copyright IBM Corp. 2003 2-7

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

Checking Out a File: Command Line Interface

Checking Out a File: Command Line Interface

Usage:
checkout | co [-reserved] [-unreserved] [-branch branch-pname |
-version] [-c comment | -cfile pname | -cq | -cqe | -nc] pname ...

Example:

/vobs/Hardware/src% cleartool checkout hello.c

Checkout comments for "hello.c":
Working on cleaning up the code
You MUST end the
. comment by typing
“.” and Enter
Checked out "hello.c" from version
“/main/r2_int/2".

2-8 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Versioning Directories

Versioning Directories
Š To change the directory namespace you must create
a new directory version
Š The ClearCase GUI automatically checks out a
directory and creates a new version if a change
occurs to the directory namespace (some operations
will prompt you to check out the directory)
Š Using the CLI, you must check out/check in a
directory to create a new version
Š To change only file contents but not the directory
namespace, you do not need to check out the
directory

A directory namespace is a list of the names of file and subdirectory elements that the
directory contains.
Operations that change the directory namespace require a new directory version. These
operations include:
• Adding new file or directory elements
• Renaming file or directory elements
• Removing elements
• Moving file or directory elements
• Adding or removing VOB links
If you change the directory namespace while working through the Windows GUI,
ClearCase automatically checks out/checks in the directory and creates a new version.
On UNIX, users are prompted to checkout the directory on certain commands.
Since ClearCase creates versions of directories, file elements seen in your view may not
exist in other directory versions.
If you are working through the CLI, you must check out/check in the directory to create
a new version if you change the directory namespace.
You don’t need to check out directories when creating view-private files.

© Copyright IBM Corp. 2003 2-9

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

Checking in a New Version

Checking in a New Version

Š Adds a new version to the version tree
Š The checked-in version becomes available to dynamic
view users and, upon the next update, to snapshot view
users

10

A checkin copies the modified checked-out version back to the VOB and uses it to
create a new version of the element. The checked-out copy of the version is deleted
from view storage.
Check in can be done in almost all GUI ClearCase Windows that list the checked-out
file version.
If the versions are identical and you still want to check in, you must click the check box
in the Check In dialog box; otherwise, ClearCase tells you that you cannot check in a
version identical to its predecessor.
If you attempt to check in an unreserved checkout without a merge (and there is a
successor version), you get a message indicating that the file needs to be merged prior
to check in.
CLI Procedure
Usage:
checkin | ci [-c comment | -nc] [-identical] pname ...
Example:
/vobs/Hardware/src% cleartool ci -c "minor enhancements"
util.c
Checked in "util.c" version “/main/2".

2 - 10 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Resolving Checkouts

Resolving Checkouts

11

When you check in a reserved checkout, it becomes the successor version.

Unreserved checkouts are a little more complicated. If no versions have been added
since the unreserved checkout occurred (due to check in by reserved or unreserved
checkouts), and there are no reserved checkouts existing, the user can check in without
a merge.
Otherwise, a merge must take place with the latest version on the branch to implement
the changes in the unreserved checkout.
The merge occurs FROM the latest on the branch to the unreserved checkout to ensure
the changes aren’t conflicting, and once the merge is complete, the unreserved
checkout can be checked in.
In the diagram, the numbers outside the version tree indicate the sequence of
operations.

© Copyright IBM Corp. 2003 2 - 11

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

What Is a Version Tree?

What Is a Version Tree?

A hierarchical representation of an element in which
all versions are logically organized.

12

ClearCase organizes the different versions of an element in a VOB into a version tree.
The element version tree has branches. A branch specifies a linear sequence of versions
of an element. Every element has one main branch, which represents the principal line
of development, and may have multiple subbranches, each of which represents an
independent line of development.
ClearCase supplies the /main branch as the trunk of every tree. Other branches are
user-created.
The 0 (zero) version on the main branch is empty. The 0 version on any other branch
contains the same contents as the version from which the branch originated.
The R1 on version 2 of the /main branch is a label. You can use labels to annotate
element versions. Labels can be used in ClearCase to mark project milestones, to
identify starting points, to mark important configurations.

2 - 12 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Version-extended Names

Version-extended Names
Š Each version of an element has a unique identifier
Š The extended naming symbol denotes a path into
the version tree of an element
Š @@ is the default extended naming symbol

13

Each version of an element has a unique identifier that marks the version’s position in
the version tree.
You can use extended version names to specify a particular version of an element other
than that which your view has selected. You learn more about this topic later in the
course.

© Copyright IBM Corp. 2003 2 - 13

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

Viewing Versions of an Element Graphically

Viewing Versions of an Element Graphically

Š ClearCase graphically
depicts an element version
tree in the Version Tree
Browser

14

ClearCase graphically depicts an element’s version tree in the Version Tree Browser.
CLI Procedure
Usage:
lsvtree [-g] [-short] [-all] [-nmerge] [-nco] pname ...
Example:
/vobs/Hardware/src% cleartool lsvtree hello.c
hello.c@@/main
hello.c@@/main/2 (R1)
hello.c@@/main/r2_int
hello.c@@/main/r2_int/2
hello.c@@/main/3

2 - 14 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

What Are View-private Files?

What Are View-private Files?

Š Files that are not under ClearCase source control
Š Files that reside in the view; other users in other views
do not see them
Š Examples:
ƒ Temporary files you create while developing source code
ƒ Files not yet added to source control

15

View-private files are files that are not under source control in ClearCase. Files that you
have not yet added to source control are view-private. Also, copies of files that you
check out of source control to modify are view-private while they exist in your local
workspace.

© Copyright IBM Corp. 2003 2 - 15

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

Branching Enables Parallel Development

Branching Enables Parallel Development

Š Allows different projects to use the same source at the
same time
Š Controls public/private work
Š Isolates changes
ƒ Temporary, such as new
features that have not yet
been tested
ƒ Permanent, such as fixing
a bug in a retired release

Š Prevents roadblocks — development can proceed

during an integration period
16

Parallel development allows multiple users to access the same sources without
competing for checkouts. Work can continue simultaneously on various branches and
later be integrated.
ClearCase has unlimited branching capabilities, allowing you to organize your
development effort in whatever way makes sense for your organization.
Examples of parallel development efforts, or branches, might include:
• Current development branches
• Maintenance branches
• Port branches
• Feature branches
• Experimental branches

2 - 16 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

What Is a Branch Type?

What Is a Branch Type?

Š A user-defined name that forms a unique pathname in
the version tree
Š Allows changes across multiple elements to be logically
grouped together
Š Centralizes administrative control of branch names

17

ClearCase allows each organization the flexibility to develop and implement its own
branching policies. Branching strategies are typically defined by a ClearCase
administrator or project leader and can vary widely from organization to organization.
As part of implementing a branching strategy, the administrator or project leader
defines a series of branch types. Branch types allow changes across multiple elements
to be logically grouped together.
Common branch types include:
• Task branches — for short-lived tasks that involve a small percentage of files
• Private development branches — allow multiple developers to work on a common
code base
• Integration branches — provide a buffer between private development branches
and the main branch
Branch type examples:
rel1_bugfix Fixing bugs for an old release
alex_exp Experimental work by an individual
wizard_features Development for specific features

© Copyright IBM Corp. 2003 2 - 17

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

Working on Branches

Working on Branches
Š When working on a project team, you will most likely
work on element branches other than /main
Š A view config spec specifies which versions of the
element appear in the view
Š Edit your view
config spec to
select the correct
branches and the
correct versions

18

2 - 18 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

The Default View Config Spec

The Default View Config Spec

Š A default config spec is automatically set whenever
you create a new view

Rule 1
Rule 2

Š Rule 1: Select version of element checked out to

THIS view
Š Rule 2: If no version is checked out, select the latest
version on /main
19

The config spec is the filtering mechanism for a view. It is a set of ordered rules that
selects the versions of elements visible to the view.
When you create a view, ClearCase assigns it a default config spec. The default config
spec can select versions in any active VOB for any element, as all elements have a main
branch and a 0 (zero) version on that branch. Although the 0 version is empty, it is still
considered the latest on the branch if no other versions exist.
The rules of a config spec are evaluated in order, line by line, starting at the top and
working down the list. As each rule is evaluated, ClearCase determines if a version of
the element matches the rule. If a version matches, that version is selected to appear in
the view. If no version matches, the next rule is evaluated.
The config spec rules are evaluated for each element.
The CHECKEDOUT rule means checked out to this view.

© Copyright IBM Corp. 2003 2 - 19

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

Editing a View Config Spec

Editing a View Config Spec

Š You can edit the config spec to select versions on a
branch other than /main

Rule 1
Rule 2

Š Rule 1: Select version of element checked out to

THIS view
Š Rule 2: If no version is checked out, select the latest
version on the r2_int branch
20

For parallel development, you can edit your config spec to select versions other than
/main/LATEST.
In many organizations, the project manager creates a config spec template that
developers paste into their individual config specs.
Note: When working in a mixed Windows and UNIX environment, slashes (/) must be
used in the config spec.

2 - 20 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Editing a Config Spec to Create Branches

Editing a Config Spec to Create Branches

Š A view config spec can use the –mkbranch clause to
create branches automatically upon checkout:

Š Rule 3 is interpreted as:

ƒ Select the version of the element with the R1 label
ƒ During checkout , automatically create the r2_int branch
from the version labeled R1
ƒ Check out the 0 (zero) version on the r2_int branch

21

You can edit a view config spec to create a branch automatically. Whenever you check
out an element for the first time, the rules in the config spec create the branching
structure you define using the –mkbranch clause. Creating branches with the config
spec ensures you are implementing a consistent branching structure.
In the example on the slide, the config spec creates a r2_int branch from the R1 labeled
version of an element. The version that is checked out is version 0 on the r2_int branch.
When it is checked in, it becomes version 1 on the r2_int branch.
Once the branch is created and the checkout occurs, the view never gets past Rule #2
in its selection. It selects either the CHECKEDOUT version or the LATEST on the branch
created when the -mkbranch clause was executed.

© Copyright IBM Corp. 2003 2 - 21

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

Creating a New Branch Automatically

Creating a New Branch Automatically

Change your config spec to create a branch when you
check out elements that have an R1 label.

22

Edit the config spec, inserting the -mkbranch rule in the appropriate location.
Remember, the config spec attempts to apply these rules in the order they appear.
When creating the config spec, do so with an “if/then” approach for each rule.

2 - 22 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Creating a New Branch Automatically (cont)

Creating a New Branch Automatically (cont)

Screenshot of how
new branch looks in
version tree browser

Before checkout into view After checkout; notice

with the config spec using that checkout created the
the auto mkbranch rule r2_int branch

23

The CHECKEDOUT rule is selecting this version, not the /main/r2_int/LATEST rule.
Once checked back in, the /main/r2_int/LATEST rule will select the version, and
as checkouts occur, the config spec’s first two rules will preempt evaluation of the third
rule and the -mkbranch rule will not be evaluated again for this element (unless the
branch is removed).

© Copyright IBM Corp. 2003 2 - 23

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
Š How does ClearCase protect files from being
modified inadvertently?
Š What happens when you check out a file?
Š What is the difference between a reserved and an
unreserved checkout?
Š When do you need to create a new version of a
directory?
Š What happens when you check in a file?
Š What is a version tree?
Š What is a view default config spec?
24

2 - 24 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 2 - Working with Files Under Source Control

Module Lab

Module Lab
Š In this lab, you perform the following tasks:
ƒ Edit a config spec to automatically create branches
ƒ View an element version tree
ƒ Check out/check in files
ƒ Create a view-private file

25

© Copyright IBM Corp. 2003 2 - 25

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

2 - 26 © Copyright IBM Corp. 2003

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