clangformat: Add include and ignore files

1 files changed, 43 insertions, 0 deletions

diff --git a/docs/markdown/snippets/clang-format.md b/docs/markdown/snippets/clang-format.md
new file mode 100644
index 0000000..8cb88e0
--- /dev/null
+++ b/docs/markdown/snippets/clang-format.md
@@ -0,0 +1,43 @@
+## clang-format include and ignore lists
+
+When clang-format is installed and a `.clang-format` file is found at the main
+project's root source directory, Meson automatically adds a `clang-format` target
+that reformat all C and C++ files.
+
+It is now possible to restrict files to be reformatted with optional
+`.clang-format-include` and `.clang-format-ignore` files.
+
+The file `.clang-format-include` contains a list of patterns matching the files
+that will be reformatted. The `**` pattern matches this directory and all
+subdirectories recursively. Empty lines and lines starting with `#` are ignored.
+If `.clang-format-include` is not found, the pattern defaults to `**/*` which
+means all files recursively in the source directory but has the disadvantage to
+walk the whole source tree which could be slow in the case it contains lots of
+files.
+
+Example of `.clang-format-include` file:
+```
+# All files in src/ and its subdirectories
+src/**/*
+
+# All files in include/ but not its subdirectories
+include/*
+```
+
+The file `.clang-format-ignore` contains a list of patterns matching the files
+that will be excluded. Files matching the include list (see above) that match
+one of the ignore pattern will not be reformatted. Unlike include patters, ignore
+patterns does not support `**` and a single `*` match any characters including
+path separators. Empty lines and lines starting with `#` are ignored.
+
+The build directory and file without a well known C or C++ suffix are always
+ignored.
+
+Example of `.clang-format-ignore` file:
+```
+# Skip C++ files in src/ directory
+src/*.cpp
+```
+
+Modified files will be printed on the console which can be used for example by
+CI to ensure all files are correctly formatted.