Clang-Format Style Options#

Clang-Format Style Options describes configurable formatting style options supported by LibFormat and ClangFormat.

When using clang-format command line utility or clang::format::reformat(...) functions from code, one can either use one of the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or create a custom style by configuring specific style options.

Configuring Style with clang-format#

clang-format supports two ways to provide custom style options: directly specify style configuration in the -style= command line option or use -style=file and put style configuration in the .clang-format or _clang-format file in the project directory.

When using -style=file, clang-format for each input file will try to find the .clang-format file located in the closest parent directory of the input file. When the standard input is used, the search is started from the current directory.

When using -style=file:<format_file_path>, clang-format for each input file will use the format file located at <format_file_path>. The path may be absolute or relative to the working directory.

The .clang-format file uses YAML format:

key1: value1
key2: value2
# A comment.
...

The configuration file can consist of several sections each having different Language: parameter denoting the programming language this section of the configuration is targeted at. See the description of the Language option below for the list of supported languages. The first section may have no language set, it will set the default style options for all languages. Configuration sections for specific language will override options set in the default section.

When clang-format formats a file, it auto-detects the language using the file name. When formatting standard input or a file that doesn’t have the extension corresponding to its language, -assume-filename= option can be used to override the file name clang-format uses to detect the language.

An example of a configuration file for multiple languages:

---
# We'll use defaults from the LLVM style, but with 4 columns indentation.
BasedOnStyle: LLVM
IndentWidth: 4
---
Language: Cpp
# Force pointers to the type for C++.
DerivePointerAlignment: false
PointerAlignment: Left
---
Language: JavaScript
# Use 100 columns for JS.
ColumnLimit: 100
---
Language: Proto
# Don't format .proto files.
DisableFormat: true
---
Language: CSharp
# Use 100 columns for C#.
ColumnLimit: 100
...

An easy way to get a valid .clang-format file containing all configuration options of a certain predefined style is:

clang-format -style=llvm -dump-config > .clang-format

When specifying configuration in the -style= option, the same configuration is applied for all input files. The format of the configuration is:

-style='{key1: value1, key2: value2, ...}'

Disabling Formatting on a Piece of Code#

Clang-format understands also special comments that switch formatting in a delimited range. The code between a comment // clang-format off or /* clang-format off */ up to a comment // clang-format on or /* clang-format on */ will not be formatted. The comments themselves will be formatted (aligned) normally. Also, a colon (:) and additional text may follow // clang-format off or // clang-format on to explain why clang-format is turned off or back on.

int formatted_code;
// clang-format off
    void    unformatted_code  ;
// clang-format on
void formatted_code_again;

In addition, the OneLineFormatOffRegex option gives you a concise way to disable formatting for all of the lines that match the regular expression.

Configuring Style in Code#

When using clang::format::reformat(...) functions, the format is specified by supplying the clang::format::FormatStyle structure.

Configurable Format Style Options#

This section lists the supported style options. Value type is specified for each option. For enumeration types possible values are specified both as a C++ enumeration member (with a prefix, e.g. LS_Auto), and as a value usable in the configuration (without a prefix: Auto).

BasedOnStyle (String)

The style used for all options not specifically set in the configuration.

This option is supported only in the clang-format configuration (both within -style='{...}' and the .clang-format file).

Possible values:

  • LLVM A style complying with the LLVM coding standards

  • Google A style complying with Google’s C++ style guide

  • Chromium A style complying with Chromium’s style guide

  • Mozilla A style complying with Mozilla’s style guide

  • WebKit A style complying with WebKit’s style guide

  • Microsoft A style complying with Microsoft’s style guide

  • GNU A style complying with the GNU coding standards

  • InheritParentConfig Not a real style, but allows to use the .clang-format file from the parent directory (or its parent if there is none). If there is no parent file found it falls back to the fallback style, and applies the changes to that. With this option you can overwrite some parts of your main style for your subdirectories. This is also possible through the command line, e.g.: --style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}

  • InheritParentConfig=<directory-path> Same as the above except that the inheritance is redirected to <directory-path>. This is only supported in configuration files.