Command line tool

Model RealTime provides two command-line tools for launching compare and merge sessions from the command-line or scripts:

1. XtoolsTypeManager: This is an executable on Windows, and a shell-script on Linux. It’s located in the plugin folder for the com.ibm.xtools.comparemerge.team plugin. For example:

   <install-dir>\plugins\com.ibm.xtools.comparemerge.team_7.60.100.v20150603_0908\utm
   

   One way to find out the exact path to XtoolsTypeManager, which for example a script can use, is to look in the file TypeManagerLaunchCommand.cfg which is located in the user's home directory under AppData/Roaming/Rational/TeamServerSharedData (on Windows) and rational/TeamServerSharedData/linux_x86 (on Linux). The path to XtoolsTypeManager is specified in this file.

2. cmcmdline.jar: This is a Java application. It’s located in the same place as the XtoolsTypeManager.

Hint: The full path to cmcmdline.jar can be seen in the preferences at General – Compare/Patch – Modeling Compare/Merge – Compare/Merge Server.

The XtoolsTypeManager is specifically designed for integration with ClearCase. It is possible to also use it as a general command-line tool for Compare/Merge, but for that we instead recommend the cmcmdline.jar Java application which is more generic, newer and more feature-rich.

In This Topic:

• Commands
• Options
• Command-Line Integrations with CM Tools

Commands

Launch the command-line tool using Java like this:

java -cp cmcmdline.jar com.ibm.xtools.comparemerge.cmcmdline.CMTool <command> <options>

You should use the same Java virtual machine that you use for running Model RealTime (normally specified in eclipse.ini using the -vm argument).

<command> is one of the following:

• compare: Perform a non-visual compare operation, i.e. a compare operation that does not launch the Model RealTime Compare user interface. The number of conflicts and changes are reported. Non-visual compare is only supported for three-way compare, so you must specify an ancestor version using the -ancestor option.

• merge: Perform a non-visual merge operation, i.e. a merge operation that does not launch the Model RealTime Merge user interface.

• xcompare: Perform a visual compare operation. A connection is established to an Model RealTime instance using the Compare/Merge Server and a compare session is launched in that Model RealTime instance.

• xmerge: Perform a visual merge operation. A connection is established to an Model RealTime instance using the Compare/Merge Server and a merge session is launched in that Model RealTime instance (provided that conflicts were found so that the merge could not be fully automatic).

Options

You must also specify <options> according to which command that is used. The following options are available (use the -help option to list all available options):

• -ancestor <file>: Specifies the ancestor version of a model file to use in a three-way compare or merge session. For a file-by-file compare you can omit specifying an ancestor version, and then the compare session will be two-way.

• -autoLaunch <argument>: If this option is used the Compare/Merge command-line tool will not look for a running instance of Model RealTime. Instead it will launch a new Model RealTime instance and use it for the compare/merge session. The argument to this option should be the launch command to use for launching the new Model RealTime instance. Note that since this command typically contains its own arguments, you need to enclose it in double quotes to make sure it's processed correctly. For example:

-autoLaunch "C:\rtist\eclipse\eclipse.exe -nosplash -data C:\rtist\egit_workspace -showlocation" 

• -autoLaunchFile <file path>: This option works the same as -autoLaunch but the launch command is read from a text file instead. For example, you can pass the path to the EclipseAutoLaunchCommand.cfg file in order to launch Model RealTime according to what is currently specified as the auto-launch configuration (see Compare/Merge Server for more information about the auto-launch configuration).

• -ccpath: Set this option if you use any ClearCase specific paths.

• -cformat [details | conflicts | simple]: Specifies how to report the result of a non-visual compare session. The default format is 'details' which means that full details about conflicts and changes are reported. For example:

  Non-Visual Compare completed with result : SUCCESS.DIFF
  conflicts : 0
  left diffs : 0
  right diffs : 1  
  

  
  Set the format to 'conflicts' to only show information about conflicts (second line in the example above), and to 'simple' to only show if the compare session was successfully performed and if any differences were found or not (first line in the example above).

• -cwd <path>: Specifies the current working directory. Relative paths are by default interpreted as relative from the current working directory of the Java application. If they should be interpreted relative to another directory, use this option.

• -exportSettings <file>: This option specifies a file to which all used option arguments are written. This also shows the default value of some options which are not explicitly set. This can be useful for throubleshooting if you get unexpected results from a compare or merge operation.

• -fileExtension <argument>: As described in Switch Compare Viewer it is the file extension of the contributor files that determines which content type to use for the compare/merge session. The following file extensions are currently recognized:

  • emx, efx
    UML model and fragment files

  • epx
    UML profiles (these are recognized but currently not supported in compare/merge)

  • bpx
    BPMN model files

  • topologyy, topologyv
    Topology model and diagram files

  If your contributor files do not have these expected file extensions you need to use this option to specify which content type to use when comparing or merging these files.

• -filter <argument>: Specifies a filter for a logical model or closure compare session. The filter can specify a list of model files, and only those files will then be part of the logical or closure compare session. The format of the argument is either a comma-separated list of file patterns, or @ where is a file that contains such a list of file patterns. Note that the patterns are matched against the file names of .emx files. It may include the wildcard symbols * and ?.

• -help: Show the list of all available options, how they can be abbreviated, and a brief description of each.

• -kind [file | logical | closure]: Specifies the kind of compare/merge session. The default is 'file' which means that the scope of the compare/merge session is a single file. This kind is sometimes called “file-by-file” since files are compared or merged individually, one by one. Set the option to 'logical' or 'closure' to perform a logical or closure compare/merge.

• -lancestor <label> -lleft <label> -lright <label>: These options can be used to set a label for the left, right or ancestor version in a visual compare or merge session. The default labels that are used depend on the input for the compare or merge session. It can for example be a filename, or the description of a Git commit. By specifying custom labels it may be easier to understand what the contributors mean in a particular compare/merge scenario.

• -left <file>: Specifies the left version of a model file to use in the compare/merge session.

• -right <file>: Specifies the right version of a model file to use in the compare/merge session.

• -log <file>: Redirects all log messages produced by the Compare/Merge command-line tool to a text file.

• -manifest <file>: Specifies a closure manifest file (.ecx) which defines the closure for a closure merge session. If you do not specify a closure manifest the closure will by default consist of all logical models that have changes when comparing the source and target versions for the merge. The syntax of a closure manifest file is
  bash [closure <closure-name>] <path to model file> <path to model file> ... where <closure-name> is the name of the closure, and <path to model file> is a workspace relative path to the .emx file of a logical model.

• -out <file>: Specifies the output file for a merge session. This file is sometimes called the merge result file since this is where the result of the merge is saved. This option is only used for file-by-file merges. For logical and closure merge a target workspace is used instead (see the option -workspace).

• -portRange <fromPort>:<toPort>: Specifies the range of ports to use when communicating with the Compare/Merge Server of running Model RealTime instances. The default value is 60001:60020. You may specify a different port range if you have set the Alternative Port Range preference to something else.

• -settings <file>: Specifies that options should be read from a text file. Each option in the file should be specified on its own line using the syntax

  <option>=<value>:The file may contain comments by using '#' as the first character of a line.

• -shutdown: If this option is set Model RealTime will be shutdown automatically when the launched compare/merge session is finished. However, this only happens if Model RealTime was also automatically launched in order to perform the compare/merge operation. If an existing Model RealTime instance is used you need to specify -shutdown=force to force that Model RealTime instance to shutdown when the compare/merge session is finished.

• -source <argument>: This option needs to be set when launching a logical model or closure compare/merge session. The argument specifies the source version of the model to be compared or merged. The interpretation of the argument depends on the CM system that is used. For Git it can be one of the following:

  • The name of a branch
  • The name of a tag (including “HEAD”)
  • A commit id

• -target <argument>: This option may be set when launching a logical model or closure merge session. The argument specifies the target version of the model to be merged. If this option is omitted the target version is taken to be the current workspace version of the Model RealTime instance where the merge session takes place. The interpretation of the argument depends on the CM system that is used. See the -source option above for valid target arguments when using Git.
  Note that for logical model or closure compare, the target version is always the current contents of the workspace in the Model RealTime instance that performs the compare operation. Hence the -target option is ignored in this case.

• -threadCount <number of threads>: The Compare/Merge command-line tool uses threads to be able to find an available instance of Model RealTime faster when launching a compare/merge session. By default 10 threads are used. If you have many instances of Model RealTime running and you experience delays when launching a compare/merge session you can increase the number of threads used.

• -verbose <argument>: This option turns on additional logging messages. It can be helpful when troubleshooting problems that seem related to how the Compare/Merge command-line tool runs. The argument should be a comma-separated list of strings that specify which modules of the command-line tool that should emit additional logging. Each string starts with '+' or '-' for enabling or disabling logging for a particular module. The following modules can be specified:

  • PROXY (disabled by default): Show details about communication with the Model RealTime Compare/Merge Server (also known as the Team Server).

  • WSCHECK (enabled by default): Show details about how the workspace pattern specified by the -workspace option is matched against workspace folders of running Model RealTime instances.

  • CONNECT (enabled by default): Show details about how the connection to the Model RealTime Team Server is established.

  • EXCEPTION (disabled by default): Show stack traces for Java exceptions that are thrown internally.

  • PATH (enabled by default): Show details about how paths are converted.

  • SYSPROP (disabled by default): Show details about how system properties are processed.

  • SHUTDOWN (disabled by default): Show details about the shutdown of an Model RealTime instance.

  • RPLYSOCK (disabled by default): Show details about the connection to an auto-launched Model RealTime instance.

  • AUTO (disabled by default): Show details about how an Model RealTime instance gets automatically launched.

  • PROGRESS (enabled by default): Show the progress of auto-launching Model RealTime in the console.

  • PROGRESSSERVER (disabled by default): Show progress messages in the console when using logical and closure merge.

  • ALL: Enables logging for all modules mentioned above.

  For example, to enable all available logging:

  -verbose=+ALL
  

  You can turn off all logging by specifying:

  -verbose=silent
  

• -waitForLaunch <seconds to wait>: This option can be used when auto-launching an Model RealTime instance to use for a compare/merge session. By default the Compare/Merge command-line tool waits for at most 3 minutes for the Model RealTime instance to start up. If it has not been able to detect that it is running within that time limit it terminates. If it takes longer to launch the Model RealTime instance in your environment, you may raise this limit. The option argument is the number of seconds to wait.

• -workspace <pattern>: By default the Compare/Merge command-line tool attempts to connect to the first Model RealTime instance it finds running. You may use this option to specify a pattern for the workspace folder of the Model RealTime instance that should be used for the compare/merge session. The pattern may contain wildcards ('*' and '?'). For example: -workspace=/home/*/myworkspace

Command-Line Integrations with CM Tools

Many CM systems can be used from the command-line. It's then convenient to have an integration with Model RealTime Compare/Merge so that compare and merge operations performed with the CM tool will launch the Model RealTime Compare/Merge tool for model files. Such integrations use the Model RealTime Compare/Merge command-line tool.

ClearCase comes with a pre-configured integration which uses the XtoolsTypeManager. That's why a command like cleartool diff on model files will launch an Model RealTime compare session and not the standard diff tool.

For other CM systems, such as Git, you need to configure the integration yourself. In general what is usually needed is to write a wrapper script which takes arguments from the CM system and uses some of them in order to invoke the cmcmdline.jar Java application with appropriate arguments. Note that the XtoolsTypeManager should not be used in this case, since it is specifically designed for the ClearCase integration. Refer to the CM system's documentation for the exact steps to set-up such an integration.