To reach this options page, select File > Report...
Merge provides several different ways to generate a report from a file comparison. A report is a static representation of a file comparison in a format that is suitable for archival storage on disk or placing on a website.
Creating a report
To create a report for a file comparison, select the Report... command in the File menu. A window similar to the one shown below will appear.
A list of available report types is displayed in the left-hand column of the window. Click on a report type to display a page of configuration options for that report type. Click the Help button for information about the options for the currently selected report type.
When you have configured or reviewed the options for the selected report type and chosen the location to which the report is written, click the Save... button to create the report.
Report types
HTML
HTML reports contain information about the compared files, and a side-by-side presentation of the comparison results. They can be opened in many different web browsers and can be emailed to colleagues or archived. Most options that affect the appearance of the file comparison on-screen are used when generating the report.
XML
XML reports contain information about the compared files and the data for a side-by-side presentation of the comparison results. Most options that affect the appearance of the file comparison on-screen are used when generating the report.
There are no configurable options for this report type.
UNIX diff
This type of report is like those created by the popular UNIX diff program. Edit script reports (the default diff output format), context-diff reports (diff’s -c option), and unified-diff reports (diff’s -u option) can all be created.
Please note that the output of a diff-style report from Merge will not be identical to a report generated by the real diff program. Merge and diff use different algorithms to calculate the changes between files. Although they will agree about many changes, there will be some (or many) cases where they won’t.
Example file comparison reports
Examples of the various report types are available:
Understanding XML file comparison reports
XML comparison reports are useful because they can be further processed by other applications. The information below is intended primarily for those intending to write software to process XML reports. Note that Merge creates HTML comparison reports by performing an XSLT transform on the equivalent XML report. Consequently, the two types of report are very closely related.
Root element
An XML file comparison report is contained within a top-level mg:report element.
mg:report contains two child elements, mg:metaData and mg:rowData.
Metadata
mg:metaData contains information about the report, such as which files were compared and which Merge options were in effect when the
report was performed. It is important to realize that the content of the report is affected by the prevailing Merge options
at the time when the report was generated. The elements in mg:metaData are:
| Element | Description |
|---|---|
mg:title |
The report’s title. |
mg:id |
The report’s id. This is used to number reports when creating several reports in one go (e.g. a folder comparison report with linked file comparison reports). |
mg:date |
The date when the report was created. |
mg:options |
The options and regular expressions prevailing when the report was created. These should be largely self-explanatory. The option names and values should correspond to those discussed in the AppleScript API documentation. |
mg:fileDetails |
One instance of this element exists for each file that was compared, giving the file’s name, its title (if one was provided, for example, to the compare.exe command-line utility), its path and its last modified timestamp. |
mg:changeSummaries |
Statistical information that is used for the ‘Comparison summary’ section of the HTML report (and also shown in the Statistics window for a Merge file comparison). |
mg:classes |
There is one instance of this element for each file that was compared, each containing four mg:class children, one for each type of text block (Unchanged, Removed, Inserted and Changed), giving font and colour information
for the display of text of that type.
|
Row data
mg:rowData contains the actual results of performing the file comparison. It consists of a number of mg:rowGroup elements, each of which corresponding to a block of text that has changed from one file to another.
Within each mg:rowGroup element is one or more mg:rows and/or mg:omitted element.
mg:omitted, if present, simply records the fact that one or more rows (pairs or triplets of lines) have been omitted from the comparison,
due to the ‘Show only X lines of context’ option being in effect.
Each mg:row contains up to a pair (for two-way comparisons) or triplet (for three-way comparisons) of mg:ln elements. An mg:row thus comprises a single row of the comparison, relating a single line from each file to one another. If there is no related
line, which occurs in the case of an inserted or removed blocks of text, then the mg:ln elements are only present for relevant file(s). Thus, in the entire report, there is precisely one mg:ln element for each line of text in each original file (unless, of course, lines have been omitted).
Each mg:ln element has an attribute, file, which indicates the file to which it belongs (numbered 1, 2 and 3, going from left to right). It also has a number attribute, giving the line number of the line in the file to which it belongs. Finally, it has a class attribute, which indicates whether the line as a whole is considered to have been inserted (‘I’), removed (‘R’), changed
(‘C’) or unchanged (‘U’).
mg:ln elements can contain mg:sg children. Each mg:sg represents a sequence of text characters with a particular highlight colour, and thus communicates the highlighting of changes
within lines. Each segment has a class attribute, similar to that on mg:ln, indicating whether the segment represents inserted, removed, changed or unchanged text. Merge will also break up longer
runs of text into adjacent segments, each no more than 10 or so characters. This makes it easier for the XSLT that creates HTML comparison reports to allow for a degree of line wrapping.
Since spaces and line ending characters (CR and LF) are important in file comparisons, these are explicitly encoded within segments by the mg:s, mg:cr and mg:lf elements. This ensures that information about these characters survives the XML parsing process.
The mg:rowGroup elements, and their mg:row and mg:ln children, are ordered in the XML report such that they represent lines starting from top of the compared files and working towards their ends.