This is just a quick summary on how to use clang-format and in particular git clang-format on a Windows machine.
clang-format is a great and flexible tool to format your code automatically. jetbrains summarizes it well:
“Clang-Format is a widely-used C++ code formatter. As it provides an option to define code style options in YAML-formatted files — named .clang-format … — these files often become a part of your project where you keep all code style rules.”
I believe it speeds up development as I can just type away and then auto-format rather than having to manually indent and align things. This is especially useful if you are refactoring old code, but also when writing new code. I puts the code in a standard format which in turn makes it easier to read and understand. No more lines that are 200 characters wide!
For reference, my currently used .clang-format file can be found here.
Installing clang-format on Windows using LLVM
Getting clang-format running on Windows is fairly easy, as it’s contained in the LLVM compiler. Simply download and install LLVM to the default path, using either their installer or better yet, using winget with a simple:winget install -e --id LLVM.LLVM -y
Once installed, it can be either added to PATH to run from anywhere in the command line. Assuming you are using Visual Studio Code (which you should!), using clang-format is very easy using Clang-Format extension:
- Install the extension
- Set the correct executable path using
"clang-format.executable": "c:\\Program Files\\LLVM\\bin\\clang-format.exe" - (optional) Place a .clang-format file in your workspace directory, if none is present the default style options will be used
- right-click in any source file and click “Format Document” or use the keyboard shortcut Shift+Alt+F
Using git clang-format
I use clang-format all the time, but my coworkers are less strict and thus I often end up with poorly formatted code and once I make code changes I will also format the code. However, that messes up the git commit with changes that are not related to what I am actually working on. This makes it harder for my coworkers to identify what changes I made and makes the commit history messy in general.
Recently, I have stumbled over a better way to coerce my coworkers into using clang-format, whether they like it or not: git-clang-format. It’s been there alongside clang-format the whole time, but only the “Format your code – all the time” blog post by Erik Larsson made me aware of it.
In short, git clang-format enables you to automatically run formatting on all files changes during a commit. So once you commit and push your code, it will be formatted correctly and thus the code changes and the correct formatting are contained in the same commit.
Running git clang-format on Linux is as simple as calling git clang-format, but with our LLVM install things are a tiny bit more tricky. git-clang-format is actually a python script, thus it requires a “Python 2.7 or Python 3” installation. The file can be found alongside clang-format in the LLVM bin folder (“C:\Program Files\LLVM\bin\git-clang-format” in my case).
To use it in your current workspace, just copy it in your root directory. From the interactive terminal or a normal PowerShell window, you can run python .\git-clang-format
but you will get an error message saying “error: cannot find executable “clang-format””. However, we can provide a path to the script, and that should do the trick:
python .\git-clang-format --binary 'C:\Program Files\LLVM\bin\clang-format.exe'
If you have not changed any code since your last commit, you will get the message “clang-format did not modify any files”. Now, change some files but DO NOT run code-formatting yourself. When running the above command again, the script is very helpful, as it will notice the changes and will list them, but will also inform you that you need to “Please commit, stage, or stash them first.”
Go ahead and stage your changes. Running the above command yet again, we finally succeed:
You will have to stage the changed files again and you are ready to commit your properly formatted code!
Introduction
clang-format is a tool for formatting source code of C-like languages including C, C++ and Java, it support user defined syntax rules. It’s part of the LLVM compiler toolchain suite. On Waterloo Rocketry, we used this tool for format C firmware code, to enforce team C syntax rule. This tutorial is based on assumption that you have git bash setup in case of you are on Windows, because the shell(bash) is required for running shell scripts. We are currently using clang-format version 19.
Install Clang-format on Debian/Ubuntu Linux
Open a terminal and run sudo apt install clang-format-19.
Install Clang-format on Windows
Go to LLVM GitHub release page , download latest LLVM 19 Windows release LLVM-19.x.x-win64.exe, run this installer.
In the LLVM install page, select “Add LLVM to the system PATH for all users”, and select a location that you would like to install LLVM, and wait for installation to finish.
Install Clang-format on MacOS
Coming soon
Test the Clang-format installation
Go to shell and type clang-format –version, the output should be clang-format Version 19.x.x, Which x is the minor version number.
Running clang-format on a CAN firmware repository
For PIC18 projects: Assuming the rocketlib git submodule is added to the root of the cansw_* git repository, run cd rocketlib/scripts to change current directory to the rocketlib scripts directory, then run ./format.sh to format firmware code. Then all cansw and rocketlib code should be formatted, but not mcc_generated_files and canlib.
Just as Black and isort can be used to format Python code, clang-format can be used to format C/C++/C# code (and more1).
Quick start §
- Install
clang-format. - Run
clang-format -i <file>to format a single file in-place.- If you omit
-i, the output is printed to stdout.
- If you omit
- Use
--style=<string>to choose from a predefined style.- Options are:
LLVM,GNU,Google,Chromium,Microsoft,Mozilla,Webkit. - Preview styles here in your browser.
- Options are:
- Or, define your own style in a
.clang-formatfile.- Use
--style=fileto load a style from a.clang-formatfile.- Note that
clang-formatwill search for a file with the exact name.clang-formatin the current working directory, and if it does not find one, will go up one directoy (..), and repeat.- To avoid this search behaviour, and instead explicitly specify the file, use
--style=file:<file path>.
- To avoid this search behaviour, and instead explicitly specify the file, use
- Note that
- Generate a
.clang-formatpopulated with a predefined style with:clang-format --style=Chromium --dump-config > .clang-format.- This will contain every single rule.
- Alternatively, you may write your own
.clang-formatand only specify the rules you need.
- Use
Formatting multiple files (Bash, Linux) §
Commonly you want to format multiple source files.
Using clang-format -i *.c will only find *.c files in the current directory.
To format *.c and *.h files recursively, you can use find:
clang-format -i --style=file $(find app src include | grep -E ".*(\.c|\.h)$")To skip any files with third_party in the filename:
clang-format -i --style=file $(find app src include | grep -E ".*(\.c|\.h)$" | grep --invert-match "third_party")Formatting multiple files (Windows, PowerShell) §
Likewise, to run clang-format on all matching source files recursively using PowerShell, while filtering out files with third_party in the filename:
clang-format -i --style=file $(Get-ChildItem -Path $PWD/app,$PWD/src,$PWD/include -Recurse | Where Name -Match '\.(?:h|c)$' | Where FullName -NotMatch 'third_party' | Select-Object -ExpandProperty FullName)Default style §
The default style for clang-format is LLVM. This fact is buried deep within the docs2, inside the description for RawStringFormats:
If
BasedOnStyleis not found, the formatting is based onLLVMstyle.
This is further confirmed by this line within clang/lib/Format/Format.cpp:
const char *DefaultFallbackStyle = "LLVM";Sorting includes §
The styles LLVM and Chromium will sort includes by default, but the other styles will not.
Sorting includes is enabled by setting SortIncludes to CaseSensitive or CaseInsensitive (see the docs for the difference). It is disabled with Never.
Beware that naïvely sorting includes can have unintended side-effects, but using IncludeCategories gives you control over how the includes are ordered. So if the include order matters, as long as you correctly configure IncludeCategories, you can still enable SortIncludes.
Beware that, when sorting includes, the whitespace between #include lines is potentially significant, for two reasons:
- The
IncludeBlocksoption configures howclang-formathandles whitespace between otherwise consecutive lines of#includes. - If
#includes are separated by something else (e.g. an#ifdef) thenclang-formatwill handle each block of includes separately. (Or perhaps it just does the first block? TBC).
There is special handling for the main #include for a source file (e.g. the main #include for "foo/widget.c" is "foo/widget.h"):
clang-formatwill attempt to find the main include for the file.- The regex defined by
IncludeIsMainRegexis used to determine whether an#includeis main, and if so, it is given priority0(i.e. highest, go to the top).- For the
LLVMstyle, this defaults to(Test)?$, which would permit the main include for both"Widget.c"and"WidgetTest.c"to be"Widget.h". - For the
Googlestyle, this defaults to([-_](test|unittest))?$, which would permit the main include for"widget-test.c,"widget_test.c","widget-unittest.c» and"widget_unittest.c"to be"widget.h".
- For the
- All
#includes are considered for being the main include. The deciding function strips off the surrounding""or<>from the include, and then checks that matches the filename. If a match is found, it is then put through the regex defined inIncludeIsMainRegex. If that passes, only then is it considered a main include.- See the implementation for more details.
Install clang-format §
Install clang-format on Windows §
Go to the LLVM releases page and download the Windows LLVM installer.
For example, at time of writing v18.1.8 is the latest release. The download named clang+llvm-18.1.8-x86_64-pc-windows-msvc.tar.xz includes LLVM and clang (and clang-format).
Install clang-format on Debian/Ubuntu §
It’s as easy as:
sudo apt install clang-formatExample .clang-format §
Following is an example of a hand-written .clang-format. It’s written in YAML:
---
BasedOnStyle: LLVM
# Alignment.
AlignAfterOpenBracket: AlwaysBreak
AlignConsecutiveMacros: true
AlignConsecutiveAssignments: true
AlignConsecutiveDeclarations: true
AlignEscapedNewlines: Right
AlignOperands: true
AlignTrailingComments: true
# Allow one-liners for case labels.
AllowShortCaseLabelsOnASingleLine: true
# Indentation.
IndentWidth: 4
ContinuationIndentWidth: 4
UseTab: Never
# Always list each argument on its own line.
BinPackArguments: false
BinPackParameters: false
ExperimentalAutoDetectBinPacking: false
AllowAllParametersOfDeclarationOnNextLine: false
# Spaces.
SpaceAfterCStyleCast: false
SpaceBeforeParens: ControlStatements
SpacesBeforeTrailingComments: 2
SpacesInCStyleCastParentheses: false
SpacesInContainerLiterals: false
SpacesInSquareBrackets: false
# Breaks.
BreakBeforeBraces: Mozilla
BreakBeforeBinaryOperators: NonAssignment
# Sorting includes.
# * The main header gets priority 0, and goes at the top. The main header is
# essentally any header file which corresponds to the current source file
# (e.g "foo.h" is the main header for "foo.c"). However, only header files
# that match the regex in `IncludeIsMainRegex` are considered.
# * The "log/mod/blah.h" headers get priority 1.
# * The "blah.h" headers get priority 2.
# * The <blah.h> headers get priority 3.
SortIncludes: CaseSensitive
IncludeBlocks: Regroup
IncludeIsMainRegex: '$?'
IncludeCategories:
- Regex: '^"log/mod/.*"'
Priority: 1
- Regex: '^".*"'
Priority: 2
- Regex: '^<.*>'
Priority: 3
# Misc.
IndentCaseLabels: true
ReflowComments: trueFor a guide as to what each rule means, try this tool, and click the blue information icon next to the rule in question.
README
Clang-Format is a tool to format C/C++/Java/JavaScript/Objective-C/Objective-C++/Protobuf code. It can be configured with a config file named .clang-format within the working folder or a parent folder. Configuration see: http://clang.llvm.org/docs/ClangFormatStyleOptions.html
Usage
This extension allows clang-format (version 3.8 or higher) to be used to format C/C++, Javascript etc.
source files directly from within Visual Studio Code.
Files can be formatted on-demand by right clicking in the document and
selecting «Format Document», or by using the associated keyboard shortcut
(usually Ctrl+⇧+F on Windows, Ctrl+⇧+I on Linux, and ⇧+⌥+F on macOS).
To automatically format a file on save, add the following to your
vscode settings.json file:
{
"editor.formatOnSave": true
}
Specifying the location of clang-format
This extension will attempt to find clang-format on your PATH.
Alternatively, the clang-format executable can be specified in your vscode
settings.json file:
{
"clang-format.executable": "/absolute/path/to/clang-format"
}
Placeholders can also be used in the clang-format.executable value.
The following placeholders are supported:
${workspaceRoot}— replaced by the absolute path of the current vscode
workspace root.${workspaceFolder}— replaced by the absolute path of the current vscode
workspace. In case of outside-workspace files${workspaceFolder}expands
to the absolute path of the first available workspace.${cwd}— replaced by the current working directory of vscode.${env.VAR}— replaced by the environment variable $VAR, e.g.${env.HOME}
will be replaced by$HOME, your home directory.
Some examples:
${workspaceRoot}/node_modules/.bin/clang-format— specifies the version of
clang that has been added to your workspace bynpm install clang-format.${env.HOME}/tools/clang38/clang-format— use a specific clang format version
under your home directory.
Placeholders are also supported in clang-format.assumeFilename. The supported
placeholders are ${file}, ${fileNoExtension}, ${fileBasename},
${fileBasenameNoExtension}, and ${fileExtname}, with the same meaning as the
predefined variables in other configuration files.
For example:
${fileNoExtension}.cpp—/home/src/foo.hwill be formatted with
-assume-filename /home/src/foo.cpp.
Installing Clang-Format
On Linux, one can simply run sudo apt install clang-format.
On Windows, the simplest way is to install LLVM to the default path either using the installer or by simply running winget install -e --id LLVM.LLVM using winget.
LLVM contains the clang-format binary, the resulting pat for the clang-format.executable then becomes:
{
"clang-format.executable": "c:\\Program Files\\LLVM\\bin\\clang-format.exe"
}
Source code
Available on github: https://github.com/xaverh/vscode-clang-format-provider
About This Article
- Go to https://visualstudio.microsoft.com/vs/preview/.
- Click Download Preview under «Community.»
- Open the downloaded file.
- Click Continue.
- Click to check the box next to Desktop development with C++.
- Click to check the box next to C++ Clang tools for Windows.
- Click Install.
- Is Clang available on Windows?
- How do I run Clang format on Windows?
- Is Clang better than GCC?
- How do I install Clang format?
- Where is Clang installed?
- Where is Clang installed Windows?
- Is GCC and Clang the same?
- Can you compile Linux with Clang?
- How do I add clang-format to Visual Studio?
- Where is clang-format PY?
- Does Clang require GCC?
- Why does Apple use Clang?
Is Clang available on Windows?
The following details setting up for and building Clang on Windows using Visual Studio: Get the required tools: Git. Source code control program.
How do I run Clang format on Windows?
Getting Started with Clang-Format
The shortcut Ctrl+Shift+I is for Linux. If you want to use it on Windows, you need to use Alter+Shift+F. If you do not have Clang-Format installed on your system, you will see the prompt: The ‘clang-format’ command is not available.
Is Clang better than GCC?
Clang is much faster and uses far less memory than GCC. Clang aims to provide extremely clear and concise diagnostics (error and warning messages), and includes support for expressive diagnostics. GCC’s warnings are sometimes acceptable, but are often confusing and it does not support expressive diagnostics.
How do I install Clang format?
You can install clang-format and git-clang-format via npm install -g clang-format . To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc . It should work on macOS/Linux/Windows.
Where is Clang installed?
By default, clang-cl.exe is located in %VCINSTALLDIR%\Tools\Llvm\bin\ and %VCINSTALLDIR%\Tools\Llvm\x64\bin\.
Where is Clang installed Windows?
Use the default install location: C:\Program Files\LLVM . Once the installation completes hit ‘Finish’. clang++.exe should be located in C:\Program Files\LLVM\bin , which should be in your system PATH.
Is GCC and Clang the same?
GCC is a program language compiler developed by GNU. … Clang is a C, C++, Objective-C, or Objective-C++ compiler that is compiled in C++ based on LLVM and released under the Apache 2.0 license. Clang is mainly used to provide performance superior to that of GCC.
Can you compile Linux with Clang?
The Linux kernel has always traditionally been compiled with GNU toolchains such as GCC and binutils. Ongoing work has allowed for Clang and LLVM utilities to be used as viable substitutes. Distributions such as Android, ChromeOS, and OpenMandriva use Clang built kernels.
How do I add clang-format to Visual Studio?
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.
Where is clang-format PY?
Standalone Tool
clang-format is located in clang/tools/clang-format and can be used to format C/C++/Obj-C code.
Does Clang require GCC?
Clang is a completely separate compiler (written entirely from scratch, using LLVM). You don’t need GCC to use Clang, as can be shown in the case of FreeBSD (they completely replaced GCC with Clang/LLVM and don’t install GCC in the base anymore for licensing reasons).
Why does Apple use Clang?
The Clang Compiler is an open-source compiler for the C family of programming languages, aiming to be the best in class implementation of these languages. Clang builds on the LLVM optimizer and code generator, allowing it to provide high-quality optimization and code generation support for many targets.