3 <style type="text/css">
4 .versionbadge { background-color: #1c913d; height: 20px; display: inline-block; width: 120px; text-align: center; border-radius: 5px; color: #FFFFFF; font-family="Verdana,Geneva,DejaVu Sans,sans-serif" }
9 ==========================
10 Clang-Format Style Options
11 ==========================
13 :doc:`ClangFormatStyleOptions` describes configurable formatting style options
14 supported by :doc:`LibFormat` and :doc:`ClangFormat`.
16 When using :program:`clang-format` command line utility or
17 ``clang::format::reformat(...)`` functions from code, one can either use one of
18 the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or
19 create a custom style by configuring specific style options.
22 Configuring Style with clang-format
23 ===================================
25 :program:`clang-format` supports two ways to provide custom style options:
26 directly specify style configuration in the ``-style=`` command line option or
27 use ``-style=file`` and put style configuration in the ``.clang-format`` or
28 ``_clang-format`` file in the project directory.
30 When using ``-style=file``, :program:`clang-format` for each input file will
31 try to find the ``.clang-format`` file located in the closest parent directory
32 of the input file. When the standard input is used, the search is started from
33 the current directory.
35 The ``.clang-format`` file uses YAML format:
44 The configuration file can consist of several sections each having different
45 ``Language:`` parameter denoting the programming language this section of the
46 configuration is targeted at. See the description of the **Language** option
47 below for the list of supported languages. The first section may have no
48 language set, it will set the default style options for all languages.
49 Configuration sections for specific language will override options set in the
52 When :program:`clang-format` formats a file, it auto-detects the language using
53 the file name. When formatting standard input or a file that doesn't have the
54 extension corresponding to its language, ``-assume-filename=`` option can be
55 used to override the file name :program:`clang-format` uses to detect the
58 An example of a configuration file for multiple languages:
63 # We'll use defaults from the LLVM style, but with 4 columns indentation.
68 # Force pointers to the type for C++.
69 DerivePointerAlignment: false
70 PointerAlignment: Left
73 # Use 100 columns for JS.
77 # Don't format .proto files.
81 # Use 100 columns for C#.
85 An easy way to get a valid ``.clang-format`` file containing all configuration
86 options of a certain predefined style is:
88 .. code-block:: console
90 clang-format -style=llvm -dump-config > .clang-format
92 When specifying configuration in the ``-style=`` option, the same configuration
93 is applied for all input files. The format of the configuration is:
95 .. code-block:: console
97 -style='{key1: value1, key2: value2, ...}'
100 Disabling Formatting on a Piece of Code
101 =======================================
103 Clang-format understands also special comments that switch formatting in a
104 delimited range. The code between a comment ``// clang-format off`` or
105 ``/* clang-format off */`` up to a comment ``// clang-format on`` or
106 ``/* clang-format on */`` will not be formatted. The comments themselves
107 will be formatted (aligned) normally.
113 void unformatted_code ;
115 void formatted_code_again;
118 Configuring Style in Code
119 =========================
121 When using ``clang::format::reformat(...)`` functions, the format is specified
122 by supplying the `clang::format::FormatStyle
123 <https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
127 Configurable Format Style Options
128 =================================
130 This section lists the supported style options. Value type is specified for
131 each option. For enumeration types possible values are specified both as a C++
132 enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
133 the configuration (without a prefix: ``Auto``).
136 **BasedOnStyle** (``String``)
137 The style used for all options not specifically set in the configuration.
139 This option is supported only in the :program:`clang-format` configuration
140 (both within ``-style='{...}'`` and the ``.clang-format`` file).
145 A style complying with the `LLVM coding standards
146 <https://llvm.org/docs/CodingStandards.html>`_
148 A style complying with `Google's C++ style guide
149 <https://google.github.io/styleguide/cppguide.html>`_
151 A style complying with `Chromium's style guide
152 <https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md>`_
154 A style complying with `Mozilla's style guide
155 <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
157 A style complying with `WebKit's style guide
158 <https://www.webkit.org/coding/coding-style.html>`_
160 A style complying with `Microsoft's style guide
161 <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017>`_
163 A style complying with the `GNU coding standards
164 <https://www.gnu.org/prep/standards/standards.html>`_
165 * ``InheritParentConfig``
166 Not a real style, but allows to use the ``.clang-format`` file from the
167 parent directory (or its parent if there is none). If there is no parent
168 file found it falls back to the ``fallback`` style, and applies the changes
171 With this option you can overwrite some parts of your main style for your
172 subdirectories. This is also possible through the command line, e.g.:
173 ``--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}``
175 .. START_FORMAT_STYLE_OPTIONS
177 **AccessModifierOffset** (``Integer``) :versionbadge:`clang-format 3.3`
178 The extra indent or outdent of access modifiers, e.g. ``public:``.
180 **AlignAfterOpenBracket** (``BracketAlignmentStyle``) :versionbadge:`clang-format 3.8`
181 If ``true``, horizontally aligns arguments after an open bracket.
183 This applies to round brackets (parentheses), angle brackets and square
188 * ``BAS_Align`` (in configuration: ``Align``)
189 Align parameters on the open bracket, e.g.:
193 someLongFunction(argument1,
196 * ``BAS_DontAlign`` (in configuration: ``DontAlign``)
197 Don't align, instead use ``ContinuationIndentWidth``, e.g.:
201 someLongFunction(argument1,
204 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
205 Always break after an open bracket, if the parameters don't fit
206 on a single line, e.g.:
211 argument1, argument2);
215 **AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13`
216 if not ``None``, when using initialization for an array of structs
217 aligns the fields into columns.
221 * ``AIAS_Left`` (in configuration: ``Left``)
222 Align array column and left justify the columns e.g.:
229 {-1, 93463, "world"},
233 * ``AIAS_Right`` (in configuration: ``Right``)
234 Align array column and right justify the columns e.g.:
241 {-1, 93463, "world"},
245 * ``AIAS_None`` (in configuration: ``None``)
246 Don't align array initializer columns.
250 **AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8`
251 Style of aligning consecutive assignments.
253 ``Consecutive`` will result in formattings like:
258 int somelongname = 2;
263 * ``ACS_None`` (in configuration: ``None``)
264 Do not align assignments on consecutive lines.
266 * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
267 Align assignments on consecutive lines. This will result in
273 int somelongname = 2;
280 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
281 Same as ACS_Consecutive, but also spans over empty lines, e.g.
286 int somelongname = 2;
293 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
294 Same as ACS_Consecutive, but also spans over lines only containing
300 int somelongname = 2;
307 * ``ACS_AcrossEmptyLinesAndComments``
308 (in configuration: ``AcrossEmptyLinesAndComments``)
310 Same as ACS_Consecutive, but also spans over lines only containing
311 comments and empty lines, e.g.
316 int somelongname = 2;
323 **AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 11`
324 Style of aligning consecutive bit field.
326 ``Consecutive`` will align the bitfield separators of consecutive lines.
327 This will result in formattings like:
337 * ``ACS_None`` (in configuration: ``None``)
338 Do not align bit fields on consecutive lines.
340 * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
341 Align bit fields on consecutive lines. This will result in
354 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
355 Same as ACS_Consecutive, but also spans over empty lines, e.g.
367 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
368 Same as ACS_Consecutive, but also spans over lines only containing
381 * ``ACS_AcrossEmptyLinesAndComments``
382 (in configuration: ``AcrossEmptyLinesAndComments``)
384 Same as ACS_Consecutive, but also spans over lines only containing
385 comments and empty lines, e.g.
397 **AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8`
398 Style of aligning consecutive declarations.
400 ``Consecutive`` will align the declaration names of consecutive lines.
401 This will result in formattings like:
411 * ``ACS_None`` (in configuration: ``None``)
412 Do not align bit declarations on consecutive lines.
414 * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
415 Align declarations on consecutive lines. This will result in
428 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
429 Same as ACS_Consecutive, but also spans over empty lines, e.g.
441 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
442 Same as ACS_Consecutive, but also spans over lines only containing
455 * ``ACS_AcrossEmptyLinesAndComments``
456 (in configuration: ``AcrossEmptyLinesAndComments``)
458 Same as ACS_Consecutive, but also spans over lines only containing
459 comments and empty lines, e.g.
471 **AlignConsecutiveMacros** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 9`
472 Style of aligning consecutive macro definitions.
474 ``Consecutive`` will result in formattings like:
478 #define SHORT_NAME 42
479 #define LONGER_NAME 0x007f
480 #define EVEN_LONGER_NAME (2)
481 #define foo(x) (x * x)
482 #define bar(y, z) (y + z)
486 * ``ACS_None`` (in configuration: ``None``)
487 Do not align macro definitions on consecutive lines.
489 * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
490 Align macro definitions on consecutive lines. This will result in
495 #define SHORT_NAME 42
496 #define LONGER_NAME 0x007f
497 #define EVEN_LONGER_NAME (2)
499 #define foo(x) (x * x)
501 #define bar(y, z) (y + z)
503 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
504 Same as ACS_Consecutive, but also spans over empty lines, e.g.
508 #define SHORT_NAME 42
509 #define LONGER_NAME 0x007f
510 #define EVEN_LONGER_NAME (2)
512 #define foo(x) (x * x)
514 #define bar(y, z) (y + z)
516 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
517 Same as ACS_Consecutive, but also spans over lines only containing
522 #define SHORT_NAME 42
523 #define LONGER_NAME 0x007f
524 #define EVEN_LONGER_NAME (2)
526 #define foo(x) (x * x)
528 #define bar(y, z) (y + z)
530 * ``ACS_AcrossEmptyLinesAndComments``
531 (in configuration: ``AcrossEmptyLinesAndComments``)
533 Same as ACS_Consecutive, but also spans over lines only containing
534 comments and empty lines, e.g.
538 #define SHORT_NAME 42
539 #define LONGER_NAME 0x007f
540 #define EVEN_LONGER_NAME (2)
542 #define foo(x) (x * x)
544 #define bar(y, z) (y + z)
546 **AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``) :versionbadge:`clang-format 5`
547 Options for aligning backslashes in escaped newlines.
551 * ``ENAS_DontAlign`` (in configuration: ``DontAlign``)
552 Don't align escaped newlines.
561 * ``ENAS_Left`` (in configuration: ``Left``)
562 Align escaped newlines as far left as possible.
574 * ``ENAS_Right`` (in configuration: ``Right``)
575 Align escaped newlines in the right-most column.
586 **AlignOperands** (``OperandAlignmentStyle``) :versionbadge:`clang-format 12`
587 If ``true``, horizontally align operands of binary and ternary
592 * ``OAS_DontAlign`` (in configuration: ``DontAlign``)
593 Do not align operands of binary and ternary expressions.
594 The wrapped lines are indented ``ContinuationIndentWidth`` spaces from
595 the start of the line.
597 * ``OAS_Align`` (in configuration: ``Align``)
598 Horizontally align operands of binary and ternary expressions.
600 Specifically, this aligns operands of a single expression that needs
601 to be split over multiple lines, e.g.:
605 int aaa = bbbbbbbbbbbbbbb +
608 When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
609 aligned with the operand on the first line.
613 int aaa = bbbbbbbbbbbbbbb
616 * ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``)
617 Horizontally align operands of binary and ternary expressions.
619 This is similar to ``AO_Align``, except when
620 ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so
621 that the wrapped operand is aligned with the operand on the first line.
625 int aaa = bbbbbbbbbbbbbbb
630 **AlignTrailingComments** (``Boolean``) :versionbadge:`clang-format 3.7`
631 If ``true``, aligns trailing comments.
636 int a; // My comment a vs. int a; // My comment a
637 int b = 2; // comment b int b = 2; // comment about b
639 **AllowAllArgumentsOnNextLine** (``Boolean``) :versionbadge:`clang-format 9`
640 If a function call or braced initializer list doesn't fit on a
641 line, allow putting all arguments onto the next line, even if
642 ``BinPackArguments`` is ``false``.
656 **AllowAllConstructorInitializersOnNextLine** (``Boolean``) :versionbadge:`clang-format 9`
657 This option is **deprecated**. See ``NextLine`` of
658 ``PackConstructorInitializers``.
660 **AllowAllParametersOfDeclarationOnNextLine** (``Boolean``) :versionbadge:`clang-format 3.3`
661 If the function declaration doesn't fit on a line,
662 allow putting all parameters of a function declaration onto
663 the next line even if ``BinPackParameters`` is ``false``.
669 int a, int b, int c, int d, int e);
672 void myFunction(int a,
678 **AllowShortBlocksOnASingleLine** (``ShortBlockStyle``) :versionbadge:`clang-format 11`
679 Dependent on the value, ``while (true) { continue; }`` can be put on a
684 * ``SBS_Never`` (in configuration: ``Never``)
685 Never merge blocks into a single line.
695 * ``SBS_Empty`` (in configuration: ``Empty``)
696 Only merge empty blocks.
705 * ``SBS_Always`` (in configuration: ``Always``)
706 Always merge short blocks into a single line.
711 while (true) { continue; }
715 **AllowShortCaseLabelsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 3.6`
716 If ``true``, short case labels will be contracted to a single line.
721 switch (a) { vs. switch (a) {
722 case 1: x = 1; break; case 1:
723 case 2: return; x = 1;
729 **AllowShortEnumsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 12`
730 Allow short enums on a single line.
735 enum { A, B } myEnum;
743 **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) :versionbadge:`clang-format 3.5`
744 Dependent on the value, ``int f() { return 0; }`` can be put on a
749 * ``SFS_None`` (in configuration: ``None``)
750 Never merge functions into a single line.
752 * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``)
753 Only merge functions defined inside a class. Same as "inline",
754 except it does not implies "empty": i.e. top level empty functions
755 are not merged either.
768 * ``SFS_Empty`` (in configuration: ``Empty``)
769 Only merge empty functions.
778 * ``SFS_Inline`` (in configuration: ``Inline``)
779 Only merge functions defined inside a class. Implies "empty".
791 * ``SFS_All`` (in configuration: ``All``)
792 Merge all functions fitting on a single line.
803 **AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) :versionbadge:`clang-format 9`
804 Dependent on the value, ``if (a) return;`` can be put on a single line.
808 * ``SIS_Never`` (in configuration: ``Never``)
809 Never put short ifs on the same line.
827 * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``)
828 Put short ifs on the same line only if there is no else statement.
845 * ``SIS_OnlyFirstIf`` (in configuration: ``OnlyFirstIf``)
846 Put short ifs, but not else ifs nor else statements, on the same line.
863 * ``SIS_AllIfsAndElse`` (in configuration: ``AllIfsAndElse``)
864 Always put short ifs, else ifs and else statements on the same
881 **AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) :versionbadge:`clang-format 9`
882 Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
887 * ``SLS_None`` (in configuration: ``None``)
888 Never merge lambdas into a single line.
890 * ``SLS_Empty`` (in configuration: ``Empty``)
891 Only merge empty lambdas.
895 auto lambda = [](int a) {}
896 auto lambda2 = [](int a) {
900 * ``SLS_Inline`` (in configuration: ``Inline``)
901 Merge lambda into a single line if argument of a function.
905 auto lambda = [](int a) {
908 sort(a.begin(), a.end(), ()[] { return x < y; })
910 * ``SLS_All`` (in configuration: ``All``)
911 Merge all lambdas fitting on a single line.
915 auto lambda = [](int a) {}
916 auto lambda2 = [](int a) { return a; };
920 **AllowShortLoopsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 3.7`
921 If ``true``, ``while (true) continue;`` can be put on a single
924 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) :versionbadge:`clang-format 3.7`
925 The function definition return type breaking style to use. This
926 option is **deprecated** and is retained for backwards compatibility.
930 * ``DRTBS_None`` (in configuration: ``None``)
931 Break after return type automatically.
932 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
934 * ``DRTBS_All`` (in configuration: ``All``)
935 Always break after the return type.
937 * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
938 Always break after the return types of top-level functions.
942 **AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``) :versionbadge:`clang-format 3.8`
943 The function declaration return type breaking style to use.
947 * ``RTBS_None`` (in configuration: ``None``)
948 Break after return type automatically.
949 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
954 int f() { return 0; };
957 int f() { return 1; }
959 * ``RTBS_All`` (in configuration: ``All``)
960 Always break after the return type.
977 * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
978 Always break after the return types of top-level functions.
983 int f() { return 0; };
992 * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
993 Always break after the return type of function definitions.
1009 * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
1010 Always break after the return type of top-level definitions.
1015 int f() { return 0; };
1025 **AlwaysBreakBeforeMultilineStrings** (``Boolean``) :versionbadge:`clang-format 3.4`
1026 If ``true``, always break before multiline string literals.
1028 This flag is mean to make cases where there are multiple multiline strings
1029 in a file look more consistent. Thus, it will only take effect if wrapping
1030 the string at that point leads to it being indented
1031 ``ContinuationIndentWidth`` spaces from the start of the line.
1036 aaaa = vs. aaaa = "bbbb"
1040 **AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) :versionbadge:`clang-format 7`
1041 The template declaration breaking style to use.
1045 * ``BTDS_No`` (in configuration: ``No``)
1046 Do not force break before declaration.
1047 ``PenaltyBreakTemplateDeclaration`` is taken into account.
1051 template <typename T> T foo() {
1053 template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
1054 int bbbbbbbbbbbbbbbbbbbbb) {
1057 * ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
1058 Force break after template declaration only when the following
1059 declaration spans multiple lines.
1063 template <typename T> T foo() {
1065 template <typename T>
1066 T foo(int aaaaaaaaaaaaaaaaaaaaa,
1067 int bbbbbbbbbbbbbbbbbbbbb) {
1070 * ``BTDS_Yes`` (in configuration: ``Yes``)
1071 Always break after template declaration.
1075 template <typename T>
1078 template <typename T>
1079 T foo(int aaaaaaaaaaaaaaaaaaaaa,
1080 int bbbbbbbbbbbbbbbbbbbbb) {
1085 **AttributeMacros** (``List of Strings``) :versionbadge:`clang-format 12`
1086 A vector of strings that should be interpreted as attributes/qualifiers
1087 instead of identifiers. This can be useful for language extensions or
1088 static analyzer annotations.
1094 x = (char *__capability)&y;
1095 int function(void) __ununsed;
1096 void only_writes_to_buffer(char *__output buffer);
1098 In the .clang-format configuration file, this can be configured like:
1100 .. code-block:: yaml
1102 AttributeMacros: ['__capability', '__output', '__ununsed']
1104 **BinPackArguments** (``Boolean``) :versionbadge:`clang-format 3.7`
1105 If ``false``, a function call's arguments will either be all on the
1106 same line or will have one line each.
1112 f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
1113 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
1118 f(aaaaaaaaaaaaaaaaaaaa,
1119 aaaaaaaaaaaaaaaaaaaa,
1120 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
1123 **BinPackParameters** (``Boolean``) :versionbadge:`clang-format 3.7`
1124 If ``false``, a function declaration's or function definition's
1125 parameters will either all be on the same line or will have one line each.
1130 void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
1131 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
1134 void f(int aaaaaaaaaaaaaaaaaaaa,
1135 int aaaaaaaaaaaaaaaaaaaa,
1136 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
1138 **BitFieldColonSpacing** (``BitFieldColonSpacingStyle``) :versionbadge:`clang-format 12`
1139 The BitFieldColonSpacingStyle to use for bitfields.
1143 * ``BFCS_Both`` (in configuration: ``Both``)
1144 Add one space on each side of the ``:``
1150 * ``BFCS_None`` (in configuration: ``None``)
1151 Add no space around the ``:`` (except when needed for
1152 ``AlignConsecutiveBitFields``).
1158 * ``BFCS_Before`` (in configuration: ``Before``)
1159 Add space before the ``:`` only
1165 * ``BFCS_After`` (in configuration: ``After``)
1166 Add space after the ``:`` only (space may be added before if
1167 needed for ``AlignConsecutiveBitFields``).
1175 **BraceWrapping** (``BraceWrappingFlags``) :versionbadge:`clang-format 3.8`
1176 Control of individual brace wrapping cases.
1178 If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
1179 each individual brace case should be handled. Otherwise, this is ignored.
1181 .. code-block:: yaml
1184 BreakBeforeBraces: Custom
1188 SplitEmptyFunction: false
1190 Nested configuration flags:
1193 * ``bool AfterCaseLabel`` Wrap case labels.
1198 switch (foo) { vs. switch (foo) {
1210 * ``bool AfterClass`` Wrap class definitions.
1221 * ``BraceWrappingAfterControlStatementStyle AfterControlStatement``
1222 Wrap control statements (``if``/``for``/``while``/``switch``/..).
1226 * ``BWACS_Never`` (in configuration: ``Never``)
1227 Never wrap braces after a control statement.
1234 for (int i = 0; i < 10; ++i) {
1237 * ``BWACS_MultiLine`` (in configuration: ``MultiLine``)
1238 Only wrap braces after a multi-line control statement.
1247 while (foo || bar) {
1250 * ``BWACS_Always`` (in configuration: ``Always``)
1251 Always wrap braces after a control statement.
1259 for (int i = 0; i < 10; ++i)
1263 * ``bool AfterEnum`` Wrap enum definitions.
1276 * ``bool AfterFunction`` Wrap function definitions.
1293 * ``bool AfterNamespace`` Wrap namespace definitions.
1310 * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
1311 @autoreleasepool and @synchronized blocks are wrapped
1312 according to `AfterControlStatement` flag.
1314 * ``bool AfterStruct`` Wrap struct definitions.
1329 * ``bool AfterUnion`` Wrap union definitions.
1344 * ``bool AfterExternBlock`` Wrap extern blocks.
1359 * ``bool BeforeCatch`` Wrap before ``catch``.
1376 * ``bool BeforeElse`` Wrap before ``else``.
1391 * ``bool BeforeLambdaBody`` Wrap lambda block.
1409 * ``bool BeforeWhile`` Wrap before ``while``.
1424 * ``bool IndentBraces`` Indent the wrapped braces themselves.
1426 * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line.
1427 This option is used only if the opening brace of the function has
1428 already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
1429 set, and the function could/should not be put on a single line (as per
1430 `AllowShortFunctionsOnASingleLine` and constructor formatting options).
1438 * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body
1439 can be put on a single line. This option is used only if the opening
1440 brace of the record has already been wrapped, i.e. the `AfterClass`
1441 (for classes) brace wrapping mode is set.
1445 class Foo vs. class Foo
1449 * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
1450 This option is used only if the opening brace of the namespace has
1451 already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
1456 namespace Foo vs. namespace Foo
1461 **BreakAfterJavaFieldAnnotations** (``Boolean``) :versionbadge:`clang-format 3.8`
1462 Break after each annotation on a field in Java files.
1464 .. code-block:: java
1467 @Partial vs. @Partial @Mock DataLoad loader;
1471 **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) :versionbadge:`clang-format 3.6`
1472 The way to wrap binary operators.
1476 * ``BOS_None`` (in configuration: ``None``)
1477 Break after operators.
1481 LooooooooooongType loooooooooooooooooooooongVariable =
1482 someLooooooooooooooooongFunction();
1484 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
1485 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
1486 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
1487 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
1488 ccccccccccccccccccccccccccccccccccccccccc;
1490 * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
1491 Break before operators that aren't assignments.
1495 LooooooooooongType loooooooooooooooooooooongVariable =
1496 someLooooooooooooooooongFunction();
1498 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1499 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1500 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1501 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1502 > ccccccccccccccccccccccccccccccccccccccccc;
1504 * ``BOS_All`` (in configuration: ``All``)
1505 Break before operators.
1509 LooooooooooongType loooooooooooooooooooooongVariable
1510 = someLooooooooooooooooongFunction();
1512 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1513 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1514 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1515 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1516 > ccccccccccccccccccccccccccccccccccccccccc;
1520 **BreakBeforeBraces** (``BraceBreakingStyle``) :versionbadge:`clang-format 3.7`
1521 The brace breaking style to use.
1525 * ``BS_Attach`` (in configuration: ``Attach``)
1526 Always attach braces to surrounding context.
1569 void bar() { foo(true); }
1572 * ``BS_Linux`` (in configuration: ``Linux``)
1573 Like ``Attach``, but break before braces on function, namespace and
1621 void bar() { foo(true); }
1624 * ``BS_Mozilla`` (in configuration: ``Mozilla``)
1625 Like ``Attach``, but break before braces on enum, function, and record
1673 void bar() { foo(true); }
1676 * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
1677 Like ``Attach``, but break before function definitions, ``catch``, and
1725 void bar() { foo(true); }
1728 * ``BS_Allman`` (in configuration: ``Allman``)
1729 Always break before braces.
1787 void bar() { foo(true); }
1790 * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``)
1791 Like ``Allman`` but always indent braces and line up code with braces.
1849 void bar() { foo(true); }
1852 * ``BS_GNU`` (in configuration: ``GNU``)
1853 Always break before braces and add an extra level of indentation to
1854 braces of control statements, not to those of class, function
1855 or other definitions.
1914 void bar() { foo(true); }
1917 * ``BS_WebKit`` (in configuration: ``WebKit``)
1918 Like ``Attach``, but break before functions.
1963 void bar() { foo(true); }
1966 * ``BS_Custom`` (in configuration: ``Custom``)
1967 Configure each individual brace in `BraceWrapping`.
1971 **BreakBeforeConceptDeclarations** (``Boolean``) :versionbadge:`clang-format 13`
1972 If ``true``, concept will be placed on a new line.
1977 template<typename T>
1981 template<typename T> concept ...
1983 **BreakBeforeTernaryOperators** (``Boolean``) :versionbadge:`clang-format 3.7`
1984 If ``true``, ternary operators will be placed after line breaks.
1989 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
1991 : SecondValueVeryVeryVeryVeryLong;
1994 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
1996 SecondValueVeryVeryVeryVeryLong;
1998 **BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) :versionbadge:`clang-format 5`
1999 The break constructor initializers style to use.
2003 * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``)
2004 Break constructor initializers before the colon and after the commas.
2012 * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
2013 Break constructor initializers before the colon and commas, and align
2014 the commas with the colon.
2022 * ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
2023 Break constructor initializers after the colon and commas.
2033 **BreakInheritanceList** (``BreakInheritanceListStyle``) :versionbadge:`clang-format 7`
2034 The inheritance list style to use.
2038 * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
2039 Break inheritance list before the colon and after the commas.
2048 * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
2049 Break inheritance list before the colon and commas, and align
2050 the commas with the colon.
2059 * ``BILS_AfterColon`` (in configuration: ``AfterColon``)
2060 Break inheritance list after the colon and commas.
2069 * ``BILS_AfterComma`` (in configuration: ``AfterComma``)
2070 Break inheritance list only after the commas.
2080 **BreakStringLiterals** (``Boolean``) :versionbadge:`clang-format 3.9`
2081 Allow breaking string literals when formatting.
2086 const char* x = "veryVeryVeryVeryVeryVe"
2087 "ryVeryVeryVeryVeryVery"
2092 "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
2094 **ColumnLimit** (``Unsigned``) :versionbadge:`clang-format 3.7`
2097 A column limit of ``0`` means that there is no column limit. In this case,
2098 clang-format will respect the input's line breaking decisions within
2099 statements unless they contradict other rules.
2101 **CommentPragmas** (``String``) :versionbadge:`clang-format 3.7`
2102 A regular expression that describes comments with special meaning,
2103 which should not be split into lines or otherwise changed.
2107 // CommentPragmas: '^ FOOBAR pragma:'
2108 // Will leave the following line unaffected
2109 #include <vector> // FOOBAR pragma: keep
2111 **CompactNamespaces** (``Boolean``) :versionbadge:`clang-format 5`
2112 If ``true``, consecutive namespace declarations will be on the same
2113 line. If ``false``, each namespace is declared on a new line.
2118 namespace Foo { namespace Bar {
2127 If it does not fit on a single line, the overflowing namespaces get
2132 namespace Foo { namespace Bar {
2136 **ConstructorInitializerAllOnOneLineOrOnePerLine** (``Boolean``) :versionbadge:`clang-format 3.7`
2137 This option is **deprecated**. See ``CurrentLine`` of
2138 ``PackConstructorInitializers``.
2140 **ConstructorInitializerIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7`
2141 The number of characters to use for indentation of constructor
2142 initializer lists as well as inheritance lists.
2144 **ContinuationIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7`
2145 Indent width for line continuations.
2149 ContinuationIndentWidth: 2
2151 int i = // VeryVeryVeryVeryVeryLongComment
2152 longFunction( // Again a long comment
2155 **Cpp11BracedListStyle** (``Boolean``) :versionbadge:`clang-format 3.4`
2156 If ``true``, format braced lists as best suited for C++11 braced
2159 Important differences:
2160 - No spaces inside the braced list.
2161 - No line break before the closing brace.
2162 - Indentation with the continuation indent, not with the block indent.
2164 Fundamentally, C++11 braced lists are formatted exactly like function
2165 calls would be formatted in their place. If the braced list follows a name
2166 (e.g. a type or variable name), clang-format formats as if the ``{}`` were
2167 the parentheses of a function call with that name. If there is no name,
2168 a zero-length name is assumed.
2173 vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 };
2174 vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} };
2175 f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]);
2176 new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 };
2178 **DeriveLineEnding** (``Boolean``) :versionbadge:`clang-format 11`
2179 Analyze the formatted file for the most used line ending (``\r\n``
2180 or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived.
2182 **DerivePointerAlignment** (``Boolean``) :versionbadge:`clang-format 3.7`
2183 If ``true``, analyze the formatted file for the most common
2184 alignment of ``&`` and ``*``.
2185 Pointer and reference alignment styles are going to be updated according
2186 to the preferences found in the file.
2187 ``PointerAlignment`` is then used only as fallback.
2189 **DisableFormat** (``Boolean``) :versionbadge:`clang-format 3.7`
2190 Disables formatting completely.
2192 **EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``) :versionbadge:`clang-format 14`
2193 Defines when to put an empty line after access modifiers.
2194 ``EmptyLineBeforeAccessModifier`` configuration handles the number of
2195 empty lines between two access modifiers.
2199 * ``ELAAMS_Never`` (in configuration: ``Never``)
2200 Remove all empty lines after access modifiers.
2216 * ``ELAAMS_Leave`` (in configuration: ``Leave``)
2217 Keep existing empty lines after access modifiers.
2218 MaxEmptyLinesToKeep is applied instead.
2220 * ``ELAAMS_Always`` (in configuration: ``Always``)
2221 Always add empty line after access modifiers if there are none.
2222 MaxEmptyLinesToKeep is applied also.
2245 **EmptyLineBeforeAccessModifier** (``EmptyLineBeforeAccessModifierStyle``) :versionbadge:`clang-format 13`
2246 Defines in which cases to put empty line before access modifiers.
2250 * ``ELBAMS_Never`` (in configuration: ``Never``)
2251 Remove all empty lines before access modifiers.
2267 * ``ELBAMS_Leave`` (in configuration: ``Leave``)
2268 Keep existing empty lines before access modifiers.
2270 * ``ELBAMS_LogicalBlock`` (in configuration: ``LogicalBlock``)
2271 Add empty line only when access modifier starts a new logical block.
2272 Logical block is a group of one or more member fields or functions.
2290 * ``ELBAMS_Always`` (in configuration: ``Always``)
2291 Always add empty line before access modifiers unless access modifier
2292 is at the start of struct or class definition.
2314 **ExperimentalAutoDetectBinPacking** (``Boolean``) :versionbadge:`clang-format 3.7`
2315 If ``true``, clang-format detects whether function calls and
2316 definitions are formatted with one parameter per line.
2318 Each call can be bin-packed, one-per-line or inconclusive. If it is
2319 inconclusive, e.g. completely on one line, but a decision needs to be
2320 made, clang-format analyzes whether there are other bin-packed cases in
2321 the input file and act accordingly.
2323 NOTE: This is an experimental flag, that might go away or be renamed. Do
2324 not use this in config files, etc. Use at your own risk.
2326 **FixNamespaceComments** (``Boolean``) :versionbadge:`clang-format 5`
2327 If ``true``, clang-format adds missing namespace end comments for
2328 short namespaces and fixes invalid existing ones. Short ones are
2329 controlled by "ShortNamespaceLines".
2334 namespace a { vs. namespace a {
2339 **ForEachMacros** (``List of Strings``) :versionbadge:`clang-format 3.7`
2340 A vector of macros that should be interpreted as foreach loops
2341 instead of as function calls.
2343 These are expected to be macros of the form:
2347 FOREACH(<variable-declaration>, ...)
2350 In the .clang-format configuration file, this can be configured like:
2352 .. code-block:: yaml
2354 ForEachMacros: ['RANGES_FOR', 'FOREACH']
2356 For example: BOOST_FOREACH.
2358 **IfMacros** (``List of Strings``) :versionbadge:`clang-format 14`
2359 A vector of macros that should be interpreted as conditionals
2360 instead of as function calls.
2362 These are expected to be macros of the form:
2371 In the .clang-format configuration file, this can be configured like:
2373 .. code-block:: yaml
2377 For example: `KJ_IF_MAYBE
2378 <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_
2380 **IncludeBlocks** (``IncludeBlocksStyle``) :versionbadge:`clang-format 7`
2381 Dependent on the value, multiple ``#include`` blocks can be sorted
2382 as one and divided based on category.
2386 * ``IBS_Preserve`` (in configuration: ``Preserve``)
2387 Sort each ``#include`` block separately.
2391 #include "b.h" into #include "b.h"
2393 #include <lib/main.h> #include "a.h"
2394 #include "a.h" #include <lib/main.h>
2396 * ``IBS_Merge`` (in configuration: ``Merge``)
2397 Merge multiple ``#include`` blocks together and sort as one.
2401 #include "b.h" into #include "a.h"
2403 #include <lib/main.h> #include <lib/main.h>
2406 * ``IBS_Regroup`` (in configuration: ``Regroup``)
2407 Merge multiple ``#include`` blocks together and sort as one.
2408 Then split into groups based on category priority. See
2409 ``IncludeCategories``.
2413 #include "b.h" into #include "a.h"
2415 #include <lib/main.h>
2416 #include "a.h" #include <lib/main.h>
2420 **IncludeCategories** (``List of IncludeCategories``) :versionbadge:`clang-format 7`
2421 Regular expressions denoting the different ``#include`` categories
2422 used for ordering ``#includes``.
2425 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
2426 regular expressions are supported.
2428 These regular expressions are matched against the filename of an include
2429 (including the <> or "") in order. The value belonging to the first
2430 matching regular expression is assigned and ``#includes`` are sorted first
2431 according to increasing category number and then alphabetically within
2434 If none of the regular expressions match, INT_MAX is assigned as
2435 category. The main header for a source file automatically gets category 0.
2436 so that it is generally kept at the beginning of the ``#includes``
2437 (https://llvm.org/docs/CodingStandards.html#include-style). However, you
2438 can also assign negative priorities if you have certain headers that
2439 always need to be first.
2441 There is a third and optional field ``SortPriority`` which can used while
2442 ``IncludeBlocks = IBS_Regroup`` to define the priority in which
2443 ``#includes`` should be ordered. The value of ``Priority`` defines the
2444 order of ``#include blocks`` and also allows the grouping of ``#includes``
2445 of different priority. ``SortPriority`` is set to the value of
2446 ``Priority`` as default if it is not assigned.
2448 Each regular expression can be marked as case sensitive with the field
2449 ``CaseSensitive``, per default it is not.
2451 To configure this in the .clang-format file, use:
2453 .. code-block:: yaml
2456 - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
2460 - Regex: '^(<|"(gtest|gmock|isl|json)/)'
2462 - Regex: '<[[:alnum:].]+>'
2468 **IncludeIsMainRegex** (``String``) :versionbadge:`clang-format 7`
2469 Specify a regular expression of suffixes that are allowed in the
2470 file-to-main-include mapping.
2472 When guessing whether a #include is the "main" include (to assign
2473 category 0, see above), use this regex of allowed suffixes to the header
2474 stem. A partial match is done, so that:
2475 - "" means "arbitrary suffix"
2476 - "$" means "no suffix"
2478 For example, if configured to "(_test)?$", then a header a.h would be seen
2479 as the "main" include in both a.cc and a_test.cc.
2481 **IncludeIsMainSourceRegex** (``String``) :versionbadge:`clang-format 7`
2482 Specify a regular expression for files being formatted
2483 that are allowed to be considered "main" in the
2484 file-to-main-include mapping.
2486 By default, clang-format considers files as "main" only when they end
2487 with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm``
2489 For these files a guessing of "main" include takes place
2490 (to assign category 0, see above). This config option allows for
2491 additional suffixes and extensions for files to be considered as "main".
2493 For example, if this option is configured to ``(Impl\.hpp)$``,
2494 then a file ``ClassImpl.hpp`` is considered "main" (in addition to
2495 ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main
2496 include file" logic will be executed (with *IncludeIsMainRegex* setting
2497 also being respected in later phase). Without this option set,
2498 ``ClassImpl.hpp`` would not have the main include file put on top
2499 before any other include.
2501 **IndentAccessModifiers** (``Boolean``) :versionbadge:`clang-format 13`
2502 Specify whether access modifiers should have their own indentation level.
2504 When ``false``, access modifiers are indented (or outdented) relative to
2505 the record members, respecting the ``AccessModifierOffset``. Record
2506 members are indented one level below the record.
2507 When ``true``, access modifiers get their own indentation level. As a
2508 consequence, record members are always indented 2 levels below the record,
2509 regardless of the access modifier presence. Value of the
2510 ``AccessModifierOffset`` is ignored.
2515 class C { vs. class C {
2517 void bar(); void bar();
2518 protected: protected:
2524 void foo() { void foo() {
2528 **IndentCaseBlocks** (``Boolean``) :versionbadge:`clang-format 11`
2529 Indent case label blocks one level from the case label.
2531 When ``false``, the block following the case label uses the same
2532 indentation level as for the case label, treating the case label the same
2534 When ``true``, the block gets indented as a scope block.
2539 switch (fool) { vs. switch (fool) {
2551 **IndentCaseLabels** (``Boolean``) :versionbadge:`clang-format 3.3`
2552 Indent case labels one level from the switch statement.
2554 When ``false``, use the same indentation level as for the switch
2555 statement. Switch statement body is always indented one level more than
2556 case labels (except the first block following the case label, which
2557 itself indents the code - unless IndentCaseBlocks is enabled).
2562 switch (fool) { vs. switch (fool) {
2570 **IndentExternBlock** (``IndentExternBlockStyle``) :versionbadge:`clang-format 12`
2571 IndentExternBlockStyle is the type of indenting of extern blocks.
2575 * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``)
2576 Backwards compatible with AfterExternBlock's indenting.
2580 IndentExternBlock: AfterExternBlock
2581 BraceWrapping.AfterExternBlock: true
2590 IndentExternBlock: AfterExternBlock
2591 BraceWrapping.AfterExternBlock: false
2596 * ``IEBS_NoIndent`` (in configuration: ``NoIndent``)
2597 Does not indent extern blocks.
2605 * ``IEBS_Indent`` (in configuration: ``Indent``)
2606 Indents extern blocks.
2616 **IndentGotoLabels** (``Boolean``) :versionbadge:`clang-format 10`
2619 When ``false``, goto labels are flushed left.
2624 int f() { vs. int f() {
2625 if (foo()) { if (foo()) {
2633 **IndentPPDirectives** (``PPDirectiveIndentStyle``) :versionbadge:`clang-format 6`
2634 The preprocessor directive indenting style to use.
2638 * ``PPDIS_None`` (in configuration: ``None``)
2639 Does not indent any directives.
2649 * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``)
2650 Indents directives after the hash.
2660 * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``)
2661 Indents directives before the hash.
2673 **IndentRequires** (``Boolean``) :versionbadge:`clang-format 13`
2674 Indent the requires clause in a template
2679 template <typename It>
2680 requires Iterator<It>
2681 void sort(It begin, It end) {
2686 template <typename It>
2687 requires Iterator<It>
2688 void sort(It begin, It end) {
2692 **IndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7`
2693 The number of columns to use for indentation.
2706 **IndentWrappedFunctionNames** (``Boolean``) :versionbadge:`clang-format 3.7`
2707 Indent if a function definition or declaration is wrapped after the
2713 LoooooooooooooooooooooooooooooooooooooooongReturnType
2714 LoooooooooooooooooooooooooooooooongFunctionDeclaration();
2717 LoooooooooooooooooooooooooooooooooooooooongReturnType
2718 LoooooooooooooooooooooooooooooooongFunctionDeclaration();
2720 **InsertTrailingCommas** (``TrailingCommaStyle``) :versionbadge:`clang-format 12`
2721 If set to ``TCS_Wrapped`` will insert trailing commas in container
2722 literals (arrays and objects) that wrap across multiple lines.
2723 It is currently only available for JavaScript
2724 and disabled by default ``TCS_None``.
2725 ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
2726 as inserting the comma disables bin-packing.
2732 aaaaaaaaaaaaaaaaaaaaaaaaaa,
2733 aaaaaaaaaaaaaaaaaaaaaaaaaa,
2734 aaaaaaaaaaaaaaaaaaaaaaaaaa,
2740 * ``TCS_None`` (in configuration: ``None``)
2741 Do not insert trailing commas.
2743 * ``TCS_Wrapped`` (in configuration: ``Wrapped``)
2744 Insert trailing commas in container literals that were wrapped over
2745 multiple lines. Note that this is conceptually incompatible with
2746 bin-packing, because the trailing comma is used as an indicator
2747 that a container should be formatted one-per-line (i.e. not bin-packed).
2748 So inserting a trailing comma counteracts bin-packing.
2752 **JavaImportGroups** (``List of Strings``) :versionbadge:`clang-format 8`
2753 A vector of prefixes ordered by the desired groups for Java imports.
2755 One group's prefix can be a subset of another - the longest prefix is
2756 always matched. Within a group, the imports are ordered lexicographically.
2757 Static imports are grouped separately and follow the same group rules.
2758 By default, static imports are placed before non-static imports,
2759 but this behavior is changed by another option,
2760 ``SortJavaStaticImport``.
2762 In the .clang-format configuration file, this can be configured like
2763 in the following yaml example. This will result in imports being
2764 formatted as in the Java example below.
2766 .. code-block:: yaml
2768 JavaImportGroups: ['com.example', 'com', 'org']
2771 .. code-block:: java
2773 import static com.example.function1;
2775 import static com.test.function2;
2777 import static org.example.function3;
2779 import com.example.ClassA;
2780 import com.example.Test;
2781 import com.example.a.ClassB;
2783 import com.test.ClassC;
2785 import org.example.ClassD;
2787 **JavaScriptQuotes** (``JavaScriptQuoteStyle``) :versionbadge:`clang-format 3.9`
2788 The JavaScriptQuoteStyle to use for JavaScript strings.
2792 * ``JSQS_Leave`` (in configuration: ``Leave``)
2793 Leave string quotes as they are.
2800 * ``JSQS_Single`` (in configuration: ``Single``)
2801 Always use single quotes.
2808 * ``JSQS_Double`` (in configuration: ``Double``)
2809 Always use double quotes.
2818 **JavaScriptWrapImports** (``Boolean``) :versionbadge:`clang-format 3.9`
2819 Whether to wrap JavaScript import/export statements.
2825 VeryLongImportsAreAnnoying,
2826 VeryLongImportsAreAnnoying,
2827 VeryLongImportsAreAnnoying,
2828 } from 'some/module.js'
2831 import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
2833 **KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``) :versionbadge:`clang-format 3.7`
2834 If true, the empty line at the start of blocks is kept.
2839 if (foo) { vs. if (foo) {
2844 **LambdaBodyIndentation** (``LambdaBodyIndentationKind``) :versionbadge:`clang-format 13`
2845 The indentation style of lambda bodies. ``Signature`` (the default)
2846 causes the lambda body to be indented one additional level relative to
2847 the indentation level of the signature. ``OuterScope`` forces the lambda
2848 body to be indented one additional level relative to the parent scope
2849 containing the lambda signature. For callback-heavy code, it may improve
2850 readability to have the signature indented two levels and to use
2851 ``OuterScope``. The KJ style guide requires ``OuterScope``.
2853 <https://github.com/capnproto/capnproto/blob/master/kjdoc/style-guide.md>`_
2857 * ``LBI_Signature`` (in configuration: ``Signature``)
2858 Align lambda body relative to the lambda signature. This is the default.
2863 [](SomeReallyLongLambdaSignatureArgument foo) {
2867 * ``LBI_OuterScope`` (in configuration: ``OuterScope``)
2868 Align lambda body relative to the indentation level of the outer scope
2869 the lambda signature resides in.
2874 [](SomeReallyLongLambdaSignatureArgument foo) {
2880 **Language** (``LanguageKind``) :versionbadge:`clang-format 3.5`
2881 Language, this format style is targeted at.
2885 * ``LK_None`` (in configuration: ``None``)
2888 * ``LK_Cpp`` (in configuration: ``Cpp``)
2889 Should be used for C, C++.
2891 * ``LK_CSharp`` (in configuration: ``CSharp``)
2892 Should be used for C#.
2894 * ``LK_Java`` (in configuration: ``Java``)
2895 Should be used for Java.
2897 * ``LK_JavaScript`` (in configuration: ``JavaScript``)
2898 Should be used for JavaScript.
2900 * ``LK_Json`` (in configuration: ``Json``)
2901 Should be used for JSON.
2903 * ``LK_ObjC`` (in configuration: ``ObjC``)
2904 Should be used for Objective-C, Objective-C++.
2906 * ``LK_Proto`` (in configuration: ``Proto``)
2907 Should be used for Protocol Buffers
2908 (https://developers.google.com/protocol-buffers/).
2910 * ``LK_TableGen`` (in configuration: ``TableGen``)
2911 Should be used for TableGen code.
2913 * ``LK_TextProto`` (in configuration: ``TextProto``)
2914 Should be used for Protocol Buffer messages in text format
2915 (https://developers.google.com/protocol-buffers/).
2919 **MacroBlockBegin** (``String``) :versionbadge:`clang-format 3.7`
2920 A regular expression matching macros that start a block.
2925 MacroBlockBegin: "^NS_MAP_BEGIN|\
2948 **MacroBlockEnd** (``String``) :versionbadge:`clang-format 3.7`
2949 A regular expression matching macros that end a block.
2951 **MaxEmptyLinesToKeep** (``Unsigned``) :versionbadge:`clang-format 3.7`
2952 The maximum number of consecutive empty lines to keep.
2956 MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0
2960 i = foo(); return i;
2965 **NamespaceIndentation** (``NamespaceIndentationKind``) :versionbadge:`clang-format 3.7`
2966 The indentation used for namespaces.
2970 * ``NI_None`` (in configuration: ``None``)
2971 Don't indent in namespaces.
2982 * ``NI_Inner`` (in configuration: ``Inner``)
2983 Indent only in inner namespaces (nested in other namespaces).
2994 * ``NI_All`` (in configuration: ``All``)
2995 Indent in all namespaces.
3008 **NamespaceMacros** (``List of Strings``) :versionbadge:`clang-format 9`
3009 A vector of macros which are used to open namespace blocks.
3011 These are expected to be macros of the form:
3015 NAMESPACE(<namespace-name>, ...) {
3019 For example: TESTSUITE
3021 **ObjCBinPackProtocolList** (``BinPackStyle``) :versionbadge:`clang-format 7`
3022 Controls bin-packing Objective-C protocol conformance list
3023 items into as few lines as possible when they go over ``ColumnLimit``.
3025 If ``Auto`` (the default), delegates to the value in
3026 ``BinPackParameters``. If that is ``true``, bin-packs Objective-C
3027 protocol conformance list items into as few lines as possible
3028 whenever they go over ``ColumnLimit``.
3030 If ``Always``, always bin-packs Objective-C protocol conformance
3031 list items into as few lines as possible whenever they go over
3034 If ``Never``, lays out Objective-C protocol conformance list items
3035 onto individual lines whenever they go over ``ColumnLimit``.
3038 .. code-block:: objc
3040 Always (or Auto, if BinPackParameters=true):
3041 @interface ccccccccccccc () <
3042 ccccccccccccc, ccccccccccccc,
3043 ccccccccccccc, ccccccccccccc> {
3046 Never (or Auto, if BinPackParameters=false):
3047 @interface ddddddddddddd () <
3056 * ``BPS_Auto`` (in configuration: ``Auto``)
3057 Automatically determine parameter bin-packing behavior.
3059 * ``BPS_Always`` (in configuration: ``Always``)
3060 Always bin-pack parameters.
3062 * ``BPS_Never`` (in configuration: ``Never``)
3063 Never bin-pack parameters.
3067 **ObjCBlockIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7`
3068 The number of characters to use for indentation of ObjC blocks.
3070 .. code-block:: objc
3072 ObjCBlockIndentWidth: 4
3074 [operation setCompletionBlock:^{
3075 [self onOperationDone];
3078 **ObjCBreakBeforeNestedBlockParam** (``Boolean``) :versionbadge:`clang-format 12`
3079 Break parameters list into lines when there is nested block
3080 parameters in a function call.
3087 [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
3097 callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
3102 **ObjCSpaceAfterProperty** (``Boolean``) :versionbadge:`clang-format 3.7`
3103 Add a space after ``@property`` in Objective-C, i.e. use
3104 ``@property (readonly)`` instead of ``@property(readonly)``.
3106 **ObjCSpaceBeforeProtocolList** (``Boolean``) :versionbadge:`clang-format 3.7`
3107 Add a space in front of an Objective-C protocol list, i.e. use
3108 ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
3110 **PPIndentWidth** (``Integer``) :versionbadge:`clang-format 14`
3111 The number of columns to use for indentation of preprocessor statements.
3112 When set to -1 (default) ``IndentWidth`` is used also for preprocessor
3125 **PackConstructorInitializers** (``PackConstructorInitializersStyle``) :versionbadge:`clang-format 14`
3126 The pack constructor initializers style to use.
3130 * ``PCIS_Never`` (in configuration: ``Never``)
3131 Always put each constructor initializer on its own line.
3139 * ``PCIS_BinPack`` (in configuration: ``BinPack``)
3140 Bin-pack constructor initializers.
3145 : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(),
3146 cccccccccccccccccccc()
3148 * ``PCIS_CurrentLine`` (in configuration: ``CurrentLine``)
3149 Put all constructor initializers on the current line if they fit.
3150 Otherwise, put each one on its own line.
3154 Constructor() : a(), b()
3157 : aaaaaaaaaaaaaaaaaaaa(),
3158 bbbbbbbbbbbbbbbbbbbb(),
3161 * ``PCIS_NextLine`` (in configuration: ``NextLine``)
3162 Same as ``PCIS_CurrentLine`` except that if all constructor initializers
3163 do not fit on the current line, try to fit them on the next line.
3167 Constructor() : a(), b()
3170 : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
3173 : aaaaaaaaaaaaaaaaaaaa(),
3174 bbbbbbbbbbbbbbbbbbbb(),
3175 cccccccccccccccccccc()
3179 **PenaltyBreakAssignment** (``Unsigned``) :versionbadge:`clang-format 5`
3180 The penalty for breaking around an assignment operator.
3182 **PenaltyBreakBeforeFirstCallParameter** (``Unsigned``) :versionbadge:`clang-format 3.7`
3183 The penalty for breaking a function call after ``call(``.
3185 **PenaltyBreakComment** (``Unsigned``) :versionbadge:`clang-format 3.7`
3186 The penalty for each line break introduced inside a comment.
3188 **PenaltyBreakFirstLessLess** (``Unsigned``) :versionbadge:`clang-format 3.7`
3189 The penalty for breaking before the first ``<<``.
3191 **PenaltyBreakString** (``Unsigned``) :versionbadge:`clang-format 3.7`
3192 The penalty for each line break introduced inside a string literal.
3194 **PenaltyBreakTemplateDeclaration** (``Unsigned``) :versionbadge:`clang-format 7`
3195 The penalty for breaking after template declaration.
3197 **PenaltyExcessCharacter** (``Unsigned``) :versionbadge:`clang-format 3.7`
3198 The penalty for each character outside of the column limit.
3200 **PenaltyIndentedWhitespace** (``Unsigned``) :versionbadge:`clang-format 12`
3201 Penalty for each character of whitespace indentation
3202 (counted relative to leading non-whitespace column).
3204 **PenaltyReturnTypeOnItsOwnLine** (``Unsigned``) :versionbadge:`clang-format 3.7`
3205 Penalty for putting the return type of a function onto its own
3208 **PointerAlignment** (``PointerAlignmentStyle``) :versionbadge:`clang-format 3.7`
3209 Pointer and reference alignment style.
3213 * ``PAS_Left`` (in configuration: ``Left``)
3214 Align pointer to the left.
3220 * ``PAS_Right`` (in configuration: ``Right``)
3221 Align pointer to the right.
3227 * ``PAS_Middle`` (in configuration: ``Middle``)
3228 Align pointer in the middle.
3236 **QualifierAlignment** (``QualifierAlignmentStyle``) :versionbadge:`clang-format 14`
3237 Different ways to arrange specifiers and qualifiers (e.g. const/volatile).
3241 Setting ``QualifierAlignment`` to something other than `Leave`, COULD
3242 lead to incorrect code formatting due to incorrect decisions made due to
3243 clang-formats lack of complete semantic information.
3244 As such extra care should be taken to review code changes made by the use
3249 * ``QAS_Leave`` (in configuration: ``Leave``)
3250 Don't change specifiers/qualifiers to either Left or Right alignment
3258 * ``QAS_Left`` (in configuration: ``Left``)
3259 Change specifiers/qualifiers to be left-aligned.
3266 * ``QAS_Right`` (in configuration: ``Right``)
3267 Change specifiers/qualifiers to be right-aligned.
3274 * ``QAS_Custom`` (in configuration: ``Custom``)
3275 Change specifiers/qualifiers to be aligned based on ``QualifierOrder``.
3278 .. code-block:: yaml
3280 QualifierOrder: ['inline', 'static' , 'type', 'const']
3291 **QualifierOrder** (``List of Strings``) :versionbadge:`clang-format 14`
3292 The order in which the qualifiers appear.
3293 Order is an array that can contain any of the following:
3303 Note: it MUST contain 'type'.
3304 Items to the left of 'type' will be placed to the left of the type and
3305 aligned in the order supplied. Items to the right of 'type' will be placed
3306 to the right of the type and aligned in the order supplied.
3309 .. code-block:: yaml
3311 QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ]
3313 **RawStringFormats** (``List of RawStringFormats``) :versionbadge:`clang-format 6`
3314 Defines hints for detecting supported languages code blocks in raw
3317 A raw string with a matching delimiter or a matching enclosing function
3318 name will be reformatted assuming the specified language based on the
3319 style for that language defined in the .clang-format file. If no style has
3320 been defined in the .clang-format file for the specific language, a
3321 predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not
3322 found, the formatting is based on llvm style. A matching delimiter takes
3323 precedence over a matching enclosing function name for determining the
3324 language of the raw string contents.
3326 If a canonical delimiter is specified, occurrences of other delimiters for
3327 the same language will be updated to the canonical if possible.
3329 There should be at most one specification per language and each delimiter
3330 and enclosing function should not occur in multiple specifications.
3332 To configure this in the .clang-format file, use:
3334 .. code-block:: yaml
3337 - Language: TextProto
3342 - 'PARSE_TEXT_PROTO'
3343 BasedOnStyle: google
3349 CanonicalDelimiter: 'cc'
3351 **ReferenceAlignment** (``ReferenceAlignmentStyle``) :versionbadge:`clang-format 14`
3352 Reference alignment style (overrides ``PointerAlignment`` for
3357 * ``RAS_Pointer`` (in configuration: ``Pointer``)
3358 Align reference like ``PointerAlignment``.
3360 * ``RAS_Left`` (in configuration: ``Left``)
3361 Align reference to the left.
3367 * ``RAS_Right`` (in configuration: ``Right``)
3368 Align reference to the right.
3374 * ``RAS_Middle`` (in configuration: ``Middle``)
3375 Align reference in the middle.
3383 **ReflowComments** (``Boolean``) :versionbadge:`clang-format 4`
3384 If ``true``, clang-format will attempt to re-flow comments.
3389 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
3390 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
3393 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
3395 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
3398 **ShortNamespaceLines** (``Unsigned``) :versionbadge:`clang-format 14`
3399 The maximal number of unwrapped lines that a short namespace spans.
3402 This determines the maximum length of short namespaces by counting
3403 unwrapped lines (i.e. containing neither opening nor closing
3404 namespace brace) and makes "FixNamespaceComments" omit adding
3405 end comments for those.
3409 ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
3410 namespace a { namespace a {
3414 ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
3415 namespace b { namespace b {
3418 } // namespace b } // namespace b
3420 **SortIncludes** (``SortIncludesOptions``) :versionbadge:`clang-format 4`
3421 Controls if and how clang-format will sort ``#includes``.
3422 If ``Never``, includes are never sorted.
3423 If ``CaseInsensitive``, includes are sorted in an ASCIIbetical or case
3424 insensitive fashion.
3425 If ``CaseSensitive``, includes are sorted in an alphabetical or case
3430 * ``SI_Never`` (in configuration: ``Never``)
3431 Includes are never sorted.
3441 * ``SI_CaseSensitive`` (in configuration: ``CaseSensitive``)
3442 Includes are sorted in an ASCIIbetical or case sensitive fashion.
3452 * ``SI_CaseInsensitive`` (in configuration: ``CaseInsensitive``)
3453 Includes are sorted in an alphabetical or case insensitive fashion.
3465 **SortJavaStaticImport** (``SortJavaStaticImportOptions``) :versionbadge:`clang-format 12`
3466 When sorting Java imports, by default static imports are placed before
3467 non-static imports. If ``JavaStaticImportAfterImport`` is ``After``,
3468 static imports are placed after non-static imports.
3472 * ``SJSIO_Before`` (in configuration: ``Before``)
3473 Static imports are placed before non-static imports.
3475 .. code-block:: java
3477 import static org.example.function1;
3479 import org.example.ClassA;
3481 * ``SJSIO_After`` (in configuration: ``After``)
3482 Static imports are placed after non-static imports.
3484 .. code-block:: java
3486 import org.example.ClassA;
3488 import static org.example.function1;
3492 **SortUsingDeclarations** (``Boolean``) :versionbadge:`clang-format 5`
3493 If ``true``, clang-format will sort using declarations.
3495 The order of using declarations is defined as follows:
3496 Split the strings by "::" and discard any initial empty strings. The last
3497 element of each list is a non-namespace name; all others are namespace
3498 names. Sort the lists of names lexicographically, where the sort order of
3499 individual names is that all non-namespace names come before all namespace
3500 names, and within those groups, names are in case-insensitive
3501 lexicographic order.
3506 using std::cout; vs. using std::cin;
3507 using std::cin; using std::cout;
3509 **SpaceAfterCStyleCast** (``Boolean``) :versionbadge:`clang-format 3.5`
3510 If ``true``, a space is inserted after C style casts.
3515 (int) i; vs. (int)i;
3517 **SpaceAfterLogicalNot** (``Boolean``) :versionbadge:`clang-format 9`
3518 If ``true``, a space is inserted after the logical not operator (``!``).
3523 ! someExpression(); vs. !someExpression();
3525 **SpaceAfterTemplateKeyword** (``Boolean``) :versionbadge:`clang-format 4`
3526 If ``true``, a space will be inserted after the 'template' keyword.
3531 template <int> void foo(); vs. template<int> void foo();
3533 **SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``) :versionbadge:`clang-format 12`
3534 Defines in which cases to put a space before or after pointer qualifiers
3538 * ``SAPQ_Default`` (in configuration: ``Default``)
3539 Don't ensure spaces around pointer qualifiers and use PointerAlignment
3544 PointerAlignment: Left PointerAlignment: Right
3545 void* const* x = NULL; vs. void *const *x = NULL;
3547 * ``SAPQ_Before`` (in configuration: ``Before``)
3548 Ensure that there is a space before pointer qualifiers.
3552 PointerAlignment: Left PointerAlignment: Right
3553 void* const* x = NULL; vs. void * const *x = NULL;
3555 * ``SAPQ_After`` (in configuration: ``After``)
3556 Ensure that there is a space after pointer qualifiers.
3560 PointerAlignment: Left PointerAlignment: Right
3561 void* const * x = NULL; vs. void *const *x = NULL;
3563 * ``SAPQ_Both`` (in configuration: ``Both``)
3564 Ensure that there is a space both before and after pointer qualifiers.
3568 PointerAlignment: Left PointerAlignment: Right
3569 void* const * x = NULL; vs. void * const *x = NULL;
3573 **SpaceBeforeAssignmentOperators** (``Boolean``) :versionbadge:`clang-format 3.7`
3574 If ``false``, spaces will be removed before assignment operators.
3579 int a = 5; vs. int a= 5;
3582 **SpaceBeforeCaseColon** (``Boolean``) :versionbadge:`clang-format 12`
3583 If ``false``, spaces will be removed before case colon.
3588 switch (x) { vs. switch (x) {
3589 case 1 : break; case 1: break;
3592 **SpaceBeforeCpp11BracedList** (``Boolean``) :versionbadge:`clang-format 7`
3593 If ``true``, a space will be inserted before a C++11 braced list
3594 used to initialize an object (after the preceding identifier or type).
3599 Foo foo { bar }; vs. Foo foo{ bar };
3601 vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
3602 new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
3604 **SpaceBeforeCtorInitializerColon** (``Boolean``) :versionbadge:`clang-format 7`
3605 If ``false``, spaces will be removed before constructor initializer
3611 Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
3613 **SpaceBeforeInheritanceColon** (``Boolean``) :versionbadge:`clang-format 7`
3614 If ``false``, spaces will be removed before inheritance colon.
3619 class Foo : Bar {} vs. class Foo: Bar {}
3621 **SpaceBeforeParens** (``SpaceBeforeParensStyle``) :versionbadge:`clang-format 3.5`
3622 Defines in which cases to put a space before opening parentheses.
3626 * ``SBPO_Never`` (in configuration: ``Never``)
3627 Never put a space before opening parentheses.
3637 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
3638 Put a space before opening parentheses only after control statement
3639 keywords (``for/if/while...``).
3649 * ``SBPO_ControlStatementsExceptControlMacros`` (in configuration: ``ControlStatementsExceptControlMacros``)
3650 Same as ``SBPO_ControlStatements`` except this option doesn't apply to
3651 ForEach and If macros. This is useful in projects where ForEach/If
3652 macros are treated as function calls instead of control statements.
3653 ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for
3654 backward compatibility.
3664 * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``)
3665 Put a space before opening parentheses only if the parentheses are not
3677 * ``SBPO_Always`` (in configuration: ``Always``)
3678 Always put a space before opening parentheses, except when it's
3679 prohibited by the syntax rules (in function-like macro definitions) or
3680 when determined by other style rules (after unary operators, opening
3691 * ``SBPO_Custom`` (in configuration: ``Custom``)
3692 Configure each individual space before parentheses in
3693 `SpaceBeforeParensOptions`.
3697 **SpaceBeforeParensOptions** (``SpaceBeforeParensCustom``) :versionbadge:`clang-format 14`
3698 Control of individual space before parentheses.
3700 If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify
3701 how each individual space before parentheses case should be handled.
3702 Otherwise, this is ignored.
3704 .. code-block:: yaml
3707 SpaceBeforeParens: Custom
3708 SpaceBeforeParensOptions:
3709 AfterControlStatements: true
3710 AfterFunctionDefinitionName: true
3712 Nested configuration flags:
3715 * ``bool AfterControlStatements`` If ``true``, put space betwee control statement keywords
3716 (for/if/while...) and opening parentheses.
3721 if (...) {} vs. if(...) {}
3723 * ``bool AfterForeachMacros`` If ``true``, put space between foreach macros and opening parentheses.
3728 FOREACH (...) vs. FOREACH(...)
3729 <loop-body> <loop-body>
3731 * ``bool AfterFunctionDeclarationName`` If ``true``, put a space between function declaration name and opening
3737 void f (); vs. void f();
3739 * ``bool AfterFunctionDefinitionName`` If ``true``, put a space between function definition name and opening
3745 void f () {} vs. void f() {}
3747 * ``bool AfterIfMacros`` If ``true``, put space between if macros and opening parentheses.
3752 IF (...) vs. IF(...)
3753 <conditional-body> <conditional-body>
3755 * ``bool BeforeNonEmptyParentheses`` If ``true``, put a space before opening parentheses only if the
3756 parentheses are not empty.
3761 void f (int a); vs. void f();
3765 **SpaceBeforeRangeBasedForLoopColon** (``Boolean``) :versionbadge:`clang-format 7`
3766 If ``false``, spaces will be removed before range-based for loop
3772 for (auto v : values) {} vs. for(auto v: values) {}
3774 **SpaceBeforeSquareBrackets** (``Boolean``) :versionbadge:`clang-format 11`
3775 If ``true``, spaces will be before ``[``.
3776 Lambdas will not be affected. Only the first ``[`` will get a space added.
3781 int a [5]; vs. int a[5];
3782 int a [5][5]; vs. int a[5][5];
3784 **SpaceInEmptyBlock** (``Boolean``) :versionbadge:`clang-format 11`
3785 If ``true``, spaces will be inserted into ``{}``.
3790 void f() { } vs. void f() {}
3791 while (true) { } while (true) {}
3793 **SpaceInEmptyParentheses** (``Boolean``) :versionbadge:`clang-format 3.7`
3794 If ``true``, spaces may be inserted into ``()``.
3799 void f( ) { vs. void f() {
3800 int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()};
3801 if (true) { if (true) {
3806 **SpacesBeforeTrailingComments** (``Unsigned``) :versionbadge:`clang-format 3.7`
3807 The number of spaces before trailing line comments
3808 (``//`` - comments).
3810 This does not affect trailing block comments (``/*`` - comments) as
3811 those commonly have different usage patterns and a number of special
3816 SpacesBeforeTrailingComments: 3
3823 **SpacesInAngles** (``SpacesInAnglesStyle``) :versionbadge:`clang-format 14`
3824 The SpacesInAnglesStyle to use for template argument lists.
3828 * ``SIAS_Never`` (in configuration: ``Never``)
3829 Remove spaces after ``<`` and before ``>``.
3833 static_cast<int>(arg);
3834 std::function<void(int)> fct;
3836 * ``SIAS_Always`` (in configuration: ``Always``)
3837 Add spaces after ``<`` and before ``>``.
3841 static_cast< int >(arg);
3842 std::function< void(int) > fct;
3844 * ``SIAS_Leave`` (in configuration: ``Leave``)
3845 Keep a single space after ``<`` and before ``>`` if any spaces were
3846 present. Option ``Standard: Cpp03`` takes precedence.
3850 **SpacesInCStyleCastParentheses** (``Boolean``) :versionbadge:`clang-format 3.7`
3851 If ``true``, spaces may be inserted into C style casts.
3856 x = ( int32 )y vs. x = (int32)y
3858 **SpacesInConditionalStatement** (``Boolean``) :versionbadge:`clang-format 11`
3859 If ``true``, spaces will be inserted around if/for/switch/while
3865 if ( a ) { ... } vs. if (a) { ... }
3866 while ( i < 5 ) { ... } while (i < 5) { ... }
3868 **SpacesInContainerLiterals** (``Boolean``) :versionbadge:`clang-format 3.7`
3869 If ``true``, spaces are inserted inside container literals (e.g.
3870 ObjC and Javascript array and dict literals).
3875 var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
3876 f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3});
3878 **SpacesInLineCommentPrefix** (``SpacesInLineComment``) :versionbadge:`clang-format 14`
3879 How many spaces are allowed at the start of a line comment. To disable the
3880 maximum set it to ``-1``, apart from that the maximum takes precedence
3887 // One space is forced
3889 // but more spaces are possible
3893 //Forces to start every comment directly after the slashes
3895 Note that in line comment sections the relative indent of the subsequent
3896 lines is kept, that means the following:
3902 //if (b) { // if (b) {
3903 // return true; // return true;
3911 Nested configuration flags:
3914 * ``unsigned Minimum`` The minimum number of spaces at the start of the comment.
3916 * ``unsigned Maximum`` The maximum number of spaces at the start of the comment.
3919 **SpacesInParentheses** (``Boolean``) :versionbadge:`clang-format 3.7`
3920 If ``true``, spaces will be inserted after ``(`` and before ``)``.
3925 t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
3927 **SpacesInSquareBrackets** (``Boolean``) :versionbadge:`clang-format 3.7`
3928 If ``true``, spaces will be inserted after ``[`` and before ``]``.
3929 Lambdas without arguments or unspecified size array declarations will not
3935 int a[ 5 ]; vs. int a[5];
3936 std::unique_ptr<int[]> foo() {} // Won't be affected
3938 **Standard** (``LanguageStandard``) :versionbadge:`clang-format 3.7`
3939 Parse and format C++ constructs compatible with this standard.
3944 vector<set<int> > x; vs. vector<set<int>> x;
3948 * ``LS_Cpp03`` (in configuration: ``c++03``)
3949 Parse and format as C++03.
3950 ``Cpp03`` is a deprecated alias for ``c++03``
3952 * ``LS_Cpp11`` (in configuration: ``c++11``)
3953 Parse and format as C++11.
3955 * ``LS_Cpp14`` (in configuration: ``c++14``)
3956 Parse and format as C++14.
3958 * ``LS_Cpp17`` (in configuration: ``c++17``)
3959 Parse and format as C++17.
3961 * ``LS_Cpp20`` (in configuration: ``c++20``)
3962 Parse and format as C++20.
3964 * ``LS_Latest`` (in configuration: ``Latest``)
3965 Parse and format using the latest supported language version.
3966 ``Cpp11`` is a deprecated alias for ``Latest``
3968 * ``LS_Auto`` (in configuration: ``Auto``)
3969 Automatic detection based on the input.
3973 **StatementAttributeLikeMacros** (``List of Strings``) :versionbadge:`clang-format 12`
3974 Macros which are ignored in front of a statement, as if they were an
3975 attribute. So that they are not parsed as identifier, for example for Qts
3980 AlignConsecutiveDeclarations: true
3981 StatementAttributeLikeMacros: []
3982 unsigned char data = 'x';
3983 emit signal(data); // This is parsed as variable declaration.
3985 AlignConsecutiveDeclarations: true
3986 StatementAttributeLikeMacros: [emit]
3987 unsigned char data = 'x';
3988 emit signal(data); // Now it's fine again.
3990 **StatementMacros** (``List of Strings``) :versionbadge:`clang-format 8`
3991 A vector of macros that should be interpreted as complete
3994 Typical macros are expressions, and require a semi-colon to be
3995 added; sometimes this is not the case, and this allows to make
3996 clang-format aware of such cases.
3998 For example: Q_UNUSED
4000 **TabWidth** (``Unsigned``) :versionbadge:`clang-format 3.7`
4001 The number of columns used for tab stops.
4003 **TypenameMacros** (``List of Strings``) :versionbadge:`clang-format 9`
4004 A vector of macros that should be interpreted as type declarations
4005 instead of as function calls.
4007 These are expected to be macros of the form:
4013 In the .clang-format configuration file, this can be configured like:
4015 .. code-block:: yaml
4017 TypenameMacros: ['STACK_OF', 'LIST']
4019 For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
4021 **UseCRLF** (``Boolean``) :versionbadge:`clang-format 11`
4022 Use ``\r\n`` instead of ``\n`` for line breaks.
4023 Also used as fallback if ``DeriveLineEnding`` is true.
4025 **UseTab** (``UseTabStyle``) :versionbadge:`clang-format 3.7`
4026 The way to use tab characters in the resulting file.
4030 * ``UT_Never`` (in configuration: ``Never``)
4033 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
4034 Use tabs only for indentation.
4036 * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
4037 Fill all leading whitespace with tabs, and use spaces for alignment that
4038 appears within a line (e.g. consecutive assignments and declarations).
4040 * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``)
4041 Use tabs for line continuation and indentation, and spaces for
4044 * ``UT_Always`` (in configuration: ``Always``)
4045 Use tabs whenever we need to fill whitespace that spans at least from
4046 one tab stop to the next one.
4050 **WhitespaceSensitiveMacros** (``List of Strings``) :versionbadge:`clang-format 12`
4051 A vector of macros which are whitespace-sensitive and should not
4054 These are expected to be macros of the form:
4060 In the .clang-format configuration file, this can be configured like:
4062 .. code-block:: yaml
4064 WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE']
4066 For example: BOOST_PP_STRINGIZE
4068 .. END_FORMAT_STYLE_OPTIONS
4070 Adding additional style options
4071 ===============================
4073 Each additional style option adds costs to the clang-format project. Some of
4074 these costs affect the clang-format development itself, as we need to make
4075 sure that any given combination of options work and that new features don't
4076 break any of the existing options in any way. There are also costs for end users
4077 as options become less discoverable and people have to think about and make a
4078 decision on options they don't really care about.
4080 The goal of the clang-format project is more on the side of supporting a
4081 limited set of styles really well as opposed to supporting every single style
4082 used by a codebase somewhere in the wild. Of course, we do want to support all
4083 major projects and thus have established the following bar for adding style
4084 options. Each new style option must ..
4086 * be used in a project of significant size (have dozens of contributors)
4087 * have a publicly accessible style guide
4088 * have a person willing to contribute and maintain patches
4093 A style similar to the `Linux Kernel style
4094 <https://www.kernel.org/doc/Documentation/CodingStyle>`_:
4096 .. code-block:: yaml
4101 BreakBeforeBraces: Linux
4102 AllowShortIfStatementsOnASingleLine: false
4103 IndentCaseLabels: false
4105 The result is (imagine that tabs are used for indentation here):
4117 do_something_else();
4123 do_something_completely_different();
4134 A style similar to the default Visual Studio formatting style:
4136 .. code-block:: yaml
4140 BreakBeforeBraces: Allman
4141 AllowShortIfStatementsOnASingleLine: false
4142 IndentCaseLabels: false
4158 do_something_else();
4164 do_something_completely_different();