ClearCase Extension Pack Reference

Concepts

Projects

A project is a pile of source code that is being developed by a group of developers reporting to one development leader. As such, a project is more a people thing than a code thing. Different projects will have different release schedules and will often work on different Delivery Branches.

A project will usually map to a set of deliverable packages, where the source code elements contributing to that package are mostly specific to the project. There should only be a small number of elements that are shared between projects, unless special arrangements have been made. Casual code sharing between projects is encouraged, but developers should use the copy/paste method unless they are willing to negociate for a shared library with the other projects that use the code.

Even though projects are logically independent structures, they do share the same source tree, and developers will be informed of updates in other branches. This is mainly to highten the situational awareness of developers, in the hope that they may find inspiration in other people's code instead of re-inventing the wheel.

Roles

People can take on different roles in various projects. The following roles have a well defined meaning within the bug tracking database and the clearcase wrappers. Roles can be defined on a per project basis, or a user may be assigned a blanket role for all projects.

Spectator

A spectator may look at things, but not modify anything. Everybody who has a role within a project must also have the spectator role.

Submitter

A submitter may submit bugs and comment on existing bugs. A submitter may not assign bugs or change the status of a bug.

Developer

A developer can be assigned bugs to fix. A developer may change the status of bugs assigned to him via the ct-putback wrapper script.

Reviewer

A reviewer can be assigned to review bug fixes. A reviewer may change the status of bugs assigned to him via the ct-putback wrapper script.

Tester

A tester may change the status of any bug.

Manager

A manager may modify any bug in any way, may assign bugs to developers and reviewers and may change the roles of any user within the projects managed.

A user may also become a superuser. Only a superuser may grant other users superuser priviledges and assign blanket roles for all projects.

Bugs

A bug is an entry in the bug tracking database. Different projects have their own list of bugs in the bug tracking database. A bug in this sense doesn't always correspond to a defect, but may represent a variety of change requests.

A bug is referred to by a two letter project id prefix followed by a sequence number. Bug references may be used in a variety of contexts, mostly by developers when they execute a ct-putback

A bug may be in any of the following states:

Open

The bug has been submitted, but nothing else happened yet.

Assigned

The bug has been assigned to a developer, to be resolved and putback into a specified Delivery Branch. If code review is used, a reviewer must also be specified.

Review

The bug is ready for code review. This state is skipped if code review is not used. The bug then immediatly goes to the Fixed state.

Fixed

A fix of the bug has been put back into the appropriate Delivery Branch.

Labeled

A fix of the bug has built and labeled and is awaiting validation by QA.

Closed

A Release Label has been attached to the versions of the elements involved in the bug fix, and hopefully the new release will contain a proper fix.

Other states may exist or may be added in the future, but the pattern above will be maintained.

Change Log File

The change log file is usually stored in /vob/history/history. This file is mainly used to attach ClearCase metadata. Every version of this file corresponds to some kind of operation executed via one of the wrapper scripts described here.

The contents of this file varies. Some commands store scripts and other output in this file, so that you can inspect and run them. The ct-bringover wrapper script, for example, stores commands to resolve merge conflicts.

The following kinds of metadata is usually attached to the change log file:

• modified hyperlinks. These hyperlinks point to other elements that have been (or may be) modified by an operation.
• fixed hyperlinks. These point to bug ids that claim to be related to the particular change logged by the change log file.
• undone hyperlinks. These point to other versions of the change log file that contain the change being undone via the ct-undo wrapper script.
• redone hyperlinks. These point to other versions of the change log file that contain the change being redone via the ct-redo wrapper script.
• inherited hyperlinks. These point to bug ids that claim to ct-redo's of a ct-putback refering to it.

Delivery Stream

The delivery branch contains versions that represent the current common stock of source code. Developers update versions via the ct-putback wrapper script, which has some built-in safeguards to protect against unresolved merge conflicts.

delivery branches can be created by running the ct-mkbranch wrapper script. This script will also create a delivery view with the same name that will select the latest versions present on the corresponding delivery branch. This view must be used to label releases using the ct-mklabel wrapper script.

The default delivery branch is main. The development lead can specify which delivery branch is to be used for resolving a bug.

The timing of the creation of new delivery branches is tricky. One should avoid creating too many delivery branches, as this will complicate the propagation of bug fixes. On the other hand, one should branch as soon as the features required by the next release are shaping up - or, to use a negative definition: one should branch as soon as developers want to put back changes not required for the next release.

Variant Stream

A variant branch is similar to a delivery branch since it also serves as a baseline for development branches. The difference is that a variant branch does not have a corresponding branch point label. As a result, a variant branch will always show the latest versions on the main branch of an element unless that element has been customized to that variant.

Currently, you can only create variants of the main branch. Projects that use variant branches tend not to use delivery branches and vice-versa, because they essentially accomplish similar goals with a different focus.

delivery branches focus on the development timeline and the exact code freeze point, whereas variant branches focus on costumizations that spread out over time. Using both types of branching within the same project will create a very complex mechanism that will be very hard to understand and follow consistantly.

For this reason, there are no plans to allow variants of delivery branches other than main, especially since there is the mechanism of release labels available to capture important freeze points within variants.

Bugfix Stream

A bugfix branch is created when a tentative release label is transformed into a final release label. A bugfix branch always looks like this:

b_<release_label>

A bugfix branch acts like a delivery branch, meaning that developers can create development branches off from it, bugs can be assigned to it etc...

Development Stream

The development branch and view is used to actually perform changes to files and directories. Every development branch is tied to a delivery branch. This is reflected in the naming convention:

<delivery branch>_<developer>[-<reviewer>][_<user defined text>]

Development branches and views are created by the developer himself, using the ct-mkview wrapper script. The developer thereby obtains a view that will select elements from the delivery branch frozen in time -- meaning that the developer will not see any changes happening after running ct-mkview. Developers may choose to update their view by using the ct-bringover wrapper script. This may create merge conflicts that the developer should resolve.

Changes in development branches can be merged back into the corresponding delivery branch using the ct-putback wrapper script. This operation will fail if there are unresolved merge conflicts or if the development view isn't seeing the latest changes on the delivery branch.

In some cases, a code review step may be required prior to executing a ct-putback. In this case, the reviewer's userid is part of the view name. When the developer executes the ct-putback wrapper script, only a preview is performed and the reviewer is notified. It is up to the reviewer to execute the proper, merging ct-putback.

Build View

A Build view is a special view, frozen in time, taken from an delivery branch, variant branch or a bugfix branch. The name of a build view is formed by prefixing Build_ in front of the name of the branch which is to be frozen in time. The ct-build wrapper script will create and maintain a build view for you.

The recommended procedure for doing scheduled builds is to use the build view, run the build, do testing and attach labels to the versions selected by the build view. Using the build view instead of the delivery view allows work to continue, since the build view is frozen in time and therefore, the ct-mklabel wrapper script doesn't need to lock the delivery branch while it is labelling.

Another advantage of labelling only after the build and test succeeded is that this avoids the creation of worthless labels and saves the time spent to label worthless versions.

Checkin Comment

Since the main operator of change is not the checkin, but the putback, checkin comments are not quite as crucial as in other CM systems.

A checkin comment should primarily be addressed to other developers. It should contain a description of the actual change that has been performed. No reference to the bug being fixed or other high level info is required, since this will be provided by the Putback Comment.

A checkin comment may be omitted if the Putback Comment adequately explains the change. It is better to have no putback comment than a boilerplate comment that is indiscriminatly applied to all files being modified.

Putback Comment

The putback comment is addressed to the reviewer and/or development lead, explaining the overall purpose of the change. Since the ct-putback wrapper scripts will provide the references to the bug tracking database, it is not necessary to specify which bugs are fixed inside the putback comment.

The putback comment may be skipped if the titles of the bugs fixed provide sufficient information.

Branch Point Label

Branch Point Labels are a byproduct of the creation of delivery branches. They all look like this:

B-<delivery branch name>

The branch point labels identify the versions on main which form the initial baseline of a delivery branches. They are only used within view config specs, and nobody should need to be concerned about them.

Tentative Release Label

Tentative Release labels are applied by the ct-mklabel wrapper script. They look like this:

R-<project id>-<version string>

Tentative release labels must be applied within a delivery view, a variant view or a bugfix view. The ct-mklabel wrapper script will create a new view that will select only labelled elements. and that will become the bugfix view once the tentative release label is made into a final release label.

Tentative release labels can be moved forward by running the ct-mklabel wrapper script with the -replace option.

Final Release Label

A tentative release label can be transformed into a final release label by running the ct-mklabel wrapper script with both the -replace and the -release option. Once this is done, you can no longer move the label. Instead, a bugfix branch is created.

If it turns out that patches need to be done that would interfere with the development in other branches, the bugfix branch may be used.

Snapshot Views

Snapshot views are copies of the content that would be served up by a normal (dynamic) view. As such, the copy must be updated explicitly whenever something may have changed. This update process can be slow. On the other hand, simple access to the files is not encumbered with any ClearCase overhead, and the copy can actually be disconnected from the network and worked upon elsewhere.

One possibility is to create the snapshot on an NT share that is mounted upon a UNIX machine with ClearCase installed.

As long as you are connected to the network, a snapshot view will behave very much like a dynamic view, and all cleartool commands will work. You cannot, of course, use version extended naming (e.g. prog.c@@/main/21), but you can use the cleartool get command to extract a specific version of a file.

When disconnected from the network, you may only do the following operations:

• Edit existing files
• Create new files and subdirectories

In particular, you may not delete, rename or relocate any files. Any of these operations require that you use the appropriate cleartool commands, which in turn require that you are on the network. If you disregard this warning, the next update will recreate the original files in their old locations.

When you reconnect, you will have to remember to use cleartool mkelem to register any newly created files or use ct-mkdir to register any newly created directory trees. The ct-ci, ct-bringover, ct-putback and ct-update commands will resynch your snapshot with the state stored by clearcase, transforming any out of band modifications to files into checkouts.

For further information on the possibilities and limitations of snapshot views, please refer to the cleartool update man page.

To create a snapshot view, use the -snapshot or -snapdir options to the ct-mkview command.

By default, all visible elements will be loaded into the snapshot. This can be changed either by specifying the logical pathnames to be loaded (i.e. the paths stripped of the vob tag prefix) via the ct-mkview -load option or by editing the load rules in the view's config spec.

Wrapper Scripts

ct-activity

   ct-activity [-debug yes|no] [-nxn] [-htmldir htdocs]
               [-user [userid|-all]|-dir [dirname|-all]|-branch [branch|-all]]

Generate a list of currently pending changes. An element is considered to have a pending change if it either has a checkout or if it has a dangeling development branch (i.e. the latest version on that development branch does not have a merge arrow into the integration branch).

htdocs/
  |_index.html
  |_by_branch.html
  |_by_dir.html

ct-bringover

   ct-bringover [-debug] [-parent | -from -parent|branchname]
                [-g|-graphical] [-c comment|-nc] [-log pname]
                [-n|-preview] [-diff diff-command] [-f|-force]
                [pname ...]

By default, runs a cleartool findmerge from the delivery branch into the current view, which must be a development view. The source can be changed by using the -from option.

The cleartool findmerge is done twice, once for directories and once for files. This ensures that all name changes will be propagated prior to looking for file elements.

Prior to running the merge, all checked out elements will be checked in using the same procedure used by the ct-ci wrapper script.

Merge conflicts are tentatively resolved automatically. File elements where this is not possible are not merged, and a list of merge commands intended for manual execution is generated instead and stored in the change log file.

Note that merges only occur for files that the developer has modified in his development view. Most changes to the delivery branch will not be explicitly listed, unless the -preview option is used.

It is possible to restrict the scope of a ct-bringover by specifying paths to subdirectories. This should be used with care, as it may result in an incorrect representation of relocations whenever the source or the target of the relocation is outside of the specified subdirectory. For this reason, restricted ct-bringovers are only permitted when used in conjunction with the -from or -parent options unless the -force option is used.

ct-build

   ct-build [-debug] [-try n] [-delay time] [-smudge time]
            [-snapshot | -snapdir directory]
            [-branch branch [-time freezepoint]|-label label] [command]

Create and maintain a build view. This script is intended to be run non-interactively, for example from a crontab script. If used with -branch, it will lock the delivery branch to which the build view is tied to, update the config spec to select a freeze point for the current date and time or the one specified via the -time option. If used with -label, a build view based on the specified label will be created and no locks will be used. In both cases it will run a specified command in the updated build view.

ct-bug

   ct-bug [-fixed -here|history-file-version] [-title title]
          [-problem problem] [-debug] [-project projectid]

Files a new bug into the bug tracking system. Bugs may be filed retroactively and attached to any particular putback. The current development view is used to extract as much info as possible, including the assigned branch, developer and reviewer if applicable.

ct-cdpath

   ct-cdpath [-debug] [-cutoff nr-of-files] [top-level-dir ...]

Construct a string that may be assigned to the CDPATH environment variable, making changing directories less painful.

The output will list all directories that contain one of the specified top level directories, and that contain subdirectories which themselves contain more than three files. This number may be modified by using the -cutoff option.

ct-ci

   ct-ci [-c comment|-nc] [-co|-checkout|-checkpoint]
         [-debug] [pname ...]

Locate checked out elements, display diffs and prompt for checkin comment unless -nc or -c comment is specified.

ct-co

   ct-co [-c comment|-nc] [-debug] [pname ...]

Check out specified elements, following symbolic links if necessary, as opposed to the ClearCase command which simply barfs at them.

ct-init

ct-init [-debug]

Check whether all required vobs and views exist, whether the storage locations exist and whether all metadata is defined in the adminvob.

The output is a sequence of cleartool commands that will create the missing metadata items. This output may either be piped into cleartool or examined and edited.

ct-crosslink-vobs

ct-crosslink-vobs [-depth n] [-ignore pattern ...] [-leaves] pname ...

Traverse all vobs looking for missing symbolic links. This implements the procedure described in Symlink Trees.

The output is a sequence of cleartool commands that will create the symbolic links. This output may either be piped into cleartool or examined and edited.

ct-history

   ct-history [-debug yes|no] [-age age_spec] [-nxn] [-htmldir htdocs]
              [-user [userid|-all]|-dir [dirname|-all]|-branch [branch|-all]]

Generate putback history reports, either as text or as HTML. When run with no arguments, it will display all putbacks done today, ordered by integration branch.

htdocs/
  |_index.html
  |_by_branch.html
  |_by_branch_branch.html
  |_...
  |_by_dir.html
  |_by_dir_dirname.html
  |_...
  |_by_user.html
  |_by_user_userid.html
  |_...

ct-lock

   ct-lock [-debug yes|no] [-nuser userid[,userid ...]]
           [-replace] [-c comment] branchtype ...

Lock specified branch in all vobs. This script should not be used by itself. It is called from other scripts that require locking.

ct-mkbranch

   ct-mkbranch [-debug] [-projects projectid[,projectid...]]
   [-time timestamp] [-variant parent] [-noview] brtype ...

Create a new Delivery Branch or a new Variant Branch. You must be in the main view to run this command.

Release and Variant Branches can be assigned to specific projects (and they usually are). This ensures that only project specific bugs may be assigned to a particular branch.

Running this script inserts the appropriate entries into the bug tracking database, creates a Branch Point Label in main (if required) and a corresponding ReleaseVariant View.

ct-mkdir

   ct-mkdir [-all] [-ci] [-debug] pname ...

Creates and populates directory hierarchies.

ct-mklabel

   ct-mklabel [-debug] [-fixed bugid[,bugid...]] [-preview|-show]
              [-time timestamp] [-replace] [-silent]
              [-release] [-mkview] [-auto prefix | lbtype ...]

Attaches a release label to versions selected by a delivery view.

The release label must conform to the following naming convention:

R-<project id>-<version string>

The version string may contain a package name. Package names are assumed to contain only letters, no numbers or special characters. If a package name is specified, it is matched with all packages defined in the given project, and if the match is unique, the label is assumed to define a build for that package.

Unless specified by the -fixed option, the user will be prompted for a list of bugs that are to be registered as fixed in the release being labeled. If the label is package specific, all bugs that are assigned to that package will be selectable as a group, and bugs assigned to different packages are not shown. Bugs assigned to no package are assumed to apply to multiple packages, and you may or may not choose to add them.

Note that you can only apply exactly one label to a bug.

Running this script also creates a view with the same name as the label, selecting only versions that have this label attached.

When -release is used, a final release label is created, together with a bugfix branch.

ct-mkview

   ct-mkview [-debug] [-time dd-mmm-yyyy.hh:mm:ss]
             [-snapshot | -snapdir directory]
             [-label|-branch] [-load path [-load path] ...] viewtag ...

Create a development view. If so desired, the view can be "back dated", selecting only versions from the delivery branch that are older than a specified cutoff point.

Specified view tags must conform to the following naming convention:

<delivery branch>_<developer>[-<reviewer>][_<user defined text>]

ct-mkvob

   ct-mkvob [-debug] vobtag ...

Creates specified vobs. This command may only be run as the cmadmin user.

This wrapper implements the storage layout conventions described in the architecture document. It will also install all trigger types, create the AdminVOB hyperlink, register the vob for snapshot backups etc...

ct-mvview

   ct-mvview [-debug] old-viewtag new-viewtag

Renames an existing development view. The associated development branch is also renamed in all vobs. The result should be completly transparent, although some static log files might still refer to the old branch name.

Currently, you cannot rename delivery views or bugfix views. You also cannot rename someone else's development view.

ct-putback

   ct-putback [-c comment|-nc] [-debug] [-fixed bugid[,bugid...]]
              [-pc putback-comment | -pnc | -pcf putback-comment-file]
              [-g|-graphical] [-log pname] [-n|-preview]
              [-accept|-reject] [-keep|-obs[olete]|-rmbranch]
              [-part[ial]] [-diff diff-command] [pname ...]

Pushes changes made in a development branch out to the corresponding delivery branch and updates the change log and specifiend entries in the bug tracking database.

Running this script executes, among other things, a cleartool findmerge -merge -abort. The expectancy is that all merges should be copy merges. Two safeguards are in place to avoid breaking this process:

• The change history file selected by the development view must be the latest version on the delivery branch. Since ct-putback updates the change history every time it is run, these versions are different whenever another developer user did a ct-putback after the last ct-bringover in the current development view.
• Merge conflicts are not allowed to occur. If they do occur, then the cleartool findmerge is unrolled and an error message issued to the developer.

If the cleartool findmerge succeeds, all checkin comments of all versions on the development branch since the previous ct-putback are concatenated and used as the checkin comment for the new version on the delivery branch.

The combination of bugs fixed, a user-provided putback comment and all checkin comments of all elements merged into the delivery branch is appended to the change logs, and clearcase hyperlinks are created to link that version of the change log with the versions of all merged elements. This way, a complete picture of the operation can be obtained by running a cleartool describe on the change log.

If the review process is used, a putback initiated by the developer will simply execute a preview, just as if the -n|-preview option had been used. In addition, the reviewer is notified. The reviewer may then either execute the real putback or reject the putback.

Using the review process also changes the way putback comments are entered. A template is loaded into the user's favorite editor specified via the EDITOR environment variable, and this template should be used to compose an extensive description of the possible impacts of the fixes.

A putback may be restricted to a specified set of subdirectories.

A putback which delivers no changes will cause no notifications, except when a ct-bringover -parent was run. In that case, the delivery view will be modified to select newer versions of the parent delivery branch, and an appropriate notification will be sent out.

ct-redo

   ct-redo [-debug] [-c comment|-nc] [-g|-graphical]
           [-abort] [-bin|-binaries] [-f|-force]
           history_version

Generate a shell script that will execute a selective merge. This is a feature of cleartool merge, allowing the insertion of individual changes, even if other changes have happened later.

ct-redo is intended to be run in a development view, so that merge conflicts can be resolved and tested safely, using the normal development process. The fact that ct-redo was run is recorded when executing the generated shell script, and a subsequent ct-putback will generate apropriate metadata to the new change log entry.

The generated shell script is stored in the change log file. Running the shell script may invoke the graphical merge tool, and manual intervention may be necessary, especially if a very old putback is to be re-applied.

Note that it is possible for some elements referenced by the putback being re-applied might be invisible in the current view. The script will have commands to create links to these versions, effectivly resurrecting those lost elements. This may or may not be desirable.

The script will leave all modified elements checked out, so that corrections may be applied or unwanted modifications undone.

ct-rmview

   ct-rmview [-ci] [-debug] [-rmbranch|-recreate] viewtag ...

Removes a development view created by ct-mkview. As opposed to the cleartool rmview command, this wrapper script uses the view tag as argument, thereby hiding all the implementation details from the user.

Any elements that are checked out in that view are automatically unchecked out unless the -ci option is used.

The associated development branch is only removed if the -rmbranch option is specified.

If -recreate is used, then the view is recreated. Use this option to clean out old views with many stranded view private files.

ct-rmvob

   ct-rmvob [-debug] vobtag ...

Removes specified vobs. As opposed to the cleartool rmvob command, this wrapper script uses the vob tag as argument, thereby hiding all the implementation details from the user.

This command may only be run the cmadmin user.

Warning: This will destroy data. Your only hope from recovering is restoring from a backup.

ct-undo

   ct-undo [-debug] [-c comment|-nc] [-g|-graphical]
   [-abort] [-bin|-binaries] [-f|-force] history_version

Generate a shell script that will execute a subtractive merge. This is a feature of cleartool merge, allowing the removal of unwanted changes, even if other changes have happened later.

ct-undo is intended to be run in a development view, so that merge conflicts can be resolved and tested safely, using the normal development process. The fact that ct-undo was run is recorded when executing the generated shell script, and a subsequent ct-putback will generate apropriate metadata to the new change log entry.

The generated shell script is stored in the change log file. Running the shell script may invoke the graphical merge tool, and manual intervention may be necessary, especially if a very old putback is to be undone.

Note that elements that have been created by the putback being undone will disappear again, and no merge commands for those elements will be included in the generated shell script.

ct-unlock

   ct-unlock [-debug yes|no] brtype ...

Unlock specified branches. This script is mainly used internally by other scripts. Users can use this script to recover from a crashed ct-bringover or ct-putback.

ct-version

   ct-version

Print out version, packaging date and installation date of the ClearCase extensions described in this document.

None

ct-what

NAME
             ccwhat - embed or query for data in executable object files


SYNOPSIS
     The following sequence demonstrates how to embed random data
     into any linked object file, using /bin/cat as an example.
     First we put the date into the binary with a type of 'D',
     then add the current config spec with a type of 'S'.  Next
     we read all the data back out, then just the date as an
     example of how to use data types. Last, we read back the
     config spec and pipe it through /tmp/cat to demonstrate that
     the binary still works, and then strip it to show how to
     remove all ccwhat metadata.

       % cp /bin/cat /tmp && chmod a+w /tmp/cat
       % date | ccwhat -a -tD /tmp/cat
       % cleartool catcs | ccwhat -a -tS /tmp/cat
       % ccwhat /tmp/cat
       % ccwhat -tD /tmp/cat
       % ccwhat -tS -q /tmp/cat | /tmp/cat
       % strip /tmp/cat
       % ccwhat /tmp/cat

     Note that the different types are not necessary; you can
     just dump data in with ccwhat -a and read it back with
     ccwhat.  Run "ccwhat -h" for full usage plus more examples.

CLEARCASE NOTES
     There's nothing clearcase-specific about ccwhat except the
     name and the original motivation. It can be used in any
     environment as long as the object-module format allows it
     (see below).

     Some CC users will want to encode CR data into deliverable
     binaries.  This can be done but it destroys the CR, so you
     should only do it as you copy the file out.  I.e. first copy
     the DO out to regular file space, THEN dump the output of
     catcr into the *copy*.

PLATFORM CONSIDERATIONS
     This script is known to work on Solaris 2.5.1 and Windows
     NT4.0, and will almost certainly work on any Unix system
     which has the appropriate perl version. The code contains a
     "require 5.001" only because that's the oldest Perl it was
     tested against.

     A separate question regards whether appending data to an
     object module is safe. Again, this is known to be ok for ELF
     object modules and whatever the Win32 format is called. In
     terms of specific Unix platforms, it's known to not break
     binaries on Solaris 1.* (aka SunOS4) and 2.*, plus AIX.  It
     will probably work for most any others.

ADVANCED USAGE
     Recommended values for -t flag (clearcase only): R for
     config record, S for config spec, E for environment
     variables, etc.

     This script can be used to append what-data to ascii files
     as well, as long as they have a prefix comment convention,
     e.g. -c'#'.

     The -p flag is an advanced topic: it allows you to enter a
     code which will not be seen by the 'what' command.  A
     special program is needed to find this data.

AUTHOR
     Copyright (c) 1997 David Boyce (dsb@world.std.com). All
     rights reserved.  This perl program is free software; you
     may redistribute it and/or modify it under the same terms as
     Perl itself.

Build Scripts

b

b [-lib] [cook arguments...]

Invoke cook from the top of the logical source tree, passing inHowto.list into the current directory.

cook-filter-errors

cook-filter-errors [logfile ...]

None save the

cook-fix-manifests

cook-fix-manifests

Scans through all Whatto.cookfiles, inspects them and deletes those that contain invalid data.

None.

compress-html

compress-html [input-file [output-file]]

Undoes the action of the HTML normalizer trigger, removing as many white spaces as possible from an HTML file.

None.

ct-absolute-top

top=`ct-absolute-top`

Prints the absoluter pathname to the logical top of the source tree.

ct-relative-top

cd `ct-relative-top`

Prints the relative pathname../../...

ct-where

where=`ct-where`

Prints the relative pathname from the logical top of the source tree to the current directory.

None. Note that there is no newline character at the end of the output.

Triggers

Environment Variables

CCASE_ALLOW_HARDLINKS

Disables the link trigger. Allowing users to create hardlinks is dubious policy, because it will make recursive finds list the same element multiple times. Users should use symbolic links instead.

CCASE_NO_CHK_DUP_ELEMS

Disable the evil twin trigger. This would permit users to create a new element with a name already registered in a different version of the directory containing the new element. This may create directory merge conflicts.

CCASE_NO_CLEARPROMT

Set this if you do not want to be prompted in case of warnings and errors. This is useful when running unattended scripts that do clearcase operations.

CCASE_NO_FORMAT_HTML

Disables the HTML normalizer. Use it if your project required hand editing of HTML files and you dislike the format of the HTML normalizer. Note that all members of a project must use this environment variable to be effective. If you use an HTML authoring tool, please leave the trigger enabled, since authoring tools tend to create very long lines that make merges very messy.

CCASE_NO_PROTECT

Disables the element protection trigger. Disabling that trigger will likely cause access permission problems and is therefore not recommended.

CCASE_NO_RCS_KEYWORDS

Disables the RCS Keywords trigger. Keywords in keyed_text_files will no longer be updated.

CCASE_NO_RM_EMPTY_BRANCH

Disables the empty branches trigger. Disabling this trigger should never be necessary and will cause merge inefficiencies.

CCASE_NO_TEST_COMPETITORS

Disables the parallel development warning issued on checkout. If it contains a comma separated list of branch names, then the warning will be disabled only for work done on those branches.

CLEARCASE_TRACE_TRIGGERS

Setting this variable to -2 will overload the normal clearcase funtion with an environment dump of the trigger. If a trigger is run, a file called triggername.txt will be created in the current directory containing a dump of the environment as seen by the trigger. Use it for debugging triggers.

Empty Branches

Empty branches are created whenever a user cancels a checkout of an element that was checked out out for the first time. If empty branches are allowed to remain, every subsequent ct-bringover operation will generate a copy merge at that point, slowing down the operation. This trigger removes the empty branch and avoids this problem.

Evil Twin

This trigger will examine all versions of a directory in which a new element is to be created, ensuring that the name of the element exists in no other version. This prevents users from accidentally creating a copy of an element that someone else already created or that was removed. It also reduces the risk of directory merge conflicts.

HTML Normalizer

Many HTML authoring tools and HTML generators create lines that are too long for clearcase to handle. Long lines also make merging HTML files difficult. This trigger will reformat HTML files into a functionally equivalent representation that doesn't contain any long lines.

Even if users are hand editing HTML files, give this a try. The formatting has the additional benefit of exposing the effect of white spaces on the formatting and helping users avoid common pitfalls in HTML coding.

Note that this trigger will insert more white spaces into an HTML files than needed, making it longer. It is therefore recommended to use the compress-html wrapper script at packaging time to undo the effect of this trigger.

Link

Hard links should not be used, since it makes recursive finds return the same element twice. Symbolic links should be used instead. This trigger prevents the creation of hard links unless a version extended pathname is used to specify the element to be linked. This exception allows users to resurrect deleted elements and is the only valid usage for hard links.

Element Protection

RCS Keywords

An RCS Keyword is inband versioning information insered into files. As such, they are not really recommended and unnecessary withing clearcase, since clearcase already provides a variety of methods to extract version information on every element.

On the other hand, many developers have grown fond of these, and they do provide some information when the files are used outside of clearcase.