Content outdated
For up-to-date documentation see Options, Text Editor, C/C++, Formatting – Visual Studio (Windows).Note that Visual Studio also supports EditorConfig, which works in a similar way. ClangFormat, however, has a much larger variety of style options than EditorConfig, including some very C++ specific rules that can be set, and it is already used by C++ developers today.
You can use multiple ClangFormat files to apply different styling rules at different locations in your codebase, if desired, by placing files in different folders. Any given code file will be styled by the ClangFormat file closest to it in the directory tree. We run the ClangFormat utility in the background to do the formatting, so you get all of ClangFormat’s features right away.
We also provide a way to enforce the built-in formatting conventions that ClangFormat ships with (LLVM, Google, Chromium, Mozilla, or WebKit) without requiring a separate ClangFormat file. This is the same as having the file there with the -style switch set to one of these conventions. This can be configured in Tools > Options.
Using the .clang-format file in the screenshot above, here is a before and after representation of a code sample when Format Document is invoked on it:
Some of the noticeable changes here include the maximum column width (now set to 50), and the presence of the opening curly brace on the same line as the header preceding it.
How to get started
If you already have a .clang-format or _clang-format file in your codebase, you will notice Visual Studio uses it for formatting immediately, as soon as you make an edit in your code that would trigger a formatting operation. ClangFormat also runs if you run the Format Document (Ctrl+K, Ctrl+D) or Format Selection (Ctrl + K, Ctrl + F) commands from the Edit menu or keyboard shortcuts manually in Visual Studio.
If you don’t already have a sample file to get started with, there is a handy website that features an interactive .clang-format file builder and guide to ClangFormat styling options in general. For the complete list of ClangFormat style options, visit the official documentation.
Tools > Options configuration
There are a number of configurations you can make in Tools > Options to control your ClangFormat experience. You can find them at Tools > Options > Text Editor > C/C++ > Formatting.
By default, Visual Studio will use any existing ClangFormat file in your source tree for formatting operations. To turn this off, you can uncheck Enable ClangFormat support. By default, ClangFormat will also emulate Visual Studio formatting, reacting to characters like braces ({}) and semicolons to format as you type. You can change this to have it only use ClangFormat for explicit Format Document and Format Selection commands by choosing Run ClangFormat only for manually invoked formatting commands.
The Default formatting style allows you to control your formatting experience if you do not have a .clang-format or _clang-format file in your source tree. We will always prefer that file if it exists, but if we cannot find it, we will use the formatting convention selected in that option. By default, Visual Studio is selected, meaning we do what Visual Studio usually does for formatting and do not run ClangFormat at all. However, you can also specify LLVM, Google, Chromium, Mozilla, or WebKit coding conventions as well. These function the same as having a ClangFormat file with its style property set to one of these options, with no other alterations, so in this case we’re running ClangFormat with just that setting on. So, if you’re using one of these default styles and are not planning on deviating from its rules, make the selection in Tools > Options and you’re good to go without the ClangFormat file.
Give us feedback
This feature is currently out in Preview. Please try it out and let us know if you run into any issues by reporting them via Help > Send Feedback > Report A Problem from inside the Visual Studio IDE. You can view active issues, comment on them and upvote them on Developer Community.
Post Changelog – March 14, 2018: added note mentioning what version of clang-format.exe we ship.
![YongKang Zhu [MSFT]](https://devblogs.microsoft.com/cppblog/wp-content/uploads/sites/9/letter-avatar/33361fbdd81eeb6a51ff1b2ac4e640b9.svg){kind=avatar}
terribly slow, if you want to really type or paste code the only way is to disable clang in this situations, otherwise you will get random few seconds blocks with message about clang formatting
anyway than manually selecting and formatting few lines of code (recently added) makes different output as formatting the whole file
the same in different words: also with clang completely switched on it is sometimes hard to get formatting as expected (and...
Is there a way to specify custom path for .clang-format file. Both in case of using visual studio installed clang-format executable or custom executable.?
It seems like we have to put it in project path which it automatically picks up.
We have a setup, where we need to give a custom path, as we will be updating it regularly.
When any of the options:
- "Automatically indent when I type a tab"
- "Automatically format statement when I type a ;"
- "Automatically format block when I type a }"
- "Automatically format braces when they are automatically completed"
is selected along with the option "Run ClangFormat for all formatting scenarios", format changes may be made outside of the block of code or statement being edited. This is disconcerting, and does not occur when...
Is there any way to have visual studio use a default .clangformat file when there’s none found in the source tree? (currently, VS defaults to the basic style selected in Options, e.g. Google)
I just want all my local projects to use the same (custom) formatting without needing to remember to copy .clangformat files around.
Clang searches the directory tree it’s invoked in for the first .clang-format file it finds. If you have a .clang-format at the base directory where you have all your projects, that would be used as default.
When using WinRT (C++/CX), I don’t see a way to format ref’s like “^”.
That’s because WinRT stuff is specific to the Visual Studio compiler; clang doesn’t support these features, so the formatter can’t either.
Is there option to have ignore files list ?
Please prefer clang-format.exe from PATH as well in Visual Studio.https://github.com/microsoft/vscode-cpptools/issues/3569
There’s a workaround:
Under “Options” – “Text Editor” – “C/C++” – “Formatting” – “General” you can select the “Use custom clang-format.exe file” check-box and provide any clang-format you like.
Available at least from VS 15.9.21, but maybe it’s been present in some previous versions, too.
Regards