# Apache Ant ClearCase Tasks

by:
Curtis White (cwhite at aracnet dot com),
Sean P. Kane (spkane at genomatica dot com),
Rob Anderson (Anderson.Rob at vectorscm dot com), and
Sean Egan (sean at cm-logic dot com)

Version 1.6—02/25/2003

# ClearCase Support

## Table of Contents

- Introduction
- CCCheckin
- CCCheckout
- CCUnCheckout
- CCUpdate
- CCMklbtype
- CCMklabel
- CCRmtype
- CCLock
- CCUnlock
- CCMkbl
- CCMkattr
- CCMkdir
- CCMkelem

## Introduction

Apache Ant provides several optional tasks for working with ClearCase. These tasks correspond to various ClearCase commands using the `cleartool` program. The current tasks available for Ant correspond to only a few of the significant ClearCase commands.

More tasks can be easily added by deriving from the ClearCase class and then adding functionality that is specific to that ClearCase command.

Important: these tasks all require `cleartool` on the command line. If a task fails with an `IOException`, especially `error=2` on Windows, this is your problem.

## CCCheckin

### Description

Task to perform a `cleartool checkin` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
nowarn | Suppress warning messages | No
preservetime | Preserve the modification time | No
keepcopy | Keeps a copy of the file with a `.keep` extension | No
identical | Allows the file to be checked in even if it is identical to the original | No
failonerr | Throw an exception if the command fails | No; default is true

### Examples

Perform a ClearCase `checkin` on the file `c:/views/viewdir/afile`. Comment text from the file `acomment.txt` is added to ClearCase as a comment. All warning messages are suppressed. The file is checked in even if it is identical to the original.

    <cccheckin viewpath="c:/views/viewdir/afile"
               commentfile="acomment.txt"
               nowarn="true"
               identical="true"/>

## CCCheckout

### Description

Task to perform a `cleartool checkout` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
reserved | Specifies whether to check out the file as reserved or not | Yes
out | Creates a writable file under a different filename | No
nodata | Checks out the file but does not create an editable file containing its data | No
branch | Specify a branch to check out the file to | No
version | Allows checkout of a version other than `/main/LATEST` (or whatever is selected by a config spec) | No
nowarn | Suppress warning messages | No
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
notco | Fail if it's already checked out to the current view. Set to false to ignore it. Since Ant 1.6.1 | No; default is true
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `checkout` on the file `c:/views/viewdir/afile`. It is checked out as reserved on branch called `abranch`. All warning messages are suppressed. A "`Some comment text`" is added to ClearCase as a comment.

    <cccheckout viewpath="c:/views/viewdir/afile"
                reserved="true"
                branch="abranch"
                nowarn="true"
                comment="Some comment text"/>

## CCUnCheckout

### Description

Task to perform a `cleartool uncheckout` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
keepcopy | Specifies whether to keep a copy of the file with a `.keep` extension or not | No
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `uncheckout` on the file `c:/views/viewdir/afile`. A copy of the file named `c:/views/viewdir/afile.keep` is kept.

    <ccuncheckout viewpath="c:/views/viewdir/afile" keepcopy="true"/>

## CCUpdate

### Description

Task to perform an `cleartool update` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase snapshot view file or directory that the command will operate on | No
graphical | Displays a graphical dialog during the update | No
log | Specifies a log file for ClearCase to write to | No
overwrite | Specifies whether to overwrite hijacked files or not | No
rename | Specifies that hijacked files should be renamed with a `.keep` extension | No
currenttime | Specifies that modification time should be written as the current time. Mutually exclusive with preservetime. | No
preservetime | Specifies that modification time should preserved from the VOB time. Mutually exclusive with currenttime. | No
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `update` on the snapshot view directory `c:/views/viewdir`. A graphical dialog will be displayed. The output will be logged to `log.log` and it will overwrite any hijacked files. The modified time will be set to the current time.

    <ccupdate viewpath="c:/views/viewdir"
              graphical="false"
              log="log.log"
              overwrite="true"
              currenttime="true"
              rename="false"/>

## CCMklbtype

### Description

Task to perform a `cleartool mklbtype` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
typename | Name of the label type to create | Yes
vob | Name of the VOB | No
replace | Replace an existing label definition of the same type | No
global | Creates a label type that is global to the VOB or to VOBs that use this VOB. | No; only one of the two may be used, default ordinary=true
ordinary | Creates a label type that can be used only in the current VOB.
pbranch | Allows the label type to be used once per branch in a given element's version tree | No
shared | Sets the way mastership is checked by ClearCase. See ClearCase documentation for details | No
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `mklbtype` to create a label type named `VERSION_1`. It is created as ordinary so it is available only to the current VOB. The text Development version 1 is added as a comment.

    <ccmklbtype typename="VERSION_1"
                ordinary="true"
                comment="Development version 1"/>

## CCMklabel

### Description

Task to perform a `cleartool mklabel` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
typename | Name of the label type | Yes
viewpath | Path to the ClearCase view file or directory that the command will operate on | No
replace | Replace a label of the same type on the same branch | No
recurse | Process each subdirectory under viewpath | No
version | Identify a specific version to attach the label to | No
vob | Name of the VOB | No
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `mklabel` on the file `c:/views/viewdir/afile` under the `main` branch for version 2 (`\main\2`). Text "`Some comment text`" is added as a comment. It will recurse all subdirectories.

    <ccmklabel viewpath="c:/views/viewdir/afile"
               comment="Some comment text"
               recurse="true"
               version="\main\2"
               typename="VERSION_1"/>

## CCRmtype

### Description

Task to perform a `cleartool rmtype` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
typekind | The kind of type to create. Valid types are:
Kind | Description
--- | ---
attype | attribute type
brtype | branch type
eltype | element type
hltype | hyperlink type
lbtype | label type
trtype | trigger type
| Yes
typename | The name of the type to remove | Yes
ignore | Used with trigger types only. Forces removal of trigger type even if a pre-operation trigger would prevent its removal | No
rmall | Removes all instances of a type and the type object itself | No
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `rmtype` to remove a label type (lbtype) named `VERSION_1`. Comment text from the file `acomment.txt` is added as a comment. All instances of the type are removed, including the type object itself.

    <ccrmtype typekind="lbtype"
              typename="VERSION_1"
              commentfile="acomment.txt"
              rmall="true"/>

## CCLock

### Description

Task to perform a `cleartool lock` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
replace | Specifies replacing an existing lock | No
nusers | Specifies user(s) who can still modify the object | No
obsolete | Specifies that the object should be marked obsolete | No
comment | Specifies how to populate comments fields | No
pname | Specifies the object pathname to be locked. | No
objselect | Obsolete. Use objsel instead. | No
objsel | Specifies the object(s) to be locked. Since Ant 1.6.1 | No
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `lock` on the object `stream:Application_Integration@\MyProject_PVOB`.

    <cclock objsel="stream:Application_Integration@\MyProject_PVOB"/>

## CCUnlock

### Description

Task to perform a `cleartool unlock` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
comment | Specifies how to populate comments fields | No
pname | Specifies the object pathname to be unlocked. | No
objselect | Obsolete. Use objsel instead. | No
objsel | Specifies the object(s) to be unlocked. Since Ant 1.6.1 | No
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `unlock` on the object `stream:Application_Integration@\MyProject_PVOB`.

    <ccunlock objsel="stream:Application_Integration@\MyProject_PVOB"/>

## CCMkbl

### Description

Task to perform a `cleartool mkbl` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
baselinerootname | Specify the name to be associated with the baseline. | Yes
nowarn | Suppress warning messages | No
identical | Allows the baseline to be created even if it is identical to the previous baseline. | No
full | Creates a full baseline. | No
nlabel | Allows the baseline to be created without a label. | No
failonerr | Throw an exception if the command fails. Since Ant 1.6.1 | No; default is true

### Examples

Perform a ClearCase `mkbl` on the Integration view at `v:\ApplicationCC` even if it is identical to a previous baseline. The new baseline with be incremental and named `Application_Baseline_AUTO`.

    <ccmkbl baselinerootname="Application_Baseline_AUTO"
            identical="yes"
            full="no"
            viewpath="v:\ApplicationCC"/>

## CCMkattr

Since Ant 1.6.1

### Description

Task to perform a `cleartool mkattr` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | Yes
replace | Replace the value of the attribute if it already exists | No
recurse | Process each subdirectory under viewpath | No
version | Identify a specific version to attach the attribute to | No
typename | Name of the attribute type | Yes
typevalue | Value to attach to the attribute type | Yes
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
failonerr | Throw an exception if the command fails. | No; default is true

### Examples

Perform a ClearCase `mkattr` on the file `c:/views/viewdir/afile` and attach the attribute `BugFix` with a value of `34445` to it.

    <ccmkattr viewpath="c:/views/viewdir/afile"
              typename="BugFix"
              typevalue="34445"/>

## CCMkdir

Since Ant 1.6.1

### Description

Task to perform a `cleartool mkdir` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view directory that the command will operate on | Yes
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
nocheckout | Do not checkout after element creation | No
failonerr | Throw an exception if the command fails. | No; default is true

### Examples

Perform a ClearCase `mkdir` on the dir `c:/views/viewdir/adir` and do not automatically check it out.

    <ccmkdir viewpath="c:/views/viewdir/adir"
             nocheckout="true"
             comment="Some comment text"/>

## CCMkelem

Since Ant 1.6.1

### Description

Task to perform a `cleartool mkelem` command to ClearCase.

### Parameters

Attribute | Values | Required
--- | --- | ---
viewpath | Path to the ClearCase view file or directory that the command will operate on | Yes
comment | Specify a comment | No; only one of the two may be used
commentfile | Specify a file containing a comment
nowarn | Suppress warning messages | No
nocheckout | Do not checkout after element creation | No
checkin | Checkin element after creation | No
preservetime | Preserve the modification time (for checkin) | No
master | Assign mastership of the main branch to the current site | No
eltype | Element type to use during element creation | No
failonerr | Throw an exception if the command fails. | No; default is true

### Examples

Perform ClearCase `mkelem` on the file `c:/views/viewdir/afile` with element type `text_file`, check in the file after creation.

    <ccmkelem viewpath="c:/views/viewdir/afile"
              eltype="text_file"
              checkin="true"
              comment="Some comment text"/>