Oso XML Merge

2.1 - Command line parameters

While Oso XML Merge can be used as a standard Windows application, it was primarily written to complement modern version control software suites. To this end, the command line parameters provide access to most of the primary features available for easy integration to your favourite version control software.

The rest of this page groups the available command line parameters into categories and describes each option within each category.

Operation Type

Specify the type of operation Oso XML Merge will perform. These two options are mutually exclusive, but you must specify one of them. Without one of these options, Oso XML Merge may not start.

Specifies this operation will compare the input files. Provide a base file to perform a three-way comparison, or omit it to compare two input files (left & right).

Initiates a merge operation. Project: Merge will merge two or three input files into a single result file.

File Parameters

Define the input and output XML files Oso XML Merge will work with. For these options there should be at least one space character between the command line option and the accompanying filename. Filenames with spaces in them should be surrounded with quotes (").

-base <filename>
Specifies the common base file for a three-way compare or merge operation. If this parameter is not specified, a two-way compare or merge operation will be initiated.

-left <filename>
Specifies the left hand side file. For three-way operations this should be related in some way to the base file.

-right <filename>
Specifies the right hand side file.

-result <filename>
Specifies the destination file for a merge operation. If this parameter is omitted, the -silent option will be ignored (if specified) and you will be prompted to choose a destination file when saving.

Filename Parameters

Allows you to control the names that are displayed at the top of the main XML view in the Oso XML Merge window. Some version control systems provide friendly names for files being converted. These names may contain revision numbers, for example. These options provide a way to display these names in Oso XML Merge. As with the filenames above, there should be a space between the option and the name. Names with spaces in them should be surrounded with quotes (").

-basetitle <title>
Specifies the title displayed for the base file.

-lefttitle <title>
Specifies the title displayed for the left side file.

-righttitle <title>
Specifies the title displayed for the right side file.

Miscellaneous Parameters

Additional parameters that can be passed to Oso XML Merge. These parameters can be used to control the behaviour of Oso XML Merge.

Controls whether the Oso XML Merge window is displayed or not. This option is only valid for merge operations, and will only be honoured if there are no conflicts and an output XML file has also been specified with the -result option.

Checks whether there are conflicts within the input files and exits immediately without allowing the user to attempt to resolve them.

This argument must be used in conjunction with -silent and -merge.

If conflicts are detected, Oso XML Merge will quit with a -1 exit code. If no conflicts exist, the exit code will be 0 (zero).

-report <filename>
Generates a report regarding the current operation. The generated report will be saved to the specified file as plain text.

-resolve <resolve_specs>
Specifies how Oso XML Merge should automatically resolve conflicts in three-way merges. You can use this parameter at any time, although its best use case is in conjunction with the -silent option to provide fully automated merging of XML files.

The resolve_specs that should follow the -resolve command is a semi-colon (;) separated list of resolve_spec rules that specify which XML components a rule applies to, which type of conflict should be matched, and finally which input file should be used to resolve the conflict:

    resolve_specs   = resolve_spec, [';' resolve_specs];
resolve_spec = xml_components, [conflict_type], ':', input_file;

The xml_components are a comma separated list of the types of XML components a rule should be applied to:

    xml_components  = xml_component, [',' xml_components];
xml_component = '*' | 'Attributes' | 'AttributeDeclarations' | 'AttributeDefinitions' | 'CData' | 'Comments' | 'Content' | 'ContentParticles' | 'DocumentTypeDeclarations' | 'Elements' | 'ElementDeclarations' | 'Entities' | 'ProcessingInstructions';

The optional conflict_type defines which type of conflict a rule applies to:

    conflict_type   = '(md)' | '(dm)' | '(mm)';

The different values have the following meanings:
  • (md) - Item was modified in the left, deleted in the right.
  • (dm) - Item was deleted in the left, modified in the right.
  • (mm) - Item was modified in both the left and the right input files.
Omitting the conflict_type completely will apply the rule to all conflict types.

Finally, the input_file specifies which of the source files should be used to resolve the conflict:

    input_file      = 'left' | 'base' | 'right';

Each entry in the resolve specification will be processed in turn from left to right, so it's possible to resolve XML components differently depending on how they were modified in the input files.

Below are some example resolve specifications:
  • Attributes(md):left;Attributes(dm):right;*:base
    Attributes modified in the left and deleted in the right, resolve to left.
    Attributes deleted in the left and modified in the right, resolve to right.
    Discard all other conflicts by reverting them to the original base file. (Note this will only affect conflicts between the three files.)

  • Comments:base
    Discard any changes made to any comments. Any remaining conflicts will be resolved manually by the user after Oso XML Merge has displayed its window.

  • *(md):left;*(dm):right;*:base
    All items that were modified in one file and deleted in the other, keep the modified version.
    Any changes to remaining conflicted items should be discarded.