.. raw:: html

<style type="text/css">

</style>

.. role:: versionbadge

Clang-Format Style Options

:doc:`ClangFormatStyleOptions` describes configurable formatting style options

supported by :doc:`LibFormat` and :doc:`ClangFormat`.

When using :program:`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

:program:`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``, :program:`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>``, :program:`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:

.. code-block:: yaml

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

Configuration sections for specific language will override options set in the

default section.

When :program:`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 :program:`clang-format` uses to detect the

language.

An example of a configuration file for multiple languages:

.. code-block:: yaml

An easy way to get a valid ``.clang-format`` file containing all configuration

options of a certain predefined style is:

.. code-block:: console

When specifying configuration in the ``-style=`` option, the same configuration

is applied for all input files. The format of the configuration is:

.. code-block:: console

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

.. code-block:: c++

int formatted_code;

// clang-format off

void unformatted_code ;

// clang-format on

void formatted_code_again;

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``).

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

This option is supported only in the :program:`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

<https://www.gnu.org/prep/standards/standards.html>`_

* ``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}``

.. _AccessModifierOffset:

**AccessModifierOffset** (``Integer``) :versionbadge:`clang-format 3.3` :ref:`¶ <AccessModifierOffset>`

.. _AlignAfterOpenBracket:

**AlignAfterOpenBracket** (``BracketAlignmentStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignAfterOpenBracket>`

If ``true``, horizontally aligns arguments after an open bracket.

This applies to round brackets (parentheses), angle brackets and square

Possible values:

* ``BAS_Align`` (in configuration: ``Align``)

Align parameters on the open bracket, e.g.:

.. code-block:: c++

someLongFunction(argument1,

argument2);

* ``BAS_DontAlign`` (in configuration: ``DontAlign``)

Don't align, instead use ``ContinuationIndentWidth``, e.g.:

.. code-block:: c++

someLongFunction(argument1,

argument2);

* ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)

Always break after an open bracket, if the parameters don't fit

on a single line, e.g.:

.. code-block:: c++

someLongFunction(

argument1, argument2);

* ``BAS_BlockIndent`` (in configuration: ``BlockIndent``)

Always break after an open bracket, if the parameters don't fit

on a single line. Closing brackets will be placed on a new line.

E.g.:

.. code-block:: c++

someLongFunction(

argument1, argument2

)

This currently only applies to braced initializer lists (when

``Cpp11BracedListStyle`` is ``true``) and parentheses.

.. _AlignArrayOfStructures:

**AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <AlignArrayOfStructures>`

aligns the fields into columns.

.. note::

As of clang-format 15 this option only applied to arrays with equal

number of columns per row.

Possible values:

* ``AIAS_Left`` (in configuration: ``Left``)

Align array column and left justify the columns e.g.:

.. code-block:: c++

struct test demo[] =

{

{56, 23, "hello"},

{-1, 93463, "world"},

{7, 5, "!!" }

};

* ``AIAS_Right`` (in configuration: ``Right``)

Align array column and right justify the columns e.g.:

.. code-block:: c++

struct test demo[] =

{

{56, 23, "hello"},

{-1, 93463, "world"},

{ 7, 5, "!!"}

};

* ``AIAS_None`` (in configuration: ``None``)

Don't align array initializer columns.

.. _AlignConsecutiveAssignments:

**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveAssignments>`

int a = 1;

int somelongname = 2;

double c = 3;

Nested configuration flags:

Alignment options.

They can also be read as a whole for compatibility. The choices are:

* ``None``

* ``Consecutive``

* ``AcrossEmptyLines``

* ``AcrossComments``

* ``AcrossEmptyLinesAndComments``

For example, to align across empty lines and not across comments, either

of these work.

.. code-block:: c++

Enabled: true

AcrossEmptyLines: true

AcrossComments: false

* ``bool Enabled`` Whether aligning is enabled.

.. code-block:: c++

#define SHORT_NAME 42

#define LONGER_NAME 0x007f

#define EVEN_LONGER_NAME (2)

#define foo(x) (x * x)

#define bar(y, z) (y + z)

int a = 1;

int somelongname = 2;

double c = 3;

int aaaa : 1;

int b : 12;

int ccc : 8;

int aaaa = 12;

float b = 23;

std::string ccc;

true:

int a = 1;

int somelongname = 2;

double c = 3;

false:

int a = 1;

int somelongname = 2;

double c = 3;

true:

int d = 3;

/* A comment. */

false:

int d = 3;

/* A comment. */

* ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments

like ``+=`` are aligned along with ``=``.

.. code-block:: c++

true:

a &= 2;

bbb = 2;

false:

a &= 2;

bbb = 2;

* ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations

are aligned.

.. code-block:: c++

true:

unsigned int f1(void);

void f2(void);

size_t f3(void);

false:

unsigned int f1(void);

void f2(void);

size_t f3(void);

* ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are

aligned.

.. code-block:: c++

true:

unsigned i;

int &r;

int *p;

false:

unsigned i;

int &r;

int *p;

* ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment

operators are left-padded to the same length as long ones in order to

put all assignment operators to the right of the left hand side.

.. code-block:: c++

true:

a >>= 2;

bbb = 2;

a = 2;

bbb >>= 2;

false:

a >>= 2;

bbb = 2;

a = 2;

bbb >>= 2;

.. _AlignConsecutiveBitFields:

**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 11` :ref:`¶ <AlignConsecutiveBitFields>`

``Consecutive`` will align the bitfield separators of consecutive lines.

This will result in formattings like:

.. code-block:: c++

int aaaa : 1;

int b : 12;

int ccc : 8;

Nested configuration flags:

Alignment options.

They can also be read as a whole for compatibility. The choices are:

* ``None``

* ``Consecutive``

* ``AcrossEmptyLines``

* ``AcrossComments``

* ``AcrossEmptyLinesAndComments``

For example, to align across empty lines and not across comments, either

of these work.

.. code-block:: c++

Enabled: true

AcrossEmptyLines: true

AcrossComments: false

* ``bool Enabled`` Whether aligning is enabled.

.. code-block:: c++

#define SHORT_NAME 42

#define LONGER_NAME 0x007f

#define EVEN_LONGER_NAME (2)

#define foo(x) (x * x)

#define bar(y, z) (y + z)

int a = 1;

int somelongname = 2;

double c = 3;

int aaaa : 1;

int b : 12;

int ccc : 8;

int aaaa = 12;

float b = 23;

std::string ccc;

true:

int a = 1;

int somelongname = 2;

double c = 3;

false:

int a = 1;

int somelongname = 2;

double c = 3;

true:

int d = 3;

/* A comment. */

false:

int d = 3;

/* A comment. */

* ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments

like ``+=`` are aligned along with ``=``.

.. code-block:: c++

true:

a &= 2;

bbb = 2;

false:

a &= 2;

bbb = 2;

* ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations

are aligned.

.. code-block:: c++

true:

unsigned int f1(void);

void f2(void);

size_t f3(void);

false:

unsigned int f1(void);

void f2(void);

size_t f3(void);

* ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are

aligned.

.. code-block:: c++

true:

unsigned i;

int &r;

int *p;

false:

unsigned i;

int &r;

int *p;

* ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment

operators are left-padded to the same length as long ones in order to

put all assignment operators to the right of the left hand side.

.. code-block:: c++

true:

a >>= 2;

bbb = 2;

a = 2;

bbb >>= 2;

false:

a >>= 2;

bbb = 2;

a = 2;

bbb >>= 2;

.. _AlignConsecutiveDeclarations:

**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveDeclarations>`

``Consecutive`` will align the declaration names of consecutive lines.

This will result in formattings like:

int aaaa = 12;

float b = 23;

Nested configuration flags:

Alignment options.

They can also be read as a whole for compatibility. The choices are:

* ``None``

* ``Consecutive``

* ``AcrossEmptyLines``

* ``AcrossComments``

* ``AcrossEmptyLinesAndComments``

For example, to align across empty lines and not across comments, either

of these work.

.. code-block:: c++

Enabled: true

AcrossEmptyLines: true

AcrossComments: false

* ``bool Enabled`` Whether aligning is enabled.

.. code-block:: c++

#define SHORT_NAME 42

#define LONGER_NAME 0x007f

#define EVEN_LONGER_NAME (2)

#define foo(x) (x * x)

#define bar(y, z) (y + z)

int a = 1;

int somelongname = 2;

double c = 3;

int aaaa : 1;

int b : 12;

int ccc : 8;