README.md: Add supported arguments and examples

Add supported arguments
Update examples after changing entry points arguments
This commit is contained in:
Adrien Leravat 2019-06-24 13:17:51 -07:00 committed by GitHub
parent fe6fdfbbb5
commit 3357bd8888
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -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