Formatting

The controls on this options page configure the formatting of JSON files and other file types supported by Clang-Format. At the time of writing, Clang-Format supports C, C++, C#, Java, JavaScript, JSON, Objective-C, and Protobuf files.

Formatting files in a text comparison

Use the Ctrl+Alt+L keyboard shortcut to format the currently focused text comparison pane. Alternatively, use Ctrl+Alt+Shift+L to format all the panes of a text comparison.

How Merge determines which .clang-format configuration file to use

Clang-Format style options are specified using a YAML configuration file named .clang-format.

When invoking Clang-Format, Merge determines the most appropriate .clang-format configuration file to use according to the following algorithm:

  1. If the Always use this .clang-format when reformatting files option (see below) is set, use the .clang-format file specified by the Path to .clang-format setting, if that file is present. If the Always use this .clang-format when reformatting files option is set but the corresponding .clang-format file cannot be found, use the simple .clang-format file built into Merge.

  2. Otherwise, start with the file in the currently focused comparison pane. If it is a temporary file located under %USERPROFILE%\AppData\Local\Temp, skip to step 5.

  3. If a .clang-format file is present in the folder containing the current file, use that.

  4. Otherwise, search the folder hierarchy upwards, checking ancestor folders until a .clang-format file is found or until the root folder is reached. Use the first .clang-format file found, if any.

  5. If no .clang-format file has been found, repeat steps 2–4 in turn for the other file(s) in the text comparison, working rightwards and wrapping around to the leftmost file in the comparison if necessary.

  6. If no .clang-format file has been found for any of the files in the comparison, use the file specified by the Path to .clang-format setting (below), if that file is present. If it cannot be found, use the simple .clang-format file built into Merge.

Information This algorithm is intended to handle the case where there are temporary files (which likely won’t have an associated .clang-format file) being compared with a working file (which may). In that situation, which is typical for comparisons launched by certain SCM systems, files that do not have a corresponding .clang-format file will be formatted using the one for the file that does.

General Clang-Format options

Clang-Format executable locations

Merge does not bundle the Clang-Format program, so it must be present locally for Merge to be able to use it. The locations listed will be searched in descending order of preference to find the Clang-Format executable.

Path to .clang-format

Use this field to specify the location of a default .clang-format configuration file.

Always use this .clang-format when reformatting files

Check this option to use the specified default .clang-format configuration file in preference to any found in the containing folder hierarchies of the compared files.

JSON formatting

Format JSON with Clang-Format (rather than built-in, reordering formatter)

JSON files are formatted using Clang-Format when this option is checked. When unchecked, JSON files are instead formatted using the JSON formatter built into Merge.

Warning Using the built-in formatter may result in a substantial reordering of the JSON elements. This is because dictionaries (i.e. object members) are formatted in alphabetical order by their keys. This behaviour can be helpful when comparing JSON files that differ largely in their element ordering rather than in their actual content.

Warning The built-in formatter only supports files strictly adhering to the JSON specification. Non-standard features such as comments will thus prevent reformatting.

Use Clang-Format to format JSON files if you wish to avoid re-ordering or if your JSON files use non-standard features.

Automatic formatting

Reformat the following types of text file before they are compared

Check this option to apply formatting to files with filenames matching one or more of the semicolon-separated patterns in the accompanying entry field. For example, to reformat C-language files automatically, you could enable this option and provide *.c;*.h as the pattern.

Matching files are automatically formatted as they are loaded by a text comparison. It is not possible to undo this formatting within Merge. Formatting changes are preserved if you save a reformatted file.

Information This option also applies to matching text files compared during a folder comparison. Folder comparisons may therefore take longer to complete when this option is enabled.