Two Kinds of Checkouts

ClearCase supports two kinds of checkouts: reserved and unreserved. These are analogous to exclusive and shared locks in some software systems; however, ClearCase has a separate concept called a lock which is unrelated to checkouts. Instead, we say a file has an unreserved checkout or that a file is checked out unreserved.

By default, all files are checked out reserved.

Checking out files reserved is appropriate if you are working on a branch by yourself. You'll learn more about branches later in this course. For now, think of a branch as a copy of all the files in product. It isn't a whole copy, but it seems like it.

Checking files out unreserved is appropriate if you are working with other people on the same branch.

How do you check a file out unreserved?

cleartool checkout -unreserved filename

ClearCase allows a given file to have one reserved checkout and any number of unreserved checkouts. Only the person with the reserved checkout may check the file back in. Once a file is checked in, its reserved checkout status goes away and anyone else is free to convert their unreserved checkout into a reserved checkout.

NT Note: If you use the File Manager to check files out (ClearCase->Checkout) then you may uncheck the Reserved box to check the file(s) out unreserved.

How do you convert an unreserved checkout to a reserved checkout?

cleartool reserve filename

NT Note: You can use the File Manager to reserve files: select the files, then choose ClearCase->Reserve

How do you convert an reserved checkout to a unreserved checkout?

cleartool unreserve filename

NT Note: You can use the File Manager to unreserve files: select the files, then choose ClearCase->Unreserve

Checkout Comments

Whenever you check a file out you will be prompted for a checkout comment. You type your comment in and terminate it with a period on a line by itself. If you don't want to specify a comment at checkout time you can add the option -nc right before any file names. For example:

cleartool checkout -nc filename

If you are checking out a group of files you will be prompted for a checkout comment for each file (unless you specified -nc). If you want to specify the same checkout comment for all files being checked out in the same cleartool checkout command then you can add the option -cq right before any file names. For example:

cleartool checkout -cq filename1 filename2

In fact, all commands which create or modify objects managed by ClearCase will for a comment and they all respond to the -nc and -cq.

NT Note: A pop-up window will prompt for a comment whenever one is required for an operation invoked from the File Manager.

Checkin Comments

When you check files in you will again have the chance to enter a comment for the change. If you know that the checkout comment you specified is exactly what you want you can use the -nc option to avoid being asked about the comments. You can also use the -cq option to affect the comments for all files on the cleartool checkin command line.

Once the file is checked in its comments are called checkin comments.

The checkout comments appear in the cleartool lscheckout output. The checkin comments appear in the cleartool lshistory output.

Checkout Ettiquette

If you are working with other people on a branch and occasionally need to modify the same files, then you should always check your files out unreserved. You should do all your work with unreserved checkouts. When you are ready to check a group of files back in you should convert all their checkouts to be reserved.

You should not acquire the reserved checkout for a file until you really are ready to check it in. Once you have acquired a reserved checkout for your files, you should check them in promptly. The longer you hold onto your reserved checkouts the more you risk interfering with the work of other people on your team.

Change Groups

While some trivial changes might be entirely contained in one file, most changes to a software product involve changes to more than one file. All these changes need to be checked in as a group because they depend on each other. We call such a set of interdependent changes a change group. A change group is just a complete unit of work. It could involve more than one bugfix or logical change.

ClearCase does not provide any special commands to support change groups, so you must be careful to follow some simple rules to avoid the kinds of problems caused by failing to check in a complete change group. Checking in an incomplete change group is one ugly form of version skew.

Rules for Change Grouping

1. Always check files out unreserved.
2. Keep track of which files have changes which depend on each other, or check in all your checked-out files (in the current view) at the same time.
3. If you add or remove files or symbolic links as part of your change then the directory(s) with those changes are also part of your change group.
4. When you are ready to check in your change group, acquire the reserved checkout for all its files and directories.
5. Check in all files in your change group at the same time.

You may list multiple files and directories on the cleartool checkin command line. That's one good way to ensure that all the files are checked in as near to the same time as possible.

Handling Concurrent Changes

When two or more people are working with the same file at the same time on the same branch, then their work will have to be combined using a merge.

The scenario depicted here involves two engineers, Bob and Ann. Both of them check out a given file from version 5. Ann completes her work first and checks it back in (a). If Bob were to simply check his version in he would destroy Ann's changes! That would be doubly bad if Ann's change to the file were also a part of a change group.

So, Bob must merge his changes with those that Ann checked in, to produce a combination which includes both of their changes (b). It could be that Bob's work is supposed to replace Ann's work, in which case he would not include her changes. But in most cases Bob would take all of Ann's changes, paying special attention to any lines or areas where they both have made changes. When Bob is done with his changes he would check his file in (c). That would create version 7 of the file, which would include both of their changes.

ClearCase knows when this situation occurs and won't let Bob check his file in until he has performed the merge. ClearCase also knows when the merge has been performed. ClearCase provides a convenient tool you can use to perform this kind of merge. We will show you that merge command later in this course, after we have learned about branches.

Once the merge is done Bob is free to check his version in, but he doesn't have to. He can continue to work on his file if he wants. Someone else might come along and check out the file from version 6 and check it back in to create version 7. Then Bob would have to perform another merge to incorporate their changes.

Previous Page	Next Page
Version Control	CM Quiz
Course Map
Search Help