Can clang-format tell me if formatting changes are necessary?

Is there an way that you can run clang-format in a mode where it reports if the file meets the specified format? A kind of dry-run mode where it reports if a change is needed, but doesn't make the change. Ideally I'd like clang-format to just return a non-zero exit code if the file needs changes. Or, even more ideally, a non-zero exit code and a list of the files that need changes on standard output.

I'm trying to keep the question generic, so that more people can answer, but what I am trying to do is write a git pre-commit hook that will reject any commits that don't match the expected .clang-format . It's easy to run clang-format on the list of files in the index. But it's hard to know if clang-format actually changed anything.

I have one potential solution based on -output-replacements-xml (that I will post as an answer), but it's a hack and I feel like this should be more straightforward. Comments/suggestions, edits, different answers/approaches are all welcome.

One of the reasons I feel like this should be easier than it is because -output-replacements-xml essentially gives me the answer that I want, it just doesn't give it to me in an easy to consume way. However, since the output if no replacements are needed is very predictable, parsing the output isn't too hard.

What I have right now is

clang-format -style=file -output-replacements-xml | grep -c "<replacement " >/dev/null

This actually returns the inverse of the exit code I want, since grep returns 0 if something matches, 1 if nothing does. But that is easy enough to deal with.

So the relevant bit of my git pre-commit hook would be

git diff --cached --name-only --diff-filter=ACMRT |
  grep "\.[cmh]$" |
  xargs -n1 clang-format -style=file -output-replacements-xml |
  grep "<replacement " >/dev/null
if [ $? -ne 1 ]; then 
    echo "Commit did not match clang-format"
    exit 1
fi

1. Get the full filenames of the files in the index (excluding files that are being deleted and other unusual cases where I might not want to process the file)
2. Only keep the filenames of things I want to check the formatting of (in my case just c,m, and h files)
3. Run the results through xargs to essentially "for each" the next command
4. Run clang-format with the -output-replacements-xml option on all of the files
5. Search for replacement (as opposed to replacements) that indicates that clang-format has found a replacement that it wants to make. (Discarding all output as the XML won't be meaningful to the user.)
6. The last command exits 1 (grep says we found nothing) we are done and things are fine.
7. If not, display a message and exit 1, which cancels the commit. Unfortunately we don't have an easy way to tell the user which file was the problem, but they can run clang-format themselves and see.

Starting with clang-format-10, you can use the --dry-run and -Werror command line options. They will cause ClangFormat to output any formatting violations to stdout and return a non-zero exit status if any input file was not correctly formatted.

$ clang-format --dry-run --Werror foo.cpp
foo.cpp:129:23: error: code should be clang-formatted [-Wclang-format-violations]
        if (rc <= 0) {
$ echo $?
1

Originally from my website here: <https://rigtorp.se/notes/clang-format/>

run-clang-format is a simple wrapper around clang-format designed precisely to be used as a hook or as a continuous integration script: it outputs a diff and exits with a sensible status.

The example given on the home page speaks for itself:

I am not entirely sure what your use case is, but check out git-clang-format (https://llvm.org/svn/llvm-project/cfe/trunk/tools/clang-format/git-clang-format). It basically provides a clang-format integration for git and maybe that is what you are looking for.

Command Line

You can use git diff along with clang-format-diff:

$ git diff -U0 --no-color --staged HEAD | clang-format-diff -p1

Note:

• --staged is used to run clang-format-diff only on the staged changes
• If you want to run this command on specific directories, you can rewrite it as:

$ git diff -U0 --no-color --staged HEAD -- $PWD/dir1 $PWD/dir2 $PWD/dir3  | clang-format-diff -p1

..and the pre-commit

Now you pre-commit can be this one:

#!/bin/bash

dir_list="$PWD"  # Add the directories you want here
cmd="git diff -U0 --no-color --staged HEAD -- $dir_list | clang-format-diff -p1"

echo ""
echo "Running clang-format on this commit"
echo ""

# Execute the format command
diff=$(eval "$cmd")
if [[ $? -ne 0 ]]
then
    echo "Command failed to execute."
    exit 1
fi

# Print the outcome
if [[ -z "$diff" ]]
then
    echo "Everything is clean"
    exit 0
else
    echo "$diff"
    echo ""
    echo "Commit aborted due to code format inconsistencies."
    exit 1
fi

I slightly adjusted the comment from phs in this post to come up with:

find embedded/ -regex '.*\.\(ino\|cpp\|hpp\|cc\|cxx\|h\)' -exec cat {} \; | diff -u <(find embedded/ -regex '.*\.\(ino\|cpp\|hpp\|cc\|cxx\|h\)' -exec clang-format-3.9 -style=file {} \;) -

that is..

1. cat all cpp-ish files and pipe that to diff (diff will accept stdin because I specify - at the end)
2. use process substitution (the <( .. ) syntax) to run clang-format on those same files. Don't use in-place formatting here. This is the other half that's sent to diff
3. if diff exits with no output, success! You can also check the exit code via $? -- it should be zero.

I have my CI service (travis) run this line in a bash script to make sure things are formatted properly. I have another script for actually running the formatter in-place. This reminds me of a caveat: you must use a shell that can do process sub (the posix shell does not).

I use git-clang-format and a pre-commit script from Mike Rhodes' blog:

#!/bin/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)

The script has a small error in that it doesn't work when there are no commits (trying to check against HEAD which doesn't exist yet). To bypass this, use the -n or --no-verify option.

Using -n to skip the pre-commit script can also be helpful when you what to bypass the check because it can take a long time for a large codebase.

The original post is here: http://www.dx13.co.uk/articles/2015/4/3/Setting-up-git-clang-format.html

After I got inspired by David Ogren's post I made a pre-commit hook that is able to work on the staged changes. This will ensure that the pre-commit hook will work on the code that will actual make up the content of the commit and can't be fooled by a clang-format run that didn't get staged.

#!/bin/bash

files=()
for file in `git diff --cached --name-only --diff-filter=ACMRT | grep -E "\.(cpp|hpp)$"`; do
  if ! cmp -s <(git show :${file}) <(git show :${file}|clang-format); then
    files+=("${file}")
  fi
done

if [ -n "${files}" ]; then
echo Format error within the following files:
printf "%s\n" "${files[@]}"
exit 1
fi

You can simply use the -n option

clang-format -n <file>