From f55868927721f273640a3ba7a8e703d418a352b6 Mon Sep 17 00:00:00 2001
From: Xavier Claessens <xavier.claessens@collabora.com>
Date: Tue, 9 Mar 2021 13:15:06 -0500
Subject: clangformat: Add include and ignore files

---
 docs/markdown/Code-formatting.md       | 58 ++++++++++++++++++++++++++++++++++
 docs/markdown/snippets/clang-format.md | 43 +++++++++++++++++++++++++
 docs/sitemap.txt                       |  1 +
 3 files changed, 102 insertions(+)
 create mode 100644 docs/markdown/Code-formatting.md
 create mode 100644 docs/markdown/snippets/clang-format.md

(limited to 'docs')

diff --git a/docs/markdown/Code-formatting.md b/docs/markdown/Code-formatting.md
new file mode 100644
index 0000000..c8d83de
--- /dev/null
+++ b/docs/markdown/Code-formatting.md
@@ -0,0 +1,58 @@
+---
+short-description: Code formatting
+...
+
+# clang-format
+
+*Since 0.50.0*
+
+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 (currently only with Ninja backend).
+
+```sh
+ninja -C builddir clang-format
+```
+
+*Since 0.58.0*
+
+It is 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
+```
+
+Note that `.clang-format-ignore` has the same format as used by
+[`run-clang-format.py`](https://github.com/Sarcasm/run-clang-format).
+
+Modified files will be printed on the console which can be used for example by
+CI to ensure all files are correctly formatted.
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.
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index de98cd0..29c54c4 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -32,6 +32,7 @@ index.md
 		Build-options.md
 		Subprojects.md
 		Disabler.md
+		Code-formatting.md
 		Modules.md
 			CMake-module.md
 			Cuda-module.md
-- 
cgit v1.1