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, sharing with colleagues, or placing on a website.
Creating a report
To create a report for a file comparison, click the Report 
toolbar button. You can also select the File▸Report… menu item, or press Shift+Cmd+E. A window similar to the one shown below will appear.
A list of available report types is displayed along the top of the window. Click on a report type to display a page of configuration options for that report type. Click the ? 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.
UNIX diff
- UNIX diff Edit Script Report Example
- UNIX diff Context Report Example
- UNIX diff Unified Report Example
This type of report is like those created by the popular UNIX diff program. It is only available for two-way comparisons, not for three-way ones. Edit-script reports (the default diff output format), context-diff reports (diff -c), and unified-diff reports (diff -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 command-line UNIX 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.
Use edit-script format
Choose this option to generate an edit script report for the file comparison. The script contains the steps that you would need to perform to convert the first file into the second file.
Use context format
This format includes several lines of context around each block of changed, inserted, or removed lines in the report.
Use unified format
This format is a more compact form of the context report.
# lines of context
This value in this field is used by Merge for context and unified-format reports.
Context and unified-format reports surround each block of changed, inserted, and removed lines in the report with a number of unchanged lines. The contents of this field determines how many unchanged lines are included.
The unchanged lines provide you with some visual context for the change so that it is easier to locate the change in the compared files. Some patch programs can use the context information in the generated reports to convert one file into the other, even when modifications have been made to the file since the report was created. Such programs typically require at least three lines of context to operate reliably.
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. The elements comprising XML comparison reports are described below.
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 Automation API Overview 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 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.