From 3357bd88888fdcf4a86d59f34f32b9b8cef7207d Mon Sep 17 00:00:00 2001 From: Adrien Leravat Date: Mon, 24 Jun 2019 13:17:51 -0700 Subject: [PATCH] README.md: Add supported arguments and examples Add supported arguments Update examples after changing entry points arguments --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 55 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 01e3907..6fdfb2d 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,75 @@ Docker image verifying the code format with clang-format ## Getting Started -The following command will mount the current working directory folder to the `src` working directory, and check its format +The following command will mount the current working directory folder to the `src` working directory, and recursively check the format of source files in `src` and `include` directories, as well as `file.cpp` -`docker run --rm -v $(pwd):/src witekio/clang-format-checker` +`docker run --rm -v $(pwd):/src witekio/clang-format-checker -r src includes file.cpp` -The return code will be +## 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 ``` -$ docker run -v $(pwd):/src --rm witekio/clang-format-checker 2 ↵ +# 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() -+MyClass::MyClass() -- : arg(new Other(std::string("string"), 4)) +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](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) + +## Supported arguments + +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 +``` +For more information, you can check [`run-clang-format` official repository](https://github.com/Sarcasm/run-clang-format). + ## CI Integration ### BitBucket Pipeline @@ -41,18 +88,6 @@ pipelines: - run-clang-format.py -r src ``` -## Changing the 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](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) - -## Specify the files to check - -Check recursively .h/.cpp files excluding `vendors` folder - -`docker run --rm -v $(pwd):/src witekio/clang-format-checker "--extensions=h,cpp --exclude vendors"` - -For more information, you can check [`run-clang-format`](https://github.com/Sarcasm/run-clang-format) repository - ## License This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details