Getting Started

Preparations

Log on to a UNIX machine with ClearCase installed. Ask if you don't know which machines have ClearCase installed.
Ensure you have /ccase/bin and /usr/atria/bin in your path.
Consider displaying the value of $CLEARCASE_ROOT in your prompt, as this will indicate which view you are currently using.
Consider adding a file called .clearcase_profile with the following content:
```
# This file should be placed in $HOME/.clearcase_profile
 
checkin  -cq     # prompt for comment on every argument of checkin.
*        -nc     # no comment required for all other operations.
```
This document will assume that you have created this file. If you don't create this file, you will be prompted for comments more often and in weird locations, which might be OK with you.
Create an alias for cleartool, which you will be using constantly. ct has become customary and will be used in this document.

Getting Help

This document exists to provide an overview only. If you are interested in the precise definition of all the commands available, you can use the following commands:

  % ct help command
  command [-option] [-option arg] ... args ...

  % ct man command
  command
  =======

  description of command

  SYNOPSIS
  --------

  command [-option] [-option arg] ... args ...

  DESCRIPTION
  -----------

  ...

The wrapper scripts are those commands that begin with the ct- prefix and are documented in the Wrapper Script Reference page.

In the following, assume that your userid is coder. Note that some commands use our ct alias for cleartool, while others invoke a wrapper script that emulates an extension or a replacement for the cleartool command. The wrappers use the ct- prefix.

Create your development view, like this:
```
% ct-mkview main_coder
Creating view "main_coder".
...
...
```
You should have one view for every task you are doing concurrently. If you are only doing one thing at a time, one view would be enough. If, for some reason, you need to do something unrelated, like a quick bug fix, you should create another view, for example like this:
```
% ct-mkview main_coder_bugfix
Creating view "main_coder_bugfix".
...
...
```
The prefix main_coder is predefined and you must use it. You can add anything after that prefix and create as many views as you want.

Go to the top of the source tree, like this:
```
% cd /vob/project
```
Note that you will always use this path, no matter which view you are using. From here, you can navigate the same way as you used to when using CVS (or any other system).

To check out a file, say somedir/somefile, use this:
```
% ct co somedir/somefile
Checked out "somedir/somefile" from "/main/1".
```
You can now edit this file. Nobody else will see your changes and you will not see anybody else's changes until you feel ready

Checking in a file is accomplished like this:
```
% ct ci somedir/somefile
Comment for all listed objects:
Added feature XYZ
.
```
If you forgot which files you had checked out, you can use:
```
% ct-ci
...
...
```
This will locate all your checkouts, present you with a diff and prompt you for a checkin comment.

Note: A checkin will not make your changes visible to other people. A checkin only serves to save the current state of a file. In fact, only checked in versions of a file are backed up by the system. Any files which are checked out may be lost in the event of a disk crash.

If you want simply create a checkpoint and have the files checked out again, use this:
```
% ct-ci -co
...
...
```

To rename a file, or to move and delete files, you must check out the containing directories. This is one of the great ClearCase features that enable you to reorganize whole source trees without affecting other people until you (and they) are ready.

To rename a file somedir/thisfile to somedir/thatfile do this:
```
% ct co somedir
Checked out "somedir" from "/main/1".
% ct mv somedir/thisfile somedir/thatfile
Moved "somedir/thisfile" to "somedir/thatfile".
```
To relocate a file somefile from thisdir to thatdir, you need to check out both the original directory and the target directory, like so:
```
% ct co thisdir thatdir
Checked out "thisdir" from "/main/1".
Checked out "thatdir" from "/main/1".
% ct mv thisdir/somefile thatdir/somefile
Moved "thisdir/somefile" to "thatdir/somefile".
```

To remove directories and files, use this:
```
% ct co somedir
Checked out "somedir" from "/main/1".
% ct rm somedir/deadfile
Removed "somedir/deadfile".
```
Note that you can easily remove whole subtrees this way, but contrary to a real file system, this operation is harmless. You can easily back out by simply cancelling the checkout, like this:
```
% ct unco somedir
Checkout cancelled for "somedir".
```
Note how the removed element magically reappears. Even if you accidentally check in a directory and later want to restore removed elements, there are ways to do this - so have no fear and reorganize at will!

To create a new directory, the containing directory must be checked out, like this:

% ct co somedir
Checked out "somedir" from "/main/1".
% ct mkdir somedir/newdir
Created directory element "somedir/newdir".

The newly created directory is checked out and ready to be populated.

If you want to create a complete hierarchy, use this:

% ct-mkdir some/long/path/to/some/weird/place
Checked out "./." from version "/main/main…coder/1".
Created directory element "some".
Created branch "main…coder" from "some" version "/main/0".
Checked out "some" from version "/main/main…coder/0".
Created directory element "some/long".
Created branch "main…coder" from "some/long" version "/main/0".
Checked out "some/long" from version "/main/main…coder/0".
Created directory element "some/long/path".
Created branch "main…coder" from "some/long/path" version "/main/0".
Checked out "some/long/path" from version "/main/main…coder/0".
Created directory element "some/long/path/to".
Created branch "main…coder" from "some/long/path/to" version "/main/0".
Checked out "some/long/path/to" from version "/main/main…coder/0".
Created directory element "some/long/path/to/some".
Created branch "main…coder" from "some/long/path/to/some" version "/main/0".
Checked out "some/long/path/to/some" from version "/main/main…coder/0".
Created directory element "some/long/path/to/some/weird".
Created branch "main…coder" from "some/long/path/to/some/weird" version "/main/0".
Checked out "some/long/path/to/some/weird" from version "/main/main…coder/0".
Created directory element "some/long/path/to/some/weird/place".
Created branch "main…coder" from "some/long/path/to/some/weird/place" version "/main/0".
Checked out "some/long/path/to/some/weird/place" from version "/main/main…coder/0".

The long output is included for reference - don't worry about the "Created branch" messages for now. You will understand them better later...

To put a file under ClearCase control, first create the file using your favorite editor or copy the file into place, then use this:
```
% ct co somedir
Checked out "somedir" from "/main/1".
% ct mkelem somedir/newfile
Created file element "somedir/newfile".
```
To put a whole subtree under version control, copy the subtree into place and use this:
```
% ct-mkdir -all subtree
...
...
```
The output of this command depends on what is inside the subtree.

If you just want to create the directories, but leave the files alone, omit the -all option. This is actually the recommended procedure since it is easy to put too many files under version control, for example emacs backup files, derived objects (.o's) or other junk files.

Communicating with the Rest of the World

Once you feel you are ready to face the real world, the first thing you need to do is to get up to speed on the latest developments. The following command synchronizes your view with the latest and greatest:
```
% ct-bringover
Looking for Checkouts...
Merging Directories...
Merging Files...
...
```
If this command succeeds, then you should check if your changes still work when combined with all the other people's changes that have just been pulled into your view.

This command will point out conflicts that it couldn't resolve automatically. This usually happens when someone else modified the same portion of a file as you did. The command will then produce output that looks somewhat like this:
```
...
The file '/vob/history/history' now contains a script that you
can inspect and run. This script will actually perform the merges.
The script will disappear or be replaced if you execute any of the
following wrapper scripts in the current view:

  ct-bringover
  ct-putback
  ct-mkview
  ct-redo
  ct-undo
```
You are expected to run the commands stored in /vob/history/history. This will start the interactive merge tool for resolving the merge conflicts by hand. Note that you can get the graphuical merge tool by supplying the -gm option to the script.

The automatic conflict resolution sometimes produces erronous results. Therefore, you should always test your changes after executing the ct-bringover command to verify that everything is still in working order.

To foist your on changes onto the rest of the world, use this:
```
% ct-putback
Enter Putback Comment:
Redesigned the whole site to conform to our artist's new
outlook onto life, the universe and everything.
.
Looking for Checkouts...
Merging Directories...
Merging Files...
...
```
This command will push your changes out for everyone to see. All your changes will be logged into a special file located in /vob/history/history and a notification will be sent out to all members of the development team.

This command will fail if you haven't executed a ct-bringover recently (i.e. after the last change by someone else), and if you still have unresolved merge conflicts.

If you don't feel quite ready to push your changes, but would like to play a "what if" game, do this:
```
% ct-putback -preview
Looking for Checkouts...
Merging Directories...
Merging Files...
...
The file '/vob/history/history' now contains a script that you
can inspect and run. This script will actually perform the diffs.
The script will disappear or be replaced if you execute any of the
following wrapper scripts in the current view:

  ct-bringover
  ct-putback
  ct-mkview
  ct-redo
  ct-undo
```
The diff commands will match up paths in your view with the paths valid for everyone else, so you can track renames. You can copy the diff commands and paste them into a shell window to start the interactive diff tool and inspect the proposed changes in detail.

On occasion, it may become necessary to yank a change somebody did. People make mistakes, and this is how you undo a bad ct-putback.

First, you must locate the version of the change log file (/vob/history/history) that contains the entry for the ct-putback you want to undo. The easiest way is to use the ct lshistory command and look for the version of the history file that has the record of the putback you want to haver undone. This version is the same string which is also sent out in the subject line of the notification email, so if you saved it, you can retrieve it this way too.

Once you know which version of /vob/history/history contains the bad putback, you should create a special undo view to perform the undo. For various reasons too complicated to explain here, you cannot do an undo in a view where you have changed files that would be affected by the undo.
```
% ct-mkview main_coder_undo
Creating view "main_coder_undo".
...
% ct setview main_coder_undo
% ct-undo main/133
This is "/main/133":
Redesigned the whole site to conform to our artist's new
outlook onto life, the universe and everything.

  Updated: "/vob/somevob/somedir/somefile"
  Created: "/vob/somevob/otherdir/newfile"
  ...
Are you sure you want to undo this putback ?  [no] yes
...
```
The sequence above will create a shell script and store it in /vob/history/history. It will contain the apropriate cleartool commands to undo the putback. You can (and should) inspect the script and then run it. It will invoke the interactive merge tool to perform so-called subtractive merges, and there may be conflicts.

Note that undos can destroy data. For example, files created by the putback being undone will be removed.

Since the undo was executed inside a development view, the undo is really indistinguishable from any other change, and we revert to the usual process to synch up with other events and to push out the undo via a new ct-putback.

Getting Started

Preparations

Getting Help

Doing Real Work

Communicating with the Rest of the World