SCM Implementation: ClearCase

General Info


License: Commercial


For all URLs below, use a colon (:) as the separator. In case of a colon being used within one of the parameters (e.g. a Windows path), then use a pipe (|) as the separator.


view_name: Name of the view that is created on a 'checkout' of the code. This parameter is optional.

config_spec: Either

  • a user-supplied config spec file, or
  • one load rule that is used by the ClearCase SCM provider to automatically generate a config spec when creating a view.

Note: Since 1.1.1, you could also use:




ClearCase UCM

If you are using ClearCase UCM, the URL format is the following


vob_name: Identifier of the ClearCase VOB

stream_name: Name of the project's Stream

User-supplied config spec

If you specify the location of an user-supplied config spec file in the SCM URL, this config spec is used each time a view is created. SCM URL samples:


To make sure all the correct elements are loaded in the view, the config spec must have "load" rules specified. You can also include other config specs into your own config spec, as in the following example:

include \\myserver\clearcase\configspecs\my_dynamic_configspec.txt
load /myvob/modules/my_module

Notice that checking out from a tag (which is used by the maven-release-plugin) is currently not supported for user-supplied config specs. Another point to remember is that ClearCase does not check out projects directly into the checkout directory, but instead a sub-directory of the checkout directory (e.g. /checkoutdir/myvob/modules/my_module instead of just /checkoutdir). This is unexpected by the scm:bootstrap command, Continuum, the Maven-Release-Plugin and other users of the ClearCase SCM provider. Adjust the build working directory after the checkout (in Continuum, for example, by adjusting the POM file location within the Build definition).

Auto-generated config spec

For many users of a base ClearCase SCM installation, auto-generated config specs are more convenient than user-supplied config specs. Instead of being forced to provide a config spec file at an external location, the SCM URL contains all information that is needed to check out the code. Specify one load rule for the project you want to check out within the SCM URL, as in the following examples:

scm:clearcase:load /MY_VOB/my/project/dir
scm:clearcase:my_module_view:load /MY_VOB/my/project/dir

This information is used by the ClearCase SCM provider to automatically generate the following config spec:

element * CHECKEDOUT
element * /main/LATEST
load <load_directory>

When working with auto-generated config specs, checking out from version tags (= ClearCase label types) is supported as well. (Notice that checking out from a branch tag (= ClearCase branch type) is currently not supported.) In case a tag has been specified, the following config spec is created:

element * CHECKEDOUT
element * <tag>
element -directory * /main/LATEST
load <load_directory>

Notice that ClearCase does not check out projects directly into the checkout directory, but instead a sub-directory of the checkout directory (e.g. /checkoutdir/myvob/modules/my_module instead of just /checkoutdir). When using auto-generated config specs, the correct location of the project directory is provided to other modules that use the ClearCase SCM provider, such as the scm:bootstrap command. As a consequence, the build can automatically be run from the correct working directory.

Creating and removing views

Each time a 'checkout' of code is performed (e.g. when adding a project to Continuum), the ClearCase SCM provider creates a new snapshot view using the cleartool mkview command. As the view name, the view_name parameter is used if it has been specified. Many users prefer to leave the view_name parameter out, as the ClearCase SCM provider automatically chooses a view name according to the following pattern: username-hostname-maven-checkoutdir, e.g. johndoe-mymachine-maven-myproject.

Notice that the ClearCase SCM provider does not remove views once they have been created. When you don't need the view any longer, remember to explicitly remove it using ClearCase HomeBase or cleartool, e.g. using one of the following commands:

cleartool rmview /views/myproject
cleartool rmview -tag johndoe-mymachine-maven-myproject

In case a view name already exists when checking out, ClearCase reports an error like the following:

cleartool: Error: A registry entry already exists for "johndoe-mymachine-maven-myproject".

ClearCase settings file

You can configure the behaviour of the ClearCase SCM provider by providing a clearcase-settings.xml file, either at ${user.home}/.scm/clearcase-settings.xml or at ${maven.home}/conf/clearcase-settings.xml. Notice: If the file is present at both locations, the settings from the .scm subdirectory of the user's home directory is used; the settings are not merged.

-vws parameter on mkview command

By default, when creating a view, the -vws parameter of the mkview command is used to specify the location of the view store. In many environments, however, the -vws parameter can be omitted, and ClearCase uses appropriate defaults. To turn off the usage of the -vws parameter, configure it in the clearcase-settings.xml file:


Viewstore location

This setting is only relevant if and when useVWSParameter has been left or set to the default value of true. By default the viewstore location \\${hostname}\viewstore is used. To define another viewstore location, use the following setting:


ClearCase Type

By default, the ClearCase SCM provider uses commands appropriate for the full ClearCase version. If you are using ClearCase LT or ClearCase UCM instead, you must specify this fact in the clearcase-settings.xml file.


As ClearCase LT uses a predefined and unchangeable folder as the viewstore directory, you should also specify the viewstore root location in the clearcase-settings.xml file:


ClearCase dynamic views

The ClearCase SCM provider uses snapshot views. In case you are forced to use ClearCase dynamic views, one option is to use the SCM local file system provider instead. Within the SCM URL, you could specify the view name that the Continous Integration Server is using, for example:


Notice that this option provides only very limited integration of Maven into the configuration management system. As no SCM metadata can be accessed, it is not possible to use SCM plugin features like creating tags (applying labels), creating changelogs, and so on.