Setting up git-clang-format
I am draconian when it comes to code formatting. Combined with an “I’ll know it when I see it” attitude, this can become irritating. In exasperation, a colleague suggested using
clang-format to automatically format our Objective C codebase. Their proposal:
I’ll get the tool’s formatting specification as close to what you like as possible. In return, you agree that you’ll accept what the tool produces.
So, quite some time ago, we introduced a clang-formatting file to our repository.
Huge, horrible whitespace monsters
Originally we suggested using a plugin for Xcode to format code. This is a pretty great tool, but we had a problem: it was hard to format just the lines that had been changed, leading to frustration picking apart “real” changes from white space changes.
The other day I came across a script to solve this problem, from the LLVM team themselves, git-clang-format. It’s a python script that hooks into git to give you a
git clang-format command, which runs
clang-format over the changes staged for commit.
Surprisingly — to me at least — it’s really easy to install a git extension:
- Call the script something starting with
- Put it in your path.
- Make it executable.
git-clang-format, the process runs something like this:
- Install the standalone
brew install clang-format.
git-clang-formatfrom here. Read it to check for nastiness.
- Move the script somewhere in your path, for me
mv git-clang-format ~/bin/git-clang-format.
- Make the script executable:
chmod +x ~/bin/git-clang-format.
- Check it’s been picked up by git:
git clang-format -h.
- Try it out with:
git clang-format --diff.
You can now run
clang-format, which will modify your working copy, rather than your staged files. This allows for easy backing out of the changes it makes.
> git status On branch 45845-reusable-fetcher Your branch is up-to-date with 'origin/45845-reusable-fetcher'. Changes to be committed: (use "git reset HEAD
..." to unstage) modified: Classes/common/CDTFetchChanges.h > git clang-format changed files: Classes/common/CDTFetchChanges.h
Running on every commit
The final step is to make sure
clang-format is run before each commit. Some may want to just run the tool on every commit, but I’m happier with a simple reminder.
Following some instructions from Atlassian, I wrote a simple git pre-commit hook which runs
git clang-format --diff, aborting the commit if something other than
no modified files to format or
clang-format did not modify any files is returned. Rather fragile, but as long as I don’t update my
git-clang-format script, it should continue working.
#!/usr/bin/env python import subprocess output = subprocess.check_output(["git", "clang-format", "--diff"]) if output not in ['no modified files to format\n', 'clang-format did not modify any files\n']: print "Run git clang-format, then commit.\n" exit(1) else: exit(0)
Git stores commit hooks on a per-repository basis, inside the
.git folder of the repository. So we need to add this script there, and make it executable:
cp check_formatting.sh .git/hooks/pre-commit
chmod -x .git/hooks/pre-commit
Once all this is in place, if you try to make a commit with which
clang-format finds an issue the commit will be aborted. Of course, you could be more or less terse in your message:
> git commit -m "Documentation updates" Run git clang-format, then commit.
Given how lax I am at keeping to my own standards, this is invaluable.