This guide explains how to use the command-line utilities provided by Model RealTime to perform compare and merge operations on model files. These tools enable launching both non-visual and visual compare/merge sessions, suitable for manual use or automation.
Model RealTime utilizes two separate command-line utilities, XtoolsTypeManager and cmcmdline.jar, that enable users to launch compare and merge sessions for model files directly from the command line or within automated scripts.
The XtoolsTypeManager command-line tool is a specialized utility designed primarily for integration with the ClearCase Configuration Management (CM) system. This tool ensures that when a ClearCase command, such as cleartool diff, is executed on a Model RealTime model file, the appropriate Model RealTime graphical compare session is launched, superseding the default text-based difference tool.
Note: While it is possible to invoke
XtoolsTypeManagerfor general command-line Compare/Merge tasks, this approach is not recommended due to its specific design focus on the ClearCase environment.
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.
The cmcmdline.jar is a Java application that serves as the strategic command-line utility for Model RealTime or Rational Software Architect Designer's Compare/Merge functionality. It is designed to be a generic, feature-rich, and modern alternative. It is the recommended tool for all general-purpose command-line Compare/Merge operations, offering greater versatility and a richer feature set.
This tool is the standard utility for integrating Model RealTime with other Configuration Management systems (CMs), such as Git, Subversion, or similar tools. Since these CM systems typically lack a pre-configured integration, the user must manually configure the process. This involves writing a wrapper script that accepts the arguments provided by the CM system and correctly uses them to invoke the cmcmdline.jar application.
The full path to cmcmdline.jar can be seen in the preferences at General – Compare/Patch – Modeling Compare/Merge – Compare/Merge Server.
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).
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 @
-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:
-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
This section presents practical examples demonstrating how to use the cmcmdline.jar tool to perform compare and merge operations, along with expected outputs.
Command:
D:\tmp\cm_api_automatic_tests>C:\java-install\jdk\jre\bin\java.exe -cp C:\eclipse\plugins\com.ibm.xtools.comparemerge.team_7.60.100.v20180706_1406\utm\cmcmdline.jar com.ibm.xtools.comparemerge.cmcmdline.CMTool compare -ancestor=models/conflicting/CPPModel.emx -left=models/conflicting/CPPModel-v1.emx -right models/conflicting/CPPModel-v2.emx
Output:
PATH : Converted path in -ancestor=models/conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel.emx
PATH : Converted path in -left=models/conflicting/CPPModel-v1.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel-v1.emx
PATH : Converted path in -right=models/conflicting/CPPModel-v2.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel-v2.emx
CONNECT : Connecting to TeamServer...
CONNECT : Connected to TeamServer at port 60002. Protocol: 9.2
Non-Visual Compare completed with result : SUCCESS.DIFF
conflicts : 2
left diffs : 2
right diffs : 1
Command:
D:\tmp\cm_api_automatic_tests>C:\java-install\jdk\jre\bin\java.exe -cp C:\eclipse\plugins\com.ibm.xtools.comparemerge.team_7.60.100.v20180706_1406\utm\cmcmdline.jar com.ibm.xtools.comparemerge.cmcmdline.CMTool compare -ancestor=models/conflicting/CPPModel.emx -left=models/conflicting/CPPModel.emx -right=models/conflicting/CPPModel.emx
Output:
PATH : Converted path in -ancestor=models/conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel.emx
PATH : Converted path in -left=models/conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel.emx
PATH : Converted path in -right=models/conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel.emx
CONNECT : Connecting to TeamServer...
CONNECT : Connected to TeamServer at port 60002. Protocol: 9.2
Non-Visual Compare completed with result : SUCCESS.MATCH
conflicts : 0
left diffs : 0
right diffs : 0
Command:
D:\tmp\cm_api_automatic_tests>C:\java-install\jdk\jre\bin\java.exe -cp C:\eclipse\plugins\com.ibm.xtools.comparemerge.team_7.60.100.v20180706_1406\utm\cmcmdline.jar com.ibm.xtools.comparemerge.cmcmdline.CMTool merge -ancestor=models/non_conflicting/CPPModel.emx -left=models/non_conflicting/CPPModel-v1.emx -right models/non_conflicting/CPPModel-v2.emx -out run/merged.emx
Output:
PATH : Converted path in -ancestor=models/non_conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\non_conflicting\CPPModel.emx
PATH : Converted path in -left=models/non_conflicting/CPPModel-v1.emx to D:\tmp\cm_api_automatic_tests\models\non_conflicting\CPPModel-v1.emx
PATH : Converted path in -right=models/non_conflicting/CPPModel-v2.emx to D:\tmp\cm_api_automatic_tests\models\non_conflicting\CPPModel-v2.emx
CONNECT : Connecting to TeamServer...
CONNECT : Connected to TeamServer at port 60002. Protocol: 9.2
Non-Visual Merge completed with result : SUCCESS
Command:
D:\tmp\cm_api_automatic_tests>C:\java-install\jdk\jre\bin\java.exe -cp C:\eclipse\plugins\com.ibm.xtools.comparemerge.team_7.60.100.v20180706_1406\utm\cmcmdline.jar com.ibm.xtools.comparemerge.cmcmdline.CMTool xmerge -ancestor=models/conflicting/CPPModel.emx -left=models/conflicting/CPPModel-v1.emx -right models/conflicting/CPPModel-v2.emx -out run/merged.emx
Output:
PATH : Converted path in -ancestor=models/conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel.emx
PATH : Converted path in -left=models/conflicting/CPPModel-v1.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel-v1.emx
PATH : Converted path in -right=models/conflicting/CPPModel-v2.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel-v2.emx
CONNECT : Connecting to TeamServer...
CONNECT : Connected to TeamServer at port 60002. Protocol: 9.2
Visual Merge completed with result : SUCCESS
Command:
D:\tmp\cm_api_automatic_tests>C:\java-install\jdk\jre\bin\java.exe -cp C:\eclipse\plugins\com.ibm.xtools.comparemerge.team_7.60.100.v20180706_1406\utm\cmcmdline.jar com.ibm.xtools.comparemerge.cmcmdline.CMTool merge -ancestor=models/conflicting/CPPModel.emx -left=models/conflicting/CPPModel-v1.emx -right models/conflicting/CPPModel-v2.emx -out run/merged.emx
Output:
PATH : Converted path in -ancestor=models/conflicting/CPPModel.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel.emx
PATH : Converted path in -left=models/conflicting/CPPModel-v1.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel-v1.emx
PATH : Converted path in -right=models/conflicting/CPPModel-v2.emx to D:\tmp\cm_api_automatic_tests\models\conflicting\CPPModel-v2.emx
CONNECT : Connecting to TeamServer...
CONNECT : Connected to TeamServer at port 60002. Protocol: 9.2
Non-visual Merge completed with result : FAILED.Unresolved Conflicts