clang-format-checker-docker

This Docker image let you verify that your code matches the format from clang-format, in an easy way, as part of your CI pipeline. The clang-format versions supported can be found on the "Tags" page of the image.

Getting Started

The simplest use of this image is to check source files in the current folder, after mounting it with -v. The example below checks all files in the current folder (.), and recursively (-r):

docker run --rm -v $(pwd):/src witekio/clang-format-checker -r .

Arguments after the image name are passed directly to run-clang-format.py. You can target multiple folders and files. The example below will recursively analyze files in the src and includes folder, as well as the file main.cpp.

docker run --rm -v $(pwd):/src witekio/clang-format-checker -r src includes main.cpp

CI Integration

BitBucket Pipeline

The following BitBucket Pipeline step will check for any style error in the src folder, and return an error if problems are found

pipelines:
  default:
    - step:
        name: Check code format
        image: witekio/clang-format-checker
        script:
          - run-clang-format.py -r src

GitLab CI Pipeline

The following GitLab CI step will check for any style error in the src folder, and return an error if problems are found

check-format:
  image:
    name: witekio/clang-format-checker
    entrypoint: [""]
  script:
    - run-clang-format.py -r src

Output

The return code of the docker run will be:

• non-zero if any formatting errors are found, and printed in the standard output.
• 0 if no issue was found

# Recursively check all files from current folder
$ docker run -v $(pwd):/src --rm witekio/clang-format-checker -r .                                 2 ↵
--- ./testCode/File.cpp	(original)
+++ ./testCode/File.cpp	(reformatted)
@@ -3,18 +3,13 @@
 
 #include "MyHeader.h"
MyClass::MyClass()
-    : arg(new    Other( std::string(  "string"),      4))
+  : arg(new Other(std::string("string"), 4))

Specifying the code style

The style used by clang-format can be defined by providing a .clang-format file in your source folder. For more information, see clang-format style options

Supported arguments

This image relies on run-clang-format. For more information, you can check run-clang-format official repository.

Folders and files can be excluded with --exclude

# Check recursively .h/.cpp files excluding 'vendors' folder and '*_test.cpp'
docker run -v $(pwd):/src --rm witekio/clang-format-checker -r  --exclude src/third_party --exclude '*_test.cpp' src include foo.cpp

run-clang-format.py help

usage: run-clang-format.py [-h] [--clang-format-executable EXECUTABLE]
                           [--extensions EXTENSIONS] [-r] [-q] [-j N]
                           [--color {auto,always,never}] [-e PATTERN]
                           file [file ...]

A wrapper script around clang-format, suitable for linting multiple files and
to use for continuous integration. This is an alternative API for the clang-
format command line. It runs over multiple files and directories in parallel.
A diff output is produced and a sensible exit code is returned.

positional arguments:
  file

optional arguments:
  -h, --help            show this help message and exit
  --clang-format-executable EXECUTABLE
                        path to the clang-format executable
  --extensions EXTENSIONS
                        comma separated list of file extensions (default:
                        c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx)
  -r, --recursive       run recursively over directories
  -q, --quiet
  -j N                  run N clang-format jobs in parallel (default number of
                        cpus + 1)
  --color {auto,always,never}
                        show colored diff (default: auto)
  -e PATTERN, --exclude PATTERN
                        exclude paths matching the given glob-like pattern(s)
                        from recursive search

Building manually

To build manually this image, you can clone this repository, and run make. Other supported Makefile targets are:

• make build [TAG=latest]: Build the image, and use the specified tag, or latest
• make push [TAG=latest]: Push the image to Docker HUB registry
• make run [TAG=latest] [CMD="-r ."]: Run the image locally after mounting the current folder. run-clang-format arguments can be customized with CMD="<args>"

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• This Docker container uses run-clang-format from https://github.com/Sarcasm/run-clang-format