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!