clang-format: format C++ with a .clang-format file

clang-format is the LLVM tool that rewrites C++ source code into one layout: indentation, spacing, line breaks, brace placement and, by default, the order of #include lines. Run clang-format -i main.cpp to format a file in place. It reads its rules from a .clang-format file in the file’s folder or a parent, and uses the LLVM style when it finds none.

Here is main.cpp, typed in a hurry: indents of 2 to 8 spaces, two brace styles, Item * beside Item*, operators without spaces. It builds and prints total: 1340 cents.

#include <string>
#include <iostream>

struct Item {
  std::string name;
      int qty;
  int price_cents;
};

int order_total(const Item *items,int count){
    int total=0;
  for(int i=0;i<count;++i)
  {
        const Item* item = &items[i];
        total += item->qty*item->price_cents;
  }
    return total;
}

int main()
{
    Item cart[] = {{"pen",3,120},{"pad",2,450},{"ink",1,80}};
      std::cout<<"total: "<<order_total(cart,3)<<" cents\n";
}

Format it in place:

clang-format -i main.cpp

clang-format printed nothing and rewrote the file:

#include <iostream>
#include <string>

struct Item {
  std::string name;
  int qty;
  int price_cents;
};

int order_total(const Item *items, int count) {
  int total = 0;
  for (int i = 0; i < count; ++i) {
    const Item *item = &items[i];
    total += item->qty * item->price_cents;
  }
  return total;
}

int main() {
  Item cart[] = {{"pen", 3, 120}, {"pad", 2, 450}, {"ink", 1, 80}};
  std::cout << "total: " << order_total(cart, 3) << " cents\n";
}

That is the LLVM style, because no .clang-format existed in the folder or above it: two-space indents, opening braces at the end of the line, the * beside the name, spaces around operators. It also sorted the two #include lines, <iostream> before <string>: all seven predefined styles sort includes.

Both versions are C++17 and print total: 1340 cents when built with MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++); Since When has the first compiler release of each C++ feature. The clang-format runs here used clang-format 19.1.5, the copy Visual Studio 2022’s C++ Clang tools install. clang-format handles layout; clang-tidy, its sibling linter, checks what the code does.

Where does the .clang-format file go?

Put it at the root of your project. For each source file, clang-format uses the .clang-format or _clang-format in the closest folder going up from that file (Clang-Format Style Options), so a subfolder of vendored code can carry its own:

The nearer file replaces the farther one whole: a subfolder file holding only IndentWidth: 2 gave the LLVM style with that one change and nothing from the root’s file. Start it with BasedOnStyle: InheritParentConfig to build on the parent’s file instead. clang-format --dump-config src/main.cpp prints the settings a file gets.

The file is YAML: a BasedOnStyle line naming the style to start from, then only the options you change. This one keeps LLVM’s rules but indents by four, allows 100 columns, puts the * beside the type and each block’s opening brace on its own line:

BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 100
PointerAlignment: Left
BreakBeforeBraces: Allman

With it in the project folder, clang-format -i main.cpp turned the first program into this (main changes the same way):

struct Item
{
    std::string name;
    int qty;
    int price_cents;
};

int order_total(const Item* items, int count)
{
    int total = 0;
    for (int i = 0; i < count; ++i)
    {
        const Item* item = &items[i];
        total += item->qty * item->price_cents;
    }
    return total;
}

A misspelt key is an error, not a warning: with PointerAlignmnet: Left, clang-format printed error: unknown key 'PointerAlignmnet', exited with status 1 and left the file untouched. Enumerated values are case-sensitive, so PointerAlignment: left fails too, with unknown enumerated scalar.

What are the clang-format styles?

clang-format has seven predefined styles: LLVM, GNU, Google, Chromium, Microsoft, Mozilla and WebKit. clang-format --style=google --dump-config prints every option of a style. Here is how three of them set the options people change, as clang-format 19.1.5 dumped them:

Microsoft’s Custom braces go on their own line after classes, structs, functions, control statements, namespaces and enums, but not unions. Google’s DerivePointerAlignment: true follows the side a file already uses most: on a file that wrote Item * both times, --style=google kept Item *.

To start your own file, redirect a dump into .clang-format and edit it; the cheat sheet has the command for Git Bash and for PowerShell.

Which clang-format options do people change?

These six set indentation, line length, braces, pointers, include order and one-line functions; Clang-Format Style Options documents every other option.

On clang-format 19.1.5, SortIncludes takes those single words, and Never keeps the order you typed. Today’s documentation marks them deprecated in favor of a nested form (Enabled, IgnoreCase), which 19.1.5 rejected with unknown enumerated scalar, formatting nothing: check the documentation for your release.

How do you turn clang-format off for a block?

Put // clang-format off and // clang-format on around lines whose layout carries meaning, such as a matrix written row by row. The lines between keep their layout, indentation included; the two comments themselves are formatted. Both matrices below were typed in the same aligned rows, and the project’s .clang-format was applied:

// clang-format off
const int sobel_x[3][3] = {{ -1,  0,  1 },
                           { -2,  0,  2 },
                           { -1,  0,  1 }};
// clang-format on
const int sobel_y[3][3] = {{-1, -2, -1}, {0, 0, 0}, {1, 2, 1}};

sobel_y, outside the markers, came out on one line. A reason may follow a colon, as in // clang-format off: one row per line, and /* clang-format off */ works as well.

How do you check formatting in CI?

Run clang-format --dry-run --Werror on the files: it changes nothing, reports each place that would change, and exits with status 1 if there is one. On the unformatted main.cpp it printed 40 diagnostics for 24 lines; the first two:

main.cpp:1:1: error: code should be clang-formatted [-Wclang-format-violations]
#include <string>
^
main.cpp:5:20: error: code should be clang-formatted [-Wclang-format-violations]
  std::string name;
                   ^

1:1 is the include order; 5:20 is the end of line 5, where line 6’s wrong indent begins. The exit status was 1, and on the formatted file the same command printed nothing and exited 0. Without --Werror the same places are warnings and the status is 0, so a CI step without it passes unformatted code.

To check a whole tree in Git Bash, run find . \( -name '*.cpp' -o -name '*.h' \) -exec clang-format --dry-run --Werror {} +. To format only the lines you changed, the ClangFormat documentation gives git clang-format, which with no arguments formats your staged changes.

How do you use clang-format in VS Code, Visual Studio and CLion?

All three can use the project’s .clang-format:

• VS Code’s C/C++ extension formats with clang-format by default (an .editorconfig with formatting settings switches it to vc_format), with its style set to file; with no file, its C_Cpp.clang_format_fallbackStyle setting applies (Editing and Navigating C++ Code). Turn on editor.formatOnSave to format on every save.
• Visual Studio has ClangFormat support on by default and uses a .clang-format file in a project folder for that folder and its subfolders; Format Document is Ctrl+K, Ctrl+D (Visual Studio’s C/C++ formatting options).
• CLion, once you enable ClangFormat in its status bar (it is off by default), reads .clang-format and _clang-format files through the project tree, each applying to its folder and below (CLion’s ClangFormat help).

To choose among them, see which C++ IDE to install; Toolchain lists the compilers, IDEs and analyzers a C++ team installs, and Tooling has more answers on builds and analysis.

A clang-format cheat sheet